GitHub Actions 실패, AI 코딩 초보가 3분 만에 로그 읽는 5단계

GitHub에 push한 뒤 Actions가 빨갛게 실패하면 초보자는 보통 두 화면 사이에서 멈춥니다. 하나는 수백 줄 로그이고, 다른 하나는 AI 채팅창입니다. 이때 전체 로그를 그대로 붙여 넣으면 AI도 실패한 지점을 넓게 추측합니다. 먼저 3분만 써서 job, step, 실행 명령, 첫 에러 줄, 비밀값 경계를 나누면 질문이 짧아지고 수정 범위도 작아집니다.

Tap to zoom

docs.github.com의 GitHub Actions 문서는 workflow run 화면에서 각 job의 상태와 로그를 확인할 수 있다고 안내합니다. workflow 문법도 job 아래에 step이 있고, step 안에서 run 명령이나 action을 실행하는 구조입니다. 그러므로 처음 볼 것은 YAML 전체가 아닙니다. 빨간 job 하나와 빨간 step 하나입니다.

30초 안에 실패한 job 이름부터 적습니다

Actions 화면에서 실패한 run을 열면 build, test, lint, deploy 같은 job 이름이 보입니다. 여기서 빨간 표시가 붙은 job을 먼저 적습니다.

실패한 job: build

이 한 줄이 중요한 이유는 간단합니다. build가 실패했는데 배포 토큰을 고치면 문제와 멀어집니다. test가 실패했는데 화면 CSS를 다시 만들게 해도 수정 범위가 넓어집니다. AI에게는 먼저 이렇게 묻습니다.

GitHub Actions에서 실패한 job은 build입니다.
아직 파일 수정은 하지 말고, 이 job이 어떤 종류의 실패인지 분류해 주세요.

이 단계의 목표는 원인을 확정하는 것이 아닙니다. 어느 방에서 문제가 났는지 고르는 것입니다. 방을 고르지 않고 "Actions가 실패했어요"라고 말하면 AI도 저장소 전체를 훑으려 합니다.

1분째에는 빨간 step과 실행 명령을 분리합니다

job 안에는 여러 step이 있습니다. Checkout, Setup Node, Install dependencies, Run build, Run tests처럼 보일 수 있습니다. 초보자는 step 이름과 실제 실행 명령을 같이 적어야 합니다.

실패한 step: Run build
실행 명령: npm run build

docs.github.com의 GitHub Actions workflow syntax 문서 기준으로 step의 run은 runner에서 명령을 실행합니다. 그래서 npm run build가 실패했다면 우선 로컬에서도 같은 명령을 다시 실행해 볼 수 있습니다.

npm run build

로컬에서도 같은 오류가 나면 코드나 설정 문제일 가능성이 큽니다. 로컬은 통과하는데 Actions에서만 실패하면 Node 버전, 환경변수, runner 환경, 대소문자 파일명처럼 CI 환경 차이를 봐야 합니다. 여기서 중요한 경계는 실패한 명령 하나만 떼어내는 것입니다.

Vercel 배포 실패 로그에서 멈춘 지점을 찾는 순서도 같은 원리를 씁니다. 배포 로그든 Actions 로그든 먼저 멈춘 지점과 실행 명령을 떼어내야 AI 질문이 짧아집니다.

2분째에는 첫 에러 줄만 복사합니다

로그 맨 아래에는 요약 실패 문구가 자주 나옵니다. 예를 들어 Process completed with exit code 1은 실패했다는 결과이지, 원인 자체가 아닙니다. 위로 조금 올라가서 처음 빨갛게 의미 있는 줄을 찾습니다.

첫 에러:
src/index.ts:10:15 - error TS2322: Type 'string' is not assignable to type 'number'.

이 줄에는 파일, 위치, 에러 종류, 기대값과 실제값이 들어 있습니다. 반대로 아래처럼만 주면 AI가 다시 추측해야 합니다.

Process completed with exit code 1

처음에는 전체 로그를 다 읽으려 하지 않아도 됩니다. 첫 에러 줄이 Module not found라면 import나 설치 문제로 좁힙니다. Type ... is not assignable이면 타입 정의와 실제 값을 봅니다. Missing environment variable이면 배포 환경의 변수 이름과 등록 위치를 봅니다. 첫 에러 줄은 수정 방향을 고르는 신호입니다.

Tap to zoom

3분째에는 비밀값을 가리고 AI에게 줄 묶음을 만듭니다

배포나 테스트 job은 secret, token, API key 이름을 다룰 때가 있습니다. docs.github.com의 secrets 안내는 민감한 값을 repository나 organization secret으로 저장해 workflow에서 사용한다고 설명합니다. AI에게 줄 때는 값이 아니라 이름과 위치만 남깁니다.

이제 아래 형식으로 질문합니다.

GitHub Actions 실패를 고치기 전에 원인을 좁히고 싶습니다.

실패한 job: build
실패한 step: Run build
실행 명령: npm run build
첫 에러 줄:
[첫 에러 줄 붙여 넣기]

로컬 결과:
[같은 명령을 로컬에서 실행했을 때 성공/실패]

주의:
secret 값은 공유하지 않겠습니다. 필요한 경우 secret 이름과 등록 위치만 확인해 주세요.

요청:
바로 파일을 고치기보다 원인 후보를 3개로 줄이고,
각 후보마다 확인할 파일이나 설정을 하나씩만 알려 주세요.

이 프롬프트의 핵심은 "고쳐줘"가 아니라 원인 후보를 줄여 달라는 요청입니다. 초보자가 가장 많이 손해 보는 순간은 AI가 workflow 파일, package.json, 앱 코드, 배포 설정을 한꺼번에 바꾸는 때입니다. 먼저 원인을 줄이면 수정 파일도 줄어듭니다.

AI 코드 저장 전 바뀐 파일과 위험 변경을 먼저 보는 기준에서 다룬 변경 범위 점검도 여기와 이어집니다. Actions 실패도 수정 전에는 원인 후보와 파일 범위를 작게 잡아야 합니다.

로컬 재현 결과로 다음 행동을 고릅니다

마지막으로 로컬에서 같은 명령을 실행한 결과를 기준으로 다음 행동을 나눕니다.

Actions 실패는 한 번에 고치는 문제가 아닙니다. 먼저 실패한 job을 고르고, step과 command를 분리하고, 첫 에러 줄을 찾고, secret 값을 가린 뒤 AI에게 묻습니다. 오늘은 전체 로그를 붙여 넣지 말고 이 5줄만 채웁니다.

job:
step:
command:
첫 에러:
로컬 재현:

이 5줄을 채운 뒤 질문하면 AI는 "CI가 실패했어요"가 아니라 "어느 명령이 어느 파일에서 왜 멈췄는지"를 보고 답할 수 있습니다.

참고 출처

• GitHub Docs, Viewing workflow run history: https://docs.github.com/actions/managing-workflow-runs/viewing-workflow-run-history
• GitHub Docs, Workflow syntax for GitHub Actions: https://docs.github.com/actions/writing-workflows/workflow-syntax-for-github-actions
• GitHub Docs, Using secrets in GitHub Actions: https://docs.github.com/actions/security-guides/using-secrets-in-github-actions