GitHub Actions 기초

5. 자주 하는 실수 (Tip)

❌ 실수 1. 워크플로 파일을 .github/workflows/ 밖에 둠

Actions 는 정확히 이 경로만 스캔합니다. .github/actions/ci.yml 처럼 폴더 이름이 조금만 달라도 아예 인식하지 못합니다.

❌ 실수 2. on: push 만 걸고 pull_request 를 빼먹음

리뷰 중인 PR 에서는 검증이 한 번도 안 돌아, 병합 직전에야 문제를 발견합니다. 검증용 워크플로는 두 이벤트를 함께 거는 것이 기본입니다.

❌ 실수 3. 시크릿 값을 조합해 로그에 남김

${{ secrets.TOKEN }} 원문은 마스킹되지만, base64 로 인코딩하거나 다른 문자열과 합치면 마스킹을 피해갈 수 있습니다. 시크릿은 가공 없이 필요한 스텝에만 넘깁니다.

❌ 실수 4. run: 과 uses: 를 헷갈림

uses: npm install 처럼 쓰면 액션 이름으로 해석돼 즉시 실패합니다. 셸 명령은 항상 run:, 마켓플레이스 액션은 항상 uses: 입니다.

❌ 실수 5. 매트릭스를 쓰고도 runs-on 값을 하나로 고정

버전별 병렬 실행 자체는 되지만, 러너 종류(OS)까지 매트릭스에 넣지 않으면 OS 차이로 나는 버그는 여전히 못 잡습니다. 필요하면 os 도 매트릭스에 추가합니다.

❌ 실수 6. 캐시 key 를 고정 문자열로 씀

key: m2-cache 처럼 고정하면 의존성이 바뀌어도 옛 캐시를 계속 씁니다. hashFiles() 로 의존성 파일 내용을 키에 반영해야 합니다.

❌ 실수 7. 액션 버전을 태그 없이 @main 으로 씀

uses: actions/checkout@main 은 그 액션이 갱신될 때마다 동작이 바뀔 수 있습니다. @v4 처럼 메이저 버전 태그로 고정해야 빌드가 갑자기 깨지지 않습니다.

❌ 실수 8. workflow_dispatch 만 걸고 자동 트리거를 빼먹음

배포처럼 사람이 눌러야 하는 잡이 아니라면, 자동 트리거 없이 수동 실행만 걸어두면 커밋마다 깜빡 잊고 실행을 안 시킵니다.

❌ 실수 9. 아티팩트 path 를 잘못 지정

빌드 출력 폴더 이름을 바꿨는데 path 를 안 고치면 upload-artifact 가 빈 아티팩트를 올리고도 성공으로 표시됩니다. 잡 로그의 업로드 파일 개수를 확인하는 습관이 필요합니다.

❌ 실수 10. schedule 의 cron 시각을 로컬 시간으로 착각

cron: '0 3 * * 1' 은 UTC 기준 월요일 03:00 이고, 한국 시간으로는 12:00 입니다. 시간대를 안 따지면 배치가 엉뚱한 시각에 돕니다.