GitHub Actions 재사용 가능한 워크플로우란?
CI/CD 파이프라인을 관리하다 보면 비슷한 워크플로우 코드를 여러 레포지토리에 복사하게 됩니다. 빌드, 테스트, 배포 로직이 10개 레포에 중복되어 있다면? 한 곳을 수정할 때 나머지 9곳도 모두 업데이트해야 합니다. GitHub Actions의 재사용 가능한 워크플로우(Reusable Workflows)는 이 문제를 근본적으로 해결합니다.
2026년 2월 GitHub이 공개한 최신 업데이트에는 허용된 액션과 재사용 워크플로우만 실행하는 정책 기능이 추가되어 보안과 거버넌스가 더욱 강화됐습니다.
재사용 가능한 워크플로우 기본 구조
워크플로우 정의하기 (호출받는 쪽)
재사용 가능한 워크플로우는 workflow_call 이벤트로 정의합니다.
# .github/workflows/deploy-reusable.yml
name: Reusable Deploy Workflow
on:
workflow_call:
inputs:
environment:
required: true
type: string
description: "배포 환경 (staging/production)"
node-version:
required: false
type: string
default: '20'
secrets:
deploy-token:
required: true
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
steps:
- uses: actions/checkout@v4
- name: Node.js 설정
uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: 'npm'
- name: 의존성 설치
run: npm ci
- name: 빌드
run: npm run build
- name: ${{ inputs.environment }} 배포
run: npm run deploy:${{ inputs.environment }}
env:
DEPLOY_TOKEN: ${{ secrets.deploy-token }}
워크플로우 호출하기 (호출하는 쪽)
# .github/workflows/main.yml
name: CI/CD Pipeline
on:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci && npm test
deploy-staging:
needs: test
uses: org/shared-workflows/.github/workflows/deploy-reusable.yml@main
with:
environment: staging
node-version: '22'
secrets:
deploy-token: ${{ secrets.STAGING_DEPLOY_TOKEN }}
deploy-production:
needs: deploy-staging
uses: org/shared-workflows/.github/workflows/deploy-reusable.yml@main
with:
environment: production
secrets:
deploy-token: ${{ secrets.PROD_DEPLOY_TOKEN }}
outputs: 결과를 다음 잡으로 전달
재사용 워크플로우에서 생성한 값(빌드 버전, 이미지 태그 등)을 호출한 워크플로우로 반환할 수 있습니다.
# 재사용 워크플로우 - outputs 정의
on:
workflow_call:
outputs:
image-tag:
description: "빌드된 Docker 이미지 태그"
value: ${{ jobs.build.outputs.tag }}
jobs:
build:
runs-on: ubuntu-latest
outputs:
tag: ${{ steps.build.outputs.image-tag }}
steps:
- id: build
run: |
TAG="v$(date +%Y%m%d)-${GITHUB_SHA::7}"
echo "image-tag=$TAG" >> $GITHUB_OUTPUT
docker build -t myapp:$TAG .
# 호출 워크플로우 - outputs 활용
jobs:
use-image:
needs: build-image
steps:
- run: echo "이미지: ${{ needs.build-image.outputs.image-tag }}"
2026년 보안 강화: 최소 권한 원칙 적용
허용 목록(Allowlist) 정책
GitHub의 2026년 2월 업데이트 핵심 기능입니다. 조직 또는 레포지토리 수준에서 허용된 액션과 재사용 워크플로우만 실행되도록 정책을 설정할 수 있습니다.
# Organization 설정에서 허용 목록 구성 (Settings → Actions → General)
# 허용 예시:
# - actions/* (GitHub 공식 액션)
# - org/shared-workflows/* (내부 공유 워크플로우)
# - docker/build-push-action@v5 (특정 버전 고정)
이 정책으로 공급망 공격(Supply Chain Attack)을 방지하고, 악의적이거나 취약한 서드파티 액션이 파이프라인에 침투하는 것을 막을 수 있습니다.
Secrets 보안 모범 사례
- 재사용 워크플로우에 secrets를 직접 환경변수로 노출하지 말고
secrets블록으로 명시적 전달 - Production 환경 시크릿은
environment보호 규칙과 결합 - OIDC(OpenID Connect) 사용으로 장기 액세스 키 없이 클라우드 인증
# OIDC로 AWS 인증 (액세스 키 불필요)
- name: AWS 인증 (OIDC)
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789:role/github-actions-role
aws-region: ap-northeast-2
Composite Actions vs Reusable Workflows: 언제 무엇을?
| 구분 | Composite Actions | Reusable Workflows |
|---|---|---|
| 단위 | Steps 묶음 | Jobs 묶음 |
| 실행 환경 | 호출 잡의 runner 공유 | 독립적인 runner 사용 |
| 병렬 실행 | 불가 (순차) | 가능 (matrix 전략) |
| Secrets 전달 | 자동 상속 | 명시적 전달 필요 |
| 적합한 경우 | 반복 steps 공통화 | 전체 CI/CD 패턴 공유 |
실전 팁: 버전 관리와 유지보수
태그로 버전 고정
재사용 워크플로우를 @main으로 참조하면 변경사항이 즉시 반영됩니다. 안정성이 중요하다면 @v1.2.0처럼 태그로 고정하세요.
# 권장: 버전 태그 고정 (안정성)
uses: org/shared-workflows/.github/workflows/deploy.yml@v2.0.0
# 개발 중: 브랜치 참조 (최신 반영)
uses: org/shared-workflows/.github/workflows/deploy.yml@main
변경 영향도 파악
재사용 워크플로우를 수정하기 전에 GitHub의 "Used by" 기능으로 몇 개의 레포/워크플로우가 이 파일을 참조하는지 확인하세요. 주요 변경 시에는 하위 호환성을 유지하거나 새 버전 태그를 발행하는 것이 좋습니다.
정리
재사용 가능한 워크플로우는 단순한 코드 중복 제거를 넘어 CI/CD 거버넌스의 핵심 도구입니다. 조직 표준 파이프라인을 중앙화하고, 보안 정책을 일관되게 적용하며, 변경 관리를 체계화할 수 있습니다.
5개 이상의 레포에서 비슷한 워크플로우 코드를 유지하고 있다면, 지금 바로 재사용 워크플로우로 전환할 타이밍입니다.
