저장소가 하나일 때는 CI 파일을 복사해도 큰 문제가 없다. 테스트 명령 하나를 고치면 한 곳만 보면 되기 때문이다. 하지만 서비스가 늘어나면 같은 테스트 단계가 조금씩 달라진다. 어떤 저장소는 Node 버전이 다르고, 어떤 저장소는 secrets 이름이 다르고, 어떤 저장소는 실패했을 때만 알림을 보낸다. 이때부터 YAML을 잘 쓰는 문제보다, 공통 규칙을 어디에 둘지의 문제가 된다.
복사한 CI는 처음에는 빠르지만 나중에 서로 달라진다
복사한 설정이 나쁜 것은 아니다. 프로젝트마다 다른 테스트와 배포 조건이 있으니 완전히 하나로 합치려 하면 오히려 이해하기 어려워진다. 문제는 서로 같아야 하는 부분까지 제각각이 되는 순간이다. 예를 들어 모든 서비스가 같은 린트 규칙을 써야 하는데, 누군가 한 저장소에서만 버전을 올리면 다음 오류는 예상보다 멀리서 시작된다.
코드 리뷰와 자동 검증의 역할이 궁금하다면 PR과 테스트 자동화의 변화, 에이전트에 필요한 맥락을 다룬 컨텍스트와 하네스 엔지니어링, 리서치를 업무 흐름으로 바꾸는 PM의 AI 리서치 방식도 연결해서 읽을 수 있다.
재사용 워크플로는 무엇을 공통으로 두는 방식인가
GitHub Actions의 재사용 워크플로는 여러 job과 step을 포함한 워크플로 전체를 다른 워크플로에서 호출하게 해 준다. 일반 액션이 job 안의 작은 단계라면, 재사용 워크플로는 테스트나 배포 전 검사처럼 하나의 흐름을 공통으로 두는 데 가깝다. 호출받을 파일에는 workflow_call을 두고, 각 저장소는 job에서 그 파일을 부른다.
| 공통으로 두기 좋은 것 | 각 저장소에 남겨 둘 것 |
|---|---|
| 테스트 순서와 결과 요약 | 실행할 명령과 설정 파일 경로 |
| 공통 린트나 검사 도구 | 서비스별 환경 변수와 배포 조건 |
| 실패 알림의 형식 | 누가 어떤 알림을 받을지 |
이 구분이 중요한 이유는 공통 파일을 바꿨을 때다. 재사용 워크플로 하나의 변경이 여러 저장소에 영향을 줄 수 있으므로, 공통 부분은 적고 명확할수록 좋다.
입력값과 secrets는 호출하는 쪽에서 읽기 쉽게 남긴다
공식 문서는 호출받는 워크플로에 입력값과 secrets를 정의하고, 호출하는 job에서 uses, with, secrets를 이용해 값을 넘기는 구조를 안내한다. 여기서 헷갈리기 쉬운 것은 공통 파일이 모든 것을 알아서 처리해야 한다고 생각하는 일이다. 실제로는 각 저장소가 무엇을 넘기는지 한눈에 보이는 편이 유지보수에 유리하다.
jobs:
test:
uses: org/ci/.github/workflows/reusable-ci.yml@main
with:
config-path: .github/test.yml
위 예시는 구조를 보여 주기 위한 최소 형태다. 실제 참조는 팀의 버전 관리 방식에 맞춰 고정해야 한다. 공통 워크플로의 수정과 호출 저장소의 수정이 따로 움직인다는 점도 문서와 변경 기록에 남겨 두면 좋다.
권한을 한 번에 넓히지 않는 이유
재사용 워크플로를 부를 때 권한 설정을 생략하면 호출 job의 기본 GITHUB_TOKEN 권한이 적용될 수 있다. GitHub 문서는 호출된 워크플로가 호출 쪽보다 권한을 더 높일 수 없다고 설명한다. 그래서 공통 파일이 편하다는 이유만으로 넓은 권한을 공통값으로 두기보다, 필요한 저장소에서 필요한 권한을 읽을 수 있게 적는 편이 낫다.
이 글은 특정 보안 설정을 대신 판단하지 않는다. 조직의 정책, 사용하는 액션, 저장소 공개 범위에 따라 필요한 권한이 달라진다. 대신 누가 무엇을 호출하고 어떤 입력을 넘기는지는 코드 리뷰에서 읽을 수 있도록 남겨 두자는 것이 핵심이다.
처음 옮길 때는 테스트 하나부터 시작한다
처음부터 배포까지 공통화하면 문제가 생겼을 때 원인을 찾기 어렵다. 실패해도 외부 서비스에 영향을 주지 않는 테스트나 린트 하나를 옮긴 뒤, 호출 저장소 두 곳에서 같은 결과가 나오는지 보는 편이 낫다. 그 다음에 공통 파일의 입력값을 줄이고, 문서에 사용 예를 더하면 된다.
자세한 형식은 GitHub의 reusable workflow 안내, 호출 job의 제약과 권한은 재사용 워크플로 레퍼런스, 워크플로 전반의 문법은 workflow syntax 문서에서 다시 확인할 수 있다. 이 글은 2026년 8월 22일에 해당 공식 문서를 기준으로 정리했다.