재사용 가능한 워크플로우 완벽 가이드

GitHub Actions에서 워크플로우를 재사용하는 방법을 배웁니다. workflow_call 이벤트부터 조직 전체 공유, 버전 관리까지 실무에서 바로 활용할 수 있는 패턴을 익힙니다.

---

목차

1. workflow_call 이벤트
2. inputs와 secrets 정의
3. outputs 반환하기
4. 조직 전체 워크플로우
5. 버전 관리 전략
6. 템플릿 저장소 활용

---

1. workflow call 이벤트

김개발 씨는 회사에서 세 개의 프로젝트를 담당하고 있습니다. 그런데 이상하게도 세 프로젝트 모두 CI/CD 파이프라인이 거의 똑같습니다.

테스트 실행하고, 빌드하고, 배포하는 코드가 복사-붙여넣기 수준으로 중복되어 있었습니다. "이거 하나 고치려면 세 군데 다 고쳐야 하네..."

workflow_call은 한마디로 워크플로우를 함수처럼 호출할 수 있게 해주는 이벤트입니다. 마치 자주 쓰는 코드를 함수로 만들어 여러 곳에서 호출하는 것과 같습니다.

이것을 제대로 이해하면 중복 코드를 획기적으로 줄이고, 유지보수를 한 곳에서 할 수 있게 됩니다.

다음 코드를 살펴봅시다.

# .github/workflows/reusable-build.yml
name: Reusable Build Workflow

on:
  workflow_call:  # 이 이벤트가 핵심입니다
    # 다른 워크플로우에서 호출할 수 있게 됩니다

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build

김개발 씨는 입사 6개월 차 주니어 개발자입니다. 요즘 그의 고민은 CI/CD 파이프라인 관리입니다.

프로젝트가 늘어날수록 똑같은 워크플로우 파일을 복사해서 붙여넣어야 했거든요. 어느 날, 보안팀에서 Node.js 버전을 18에서 20으로 올리라는 공지가 내려왔습니다.

김개발 씨는 한숨을 쉬었습니다. "세 개 프로젝트 다 수정해야 하네..." 그때 선배 개발자 박시니어 씨가 다가왔습니다.

"혹시 workflow_call 써봤어요? 그거 쓰면 한 번만 고치면 돼요." 그렇다면 workflow_call이란 정확히 무엇일까요?

쉽게 비유하자면, workflow_call은 마치 회사의 공용 문서 템플릿과 같습니다. 모든 부서가 각자 보고서 양식을 만드는 대신, 총무팀에서 공식 템플릿 하나를 만들어두면 모두가 그걸 가져다 쓰는 것처럼요.

템플릿이 바뀌면 모든 부서의 문서가 자동으로 새 양식을 따르게 됩니다. workflow_call이 없던 시절에는 어땠을까요?

개발자들은 새 프로젝트를 시작할 때마다 기존 프로젝트의 워크플로우 파일을 복사해왔습니다. 처음에는 괜찮았습니다.

하지만 시간이 지나면서 각 프로젝트의 워크플로우가 조금씩 달라지기 시작했습니다. 누군가는 캐시 설정을 추가했고, 누군가는 테스트 단계를 수정했습니다.

더 큰 문제는 보안 업데이트나 버전 변경이 필요할 때였습니다. 열 개의 프로젝트가 있다면 열 번 수정해야 했습니다.

하나라도 빠뜨리면 그 프로젝트만 구버전으로 돌아가는 사태가 벌어졌습니다. 바로 이런 문제를 해결하기 위해 workflow_call 이벤트가 등장했습니다.

workflow_call을 사용하면 하나의 워크플로우를 여러 프로젝트에서 공유할 수 있습니다. 수정이 필요할 때는 원본 워크플로우만 고치면 됩니다.

이를 호출하는 모든 프로젝트에 자동으로 적용됩니다. 위의 코드를 살펴보겠습니다.

가장 중요한 부분은 on: workflow_call: 입니다. 이 한 줄이 일반 워크플로우를 재사용 가능한 워크플로우로 바꿔줍니다.

push나 pull_request 같은 이벤트 대신 workflow_call을 트리거로 지정한 것입니다. 이제 다른 워크플로우에서 이 파일을 호출할 수 있습니다.

uses: ./.github/workflows/reusable-build.yml 한 줄이면 됩니다. 실제 현업에서는 어떻게 활용할까요?

대부분의 회사에서 빌드, 테스트, 배포 파이프라인은 프로젝트마다 크게 다르지 않습니다. 이런 공통 작업을 재사용 가능한 워크플로우로 만들어두면, 새 프로젝트를 시작할 때 몇 줄의 설정만으로 완성된 CI/CD 파이프라인을 갖출 수 있습니다.

하지만 주의할 점도 있습니다. workflow_call 이벤트만 있는 워크플로우는 직접 실행되지 않습니다.

반드시 다른 워크플로우에서 호출해야 합니다. 테스트할 때는 workflow_dispatch 이벤트를 함께 추가해두면 수동으로도 실행할 수 있어 편리합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언대로 공용 워크플로우를 만든 김개발 씨는 이제 Node.js 버전을 한 곳에서만 수정하면 됩니다.

세 프로젝트 모두 자동으로 새 버전을 사용하게 되었습니다.

실전 팁

💡 - workflow_call과 workflow_dispatch를 함께 정의하면 호출도 되고 수동 실행도 가능합니다

• 재사용 워크플로우는 별도의 저장소에 모아두면 관리하기 편합니다

---

2. inputs와 secrets 정의

김개발 씨가 만든 재사용 워크플로우가 인기를 끌기 시작했습니다. 그런데 문제가 생겼습니다.

A팀은 Node.js 20을 쓰고 싶어하고, B팀은 아직 18 버전을 유지해야 했습니다. "버전별로 워크플로우를 따로 만들어야 하나?" 김개발 씨는 고민에 빠졌습니다.

inputs와 secrets는 재사용 워크플로우에 파라미터를 전달하는 방법입니다. 마치 함수에 인자를 넘기는 것처럼, 워크플로우를 호출할 때 필요한 값을 외부에서 주입할 수 있습니다.

inputs는 일반 설정값을, secrets는 민감한 정보를 전달할 때 사용합니다.

다음 코드를 살펴봅시다.

# .github/workflows/reusable-deploy.yml
name: Reusable Deploy

on:
  workflow_call:
    inputs:
      node-version:
        description: 'Node.js 버전'
        required: false
        default: '20'
        type: string
      environment:
        description: '배포 환경'
        required: true
        type: string
    secrets:
      AWS_ACCESS_KEY:
        required: true
      AWS_SECRET_KEY:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - name: Deploy to ${{ inputs.environment }}
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_KEY }}
        run: npm run deploy:${{ inputs.environment }}

김개발 씨는 재사용 워크플로우의 가능성에 흥분했습니다. 하지만 현실은 녹록지 않았습니다.

팀마다 Node.js 버전이 다르고, 배포 환경도 개발, 스테이징, 프로덕션으로 나뉘어 있었거든요. "버전별로, 환경별로 워크플로우를 다 만들면 오히려 더 복잡해지는 거 아닌가요?" 김개발 씨가 물었습니다.

박시니어 씨가 웃으며 대답했습니다. "함수에 파라미터를 넘기듯이, 워크플로우에도 값을 전달할 수 있어요.

inputs와 secrets를 쓰면 돼요." inputs와 secrets가 정확히 무엇일까요? 쉽게 비유하자면, inputs는 마치 카페에서 음료를 주문할 때 선택하는 옵션과 같습니다.

"아이스 아메리카노 톨 사이즈로 주세요"처럼 크기와 온도를 지정하는 것이죠. 기본 레시피는 같지만 옵션에 따라 결과물이 달라집니다.

secrets는 조금 다릅니다. 마치 은행 금고 비밀번호처럼 아무에게나 보여주면 안 되는 정보입니다.

AWS 키나 데이터베이스 비밀번호 같은 것들이죠. GitHub Actions는 이런 민감한 정보를 안전하게 전달할 수 있도록 별도의 secrets 채널을 제공합니다.

위의 코드를 자세히 살펴보겠습니다. inputs 섹션에서 node-version과 environment 두 가지 파라미터를 정의했습니다.

node-version은 required가 false이고 default 값이 있어서 생략해도 됩니다. 반면 environment는 required가 true라서 반드시 전달해야 합니다.

secrets 섹션에서는 AWS 접근 키를 정의했습니다. 이 값들은 로그에 출력되지 않고 안전하게 처리됩니다.

호출하는 쪽에서 저장소의 시크릿을 전달해야 합니다. 실제로 이 워크플로우를 호출하는 방법은 다음과 같습니다.

호출하는 워크플로우에서 uses로 재사용 워크플로우를 지정하고, with로 inputs 값을, secrets로 시크릿을 전달합니다. environment에 'production'을 넣으면 프로덕션 배포가, 'staging'을 넣으면 스테이징 배포가 실행됩니다.

type 필드도 중요합니다. string, boolean, number 중 하나를 지정할 수 있습니다.

잘못된 타입의 값이 전달되면 워크플로우가 실패합니다. 이런 타입 체크 덕분에 실수를 미리 방지할 수 있습니다.

주의할 점이 있습니다. secrets는 자동으로 전달되지 않습니다.

호출하는 워크플로우에서 명시적으로 secrets를 넘겨줘야 합니다. secrets: inherit를 사용하면 모든 시크릿을 한 번에 전달할 수 있지만, 보안상 필요한 것만 명시적으로 전달하는 것이 좋습니다.

김개발 씨는 이제 하나의 워크플로우로 모든 팀의 요구사항을 충족할 수 있게 되었습니다. A팀은 node-version에 '20'을, B팀은 '18'을 전달하면 됩니다.

배포 환경도 파라미터 하나로 구분됩니다.

실전 팁

💡 - required가 true인 inputs는 반드시 값을 전달해야 하므로 신중하게 설계하세요

• secrets: inherit보다 필요한 시크릿만 명시적으로 전달하는 것이 보안에 좋습니다

---

3. outputs 반환하기

김개발 씨의 재사용 워크플로우가 배포까지 잘 마쳤습니다. 그런데 배포 후에 Slack으로 알림을 보내려고 하니 문제가 생겼습니다.

배포된 버전 번호나 URL 같은 정보를 어떻게 가져와야 할까요? 재사용 워크플로우 안에서 생성된 값을 밖으로 꺼내올 방법이 필요했습니다.

outputs는 재사용 워크플로우가 호출한 쪽에 값을 반환하는 방법입니다. 마치 함수가 return 값을 돌려주는 것처럼, 워크플로우 실행 결과를 외부로 전달할 수 있습니다.

배포된 URL, 생성된 아티팩트 경로, 버전 번호 등을 반환할 때 유용합니다.

다음 코드를 살펴봅시다.

# .github/workflows/reusable-build-output.yml
name: Reusable Build with Output

on:
  workflow_call:
    outputs:
      artifact-path:
        description: '빌드 결과물 경로'
        value: ${{ jobs.build.outputs.artifact-path }}
      version:
        description: '빌드 버전'
        value: ${{ jobs.build.outputs.version }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact-path: ${{ steps.build.outputs.path }}
      version: ${{ steps.version.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - name: Get version
        id: version
        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
      - name: Build
        id: build
        run: |
          npm ci && npm run build
          echo "path=dist/" >> $GITHUB_OUTPUT

김개발 씨는 배포 파이프라인을 완성하고 뿌듯해하고 있었습니다. 그런데 기획팀에서 요청이 들어왔습니다.

"배포될 때마다 Slack으로 알림 받을 수 있을까요? 버전이랑 URL도 같이요." 간단한 요청 같았지만, 막상 구현하려니 막막했습니다.

버전 정보는 재사용 워크플로우 안에서 추출하는데, 그 값을 어떻게 바깥으로 가져올 수 있을까요? 박시니어 씨가 힌트를 줬습니다.

"함수가 값을 return 하듯이, 워크플로우도 outputs로 값을 반환할 수 있어요." outputs가 정확히 어떻게 동작하는지 살펴봅시다. outputs는 마치 택배 송장과 같습니다.

물건을 보낼 때 송장에 "이 박스에는 무엇이 들어있습니다"라고 적어두면, 받는 사람이 확인할 수 있죠. 워크플로우도 마찬가지입니다.

실행 결과를 outputs에 적어두면 호출한 쪽에서 그 값을 읽을 수 있습니다. 위 코드에서 outputs 정의 방식을 보겠습니다.

워크플로우 수준의 outputs에서 artifact-path와 version 두 가지를 정의했습니다. 각각의 value는 jobs.build.outputs를 참조합니다.

이것은 build 잡의 outputs를 워크플로우 outputs로 연결하는 것입니다. 그렇다면 잡 수준의 outputs는 어떻게 설정할까요?

build 잡에서 outputs 섹션을 보면 steps의 출력을 참조하고 있습니다. 실제 값은 각 스텝에서 $GITHUB_OUTPUT에 기록합니다.

echo "version=1.0.0" >> $GITHUB_OUTPUT 형식으로요. 이 체인을 정리하면 다음과 같습니다.

스텝에서 값 생성, 잡 outputs에서 스텝 값 참조, 워크플로우 outputs에서 잡 값 참조. 세 단계를 거쳐야 외부로 값을 전달할 수 있습니다.

호출하는 쪽에서는 어떻게 사용할까요? 재사용 워크플로우를 호출한 후, needs.빌드잡이름.outputs.artifact-path로 반환값에 접근합니다.

이 값을 Slack 알림이나 후속 작업에서 활용할 수 있습니다. 주의할 점이 있습니다.

outputs는 반드시 문자열입니다. 객체나 배열을 반환하고 싶다면 JSON.stringify로 문자열화한 뒤, 받는 쪽에서 파싱해야 합니다.

또한 outputs 값에는 크기 제한이 있으므로 대용량 데이터는 아티팩트로 저장하고 경로만 반환하는 것이 좋습니다. 김개발 씨는 이제 빌드 워크플로우에서 버전과 경로를 반환받아 Slack 알림에 포함시킬 수 있게 되었습니다.

기획팀도, 개발팀도 모두 만족했습니다.

실전 팁

💡 - outputs 값은 항상 문자열이므로 복잡한 데이터는 JSON으로 직렬화하세요

• 스텝, 잡, 워크플로우 세 단계의 outputs 연결을 정확히 이해해야 합니다

---

4. 조직 전체 워크플로우

김개발 씨의 재사용 워크플로우가 팀 내에서 큰 호응을 얻었습니다. 그러자 다른 팀에서도 "우리도 쓰고 싶다"는 요청이 들어왔습니다.

하지만 워크플로우 파일은 같은 저장소 안에 있어야 하는데, 다른 팀의 저장소에서 어떻게 사용할 수 있을까요?

조직 전체 워크플로우는 하나의 저장소에 있는 워크플로우를 조직 내 모든 저장소에서 공유하는 방법입니다. 마치 회사의 공용 도구함처럼, 중앙 저장소에 워크플로우를 모아두고 누구나 가져다 쓸 수 있게 합니다.

이를 통해 조직 전체의 CI/CD 표준화가 가능해집니다.

다음 코드를 살펴봅시다.

# 호출하는 워크플로우 (다른 저장소)
# .github/workflows/ci.yml
name: CI Pipeline

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    # 조직의 중앙 워크플로우 저장소 참조
    uses: my-org/.github/.github/workflows/standard-build.yml@main
    with:
      node-version: '20'
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  deploy:
    needs: build
    uses: my-org/.github/.github/workflows/standard-deploy.yml@v1.2.0
    with:
      environment: production
    secrets: inherit

김개발 씨의 재사용 워크플로우 소식이 퍼지면서 회사 전체가 술렁이기 시작했습니다. 백엔드팀, 프론트엔드팀, 데이터팀 모두가 "우리도 쓰고 싶다"고 했습니다.

하지만 문제가 있었습니다. 재사용 워크플로우는 같은 저장소 안에서만 참조할 수 있다고 알고 있었거든요.

수십 개의 저장소에 같은 워크플로우를 복사해야 하나? 박시니어 씨가 새로운 방법을 알려줬습니다.

"조직 수준의 .github 저장소를 만들면 돼요. 거기에 워크플로우를 모아두면 모든 저장소에서 참조할 수 있어요." 조직 전체 워크플로우가 어떻게 가능한 걸까요?

GitHub에는 특별한 저장소가 있습니다. 조직 이름과 같은 .github 저장소입니다.

예를 들어 조직 이름이 my-org라면, my-org/.github 저장소를 만들 수 있습니다. 이 저장소는 조직의 기본 설정과 템플릿을 담는 특별한 역할을 합니다.

이 저장소의 .github/workflows 폴더에 재사용 워크플로우를 넣어두면, 조직 내 모든 저장소에서 참조할 수 있습니다. 마치 회사의 공용 서버에 도구를 올려두고 모든 직원이 다운받아 쓰는 것과 같습니다.

위 코드에서 호출 방식을 보겠습니다. uses: my-org/.github/.github/workflows/standard-build.yml@main 이 한 줄이 핵심입니다.

형식은 조직명/저장소명/경로@ref입니다. ref에는 브랜치명, 태그, 커밋 SHA를 넣을 수 있습니다.

경로가 .github/.github/workflows로 중복된 것처럼 보이는데, 이것은 실수가 아닙니다. 첫 번째 .github는 저장소 이름이고, 두 번째 .github/workflows는 저장소 내의 경로입니다.

공개 저장소와 비공개 저장소의 차이도 알아야 합니다. 워크플로우가 있는 저장소가 공개라면 누구나 참조할 수 있습니다.

비공개라면 같은 조직 내의 저장소만 참조할 수 있습니다. 비공개 저장소의 워크플로우를 사용하려면 저장소 설정에서 "Allow access to workflows from other repositories"를 활성화해야 합니다.

실무에서는 어떻게 구성할까요? 대부분의 조직에서 .github 저장소에 다음과 같은 워크플로우를 모아둡니다.

표준 빌드 워크플로우, 표준 테스트 워크플로우, 배포 워크플로우, 보안 스캔 워크플로우 등입니다. 각 팀은 이 표준 워크플로우를 호출하기만 하면 됩니다.

이렇게 하면 보안 정책이나 빌드 방식이 변경될 때 중앙 저장소만 수정하면 됩니다. 수십, 수백 개의 저장소가 자동으로 새 정책을 따르게 됩니다.

DevOps 팀의 업무가 획기적으로 줄어드는 것이죠. 김개발 씨는 이제 회사의 DevOps 표준화를 이끄는 핵심 인물이 되었습니다.

모든 팀이 같은 워크플로우를 사용하니, 협업도 수월해지고 문제 해결도 빨라졌습니다.

실전 팁

💡 - 조직의 .github 저장소를 비공개로 유지하면서 워크플로우 접근을 허용하려면 별도 설정이 필요합니다

• @main보다 @v1.0.0 같은 태그를 사용하면 의도치 않은 변경을 방지할 수 있습니다

---

5. 버전 관리 전략

조직 전체 워크플로우가 성공적으로 도입되었습니다. 그런데 어느 날, 김개발 씨가 워크플로우를 개선하려고 수정했더니 회사 전체 CI가 멈춰버렸습니다.

수십 개 팀에서 동시에 문의가 쏟아졌습니다. "변경 사항을 미리 테스트하고, 안전하게 배포할 방법이 없을까요?"

재사용 워크플로우의 버전 관리 전략은 변경 사항을 안전하게 배포하는 방법입니다. 마치 소프트웨어 릴리스처럼 워크플로우도 버전을 매기고, 호환성을 관리해야 합니다.

시맨틱 버저닝과 브랜치 전략을 조합하면 안정적인 워크플로우 운영이 가능합니다.

다음 코드를 살펴봅시다.

# 워크플로우 저장소의 릴리스 자동화
# .github/workflows/release.yml
name: Release Workflow

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true

# 호출하는 쪽에서의 버전 지정 예시
# uses: my-org/.github/.github/workflows/build.yml@v1.2.0  # 특정 버전
# uses: my-org/.github/.github/workflows/build.yml@v1      # 메이저 버전
# uses: my-org/.github/.github/workflows/build.yml@main    # 최신 (위험)

김개발 씨는 그날의 사고를 잊을 수 없었습니다. 단순히 로깅을 추가하려고 한 줄을 수정했을 뿐인데, 회사 전체 배포가 멈춰버렸습니다.

모든 팀이 @main을 참조하고 있었기 때문입니다. 박시니어 씨가 긴급 회의를 소집했습니다.

"워크플로우도 소프트웨어처럼 버전 관리를 해야 해요. 오늘 일은 좋은 교훈이 되었네요." 왜 버전 관리가 필요할까요?

재사용 워크플로우는 여러 팀이 의존하는 공용 인프라입니다. 마치 도시의 수도관과 같습니다.

수도관을 갑자기 교체하면 모든 가정의 물이 끊기는 것처럼, 워크플로우를 무분별하게 수정하면 모든 팀의 CI/CD가 영향을 받습니다. 시맨틱 버저닝을 적용하면 이 문제를 해결할 수 있습니다.

버전 번호 형식은 MAJOR.MINOR.PATCH입니다. v1.2.3이라면 메이저 1, 마이너 2, 패치 3입니다.

각 숫자는 변경의 성격을 나타냅니다. 패치는 버그 수정처럼 기존 동작에 영향 없는 변경입니다.

마이너는 새 기능 추가처럼 하위 호환성을 유지하는 변경입니다. 메이저는 기존 동작이 바뀌는 호환성 깨지는 변경입니다.

호출하는 쪽에서는 어떻게 버전을 지정할까요? @v1.2.0처럼 정확한 버전을 지정하면 가장 안전합니다.

워크플로우가 바뀌어도 이 버전을 사용하는 저장소는 영향을 받지 않습니다. 업그레이드는 명시적으로 버전을 올려야만 됩니다.

@v1처럼 메이저 버전만 지정하면 v1.x.x 중 최신을 사용합니다. 버그 수정과 새 기능은 자동으로 받지만, 호환성이 깨지는 v2가 나와도 자동으로 적용되지 않습니다.

이것이 가장 실용적인 선택입니다. @main은 항상 최신 코드를 사용합니다.

테스트 중이거나 빠른 피드백이 필요할 때만 사용하세요. 프로덕션 환경에서는 피해야 합니다.

실무에서의 릴리스 프로세스는 어떻게 구성할까요? 먼저 개발 브랜치에서 변경 사항을 작업합니다.

PR을 통해 코드 리뷰를 받고, 테스트 저장소에서 새 워크플로우를 검증합니다. 문제가 없으면 main에 머지하고 태그를 생성합니다.

위 코드의 release 워크플로우가 자동으로 GitHub Release를 생성합니다. 변경 로그도 중요합니다.

어떤 버전에서 무엇이 바뀌었는지 문서화해야 합니다. 호출하는 팀에서 업그레이드 여부를 판단할 수 있어야 하기 때문입니다.

GitHub Release의 자동 릴리스 노트 기능을 활용하면 편리합니다. 김개발 씨는 이제 변경 사항을 신중하게 관리합니다.

작은 수정은 패치 버전으로, 새 기능은 마이너 버전으로, 큰 변경은 메이저 버전으로 릴리스합니다. 더 이상 회사 전체 CI가 멈추는 사고는 일어나지 않았습니다.

실전 팁

💡 - 프로덕션에서는 @v1 형태의 메이저 버전 지정을 권장합니다

• CHANGELOG.md를 유지하면 업그레이드 결정에 도움이 됩니다

---

6. 템플릿 저장소 활용

재사용 워크플로우와 버전 관리가 안정화되었습니다. 그런데 새로운 프로젝트를 시작할 때마다 여전히 설정 작업이 필요했습니다.

워크플로우 호출 파일도 만들어야 하고, 설정 파일도 추가해야 합니다. "아예 처음부터 다 갖춰진 상태로 시작할 수 없을까요?"

템플릿 저장소는 새 프로젝트의 시작점이 되는 미리 구성된 저장소입니다. 마치 아파트 모델하우스처럼, 필요한 것들이 다 갖춰진 상태에서 시작할 수 있습니다.

워크플로우 호출 파일, 설정 파일, 폴더 구조까지 표준화된 형태로 제공됩니다.

다음 코드를 살펴봅시다.

# 템플릿 저장소의 워크플로우
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    uses: my-org/.github/.github/workflows/standard-lint.yml@v1

  test:
    uses: my-org/.github/.github/workflows/standard-test.yml@v1
    with:
      node-version: '20'
      coverage-threshold: '80'

  build:
    needs: [lint, test]
    uses: my-org/.github/.github/workflows/standard-build.yml@v1

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    uses: my-org/.github/.github/workflows/standard-deploy.yml@v1
    with:
      environment: production
    secrets: inherit

김개발 씨의 팀에 신입 개발자 이주니어 씨가 합류했습니다. 첫 업무로 새 마이크로서비스 프로젝트를 시작하게 되었는데, 일주일이 지나도 CI/CD 설정에서 헤매고 있었습니다.

"워크플로우는 어디서 복사해야 하죠? 설정 파일은 뭘 넣어야 하고요?" 이주니어 씨의 질문에 김개발 씨는 고민에 빠졌습니다.

분명 재사용 워크플로우를 만들어뒀는데, 새 프로젝트에서 이것들을 조합하는 것도 일이었습니다. 박시니어 씨가 해결책을 제시했습니다.

"템플릿 저장소를 만들어두세요. 새 프로젝트는 그 템플릿에서 시작하면 됩니다." 템플릿 저장소가 무엇일까요?

마치 프랜차이즈 매뉴얼과 같습니다. 새 지점을 열 때 인테리어부터 메뉴판까지 하나하나 만들 필요 없이, 본사에서 제공하는 표준 패키지를 받아서 시작하는 것이죠.

템플릿 저장소는 개발 프로젝트의 표준 패키지입니다. GitHub에서 저장소 설정에 들어가면 "Template repository" 옵션이 있습니다.

이것을 활성화하면 다른 사람들이 이 저장소를 기반으로 새 저장소를 만들 수 있습니다. "Use this template" 버튼이 생기거든요.

템플릿 저장소에는 무엇을 넣어야 할까요? 위 코드처럼 재사용 워크플로우를 호출하는 CI/CD 파일을 넣습니다.

린트, 테스트, 빌드, 배포까지 표준 파이프라인이 구성되어 있습니다. 새 프로젝트에서는 이 파일을 수정할 필요가 거의 없습니다.

그 외에도 .gitignore, .eslintrc, tsconfig.json 같은 설정 파일들을 넣어둡니다. 폴더 구조도 src/, tests/, docs/ 등 표준 형태로 미리 만들어둡니다.

README 템플릿도 넣어두면 문서화 표준을 유지하는 데 도움이 됩니다. fork와 무엇이 다를까요?

fork는 원본 저장소와 연결이 유지됩니다. 원본의 변경을 가져오거나 PR을 보낼 수 있죠.

반면 템플릿에서 생성한 저장소는 완전히 독립적입니다. 새로운 역사를 시작하는 것입니다.

커밋 히스토리도 깨끗하게 비워집니다. 조직에서 여러 템플릿을 운영할 수도 있습니다.

프론트엔드 프로젝트용, 백엔드 프로젝트용, 라이브러리용 등 용도별로 템플릿을 만들어둡니다. 각 템플릿에는 해당 유형에 맞는 워크플로우와 설정이 들어갑니다.

새 프로젝트를 시작할 때 적절한 템플릿을 선택하기만 하면 됩니다. 이주니어 씨는 이제 "Use this template" 버튼 한 번으로 완벽하게 구성된 프로젝트를 시작합니다.

첫 커밋부터 CI가 돌아가고, PR을 올리면 자동으로 테스트가 실행됩니다. 설정에 쓰던 일주일이 5분으로 줄어들었습니다.

김개발 씨는 뿌듯했습니다. 재사용 워크플로우, 조직 전체 공유, 버전 관리, 그리고 템플릿 저장소까지.

이제 회사의 모든 프로젝트가 일관된 품질과 프로세스를 갖추게 되었습니다.

실전 팁

💡 - 프로젝트 유형별로 여러 템플릿을 만들어두면 선택의 폭이 넓어집니다

• 템플릿의 README에 시작 가이드를 포함하면 온보딩이 더 쉬워집니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!