워크플로 구성 재사용하기

기존 워크플로를 재사용해서 만들 때 반복을 피하는 방법을 알려드릴게요. 재사용 가능한 워크플로와 템플릿의 접근 규칙, 제한 사항, 지원 키워드를 정리해요.

출처: 문서

본문

기존 워크플로를 재사용해서 만드는 워크플로에서 반복을 피하는 방법에 대한 정보를 확인할 수 있습니다.

재사용 가능한 워크플로(Reusable workflows)

이 문서는 접근 규칙, 제한 사항, 지원되는 키워드, 러너 동작을 포함한 재사용 가능한 워크플로와 워크플로 템플릿에 대한 참고 정보를 제공합니다.

결정적이고 반복 가능한 로직은 재사용 가능한 워크플로에 중앙화하고, 저장소 콘텐츠에 대한 맥락 판단이 필요한 작업(분석, 요약, 권장 사항 등)에는 에이전트형 워크플로를 사용할 수 있습니다. 자세한 내용은 Creating GitHub Agentic Workflows를 참고하세요.

재사용 가능한 워크플로에 대한 접근

다음 중 하나에 해당하면 재사용 가능한 워크플로를 다른 워크플로가 사용할 수 있습니다:

두 워크플로가 같은 저장소에 있습니다.
호출되는 워크플로가 공개 저장소에 저장되어 있고, 조직이 공개 재사용 가능한 워크플로를 사용하도록 허용합니다.
호출되는 워크플로가 비공개 저장소에 저장되어 있고, 해당 저장소의 설정이 접근을 허용합니다. 자세한 내용은 Sharing actions and workflows with your organization과 Sharing actions and workflows from your private repository를 참고하세요.

다음 표는 호스트 저장소의 가시성에 따른 호출자 워크플로에 대한 재사용 가능한 워크플로의 접근성을 보여줍니다.

Caller repository	Accessible workflows repositories
`private`	`private` and `public`

`public`	`public`

호출자 저장소의 Actions 설정 페이지에 있는 Actions permissions이 액션과 재사용 가능한 워크플로의 사용을 허용하도록 구성되어야 합니다 - Managing GitHub Actions settings for a repository를 참고하세요.

비공개 저장소의 경우 호출되는 워크플로의 저장소 Actions 설정 페이지에 있는 Access 정책이 호출자 워크플로가 포함된 저장소에서의 접근을 허용하도록 명시적으로 구성되어야 합니다 - Managing GitHub Actions settings for a repository를 참고하세요.

[!NOTE] 보안을 강화하기 위해 GitHub Actions는 액션이나 재사용 가능한 워크플로에 대한 리다이렉트를 지원하지 않습니다. 즉 액션 저장소의 소유자, 이름, 또는 액션 이름이 변경되면 이전 이름으로 해당 액션을 사용하는 모든 워크플로가 실패합니다.

재사용 가능한 워크플로의 제한 사항

최대 10단계의 워크플로를 연결할 수 있습니다. 자세한 내용은 Nesting reusable workflows를 참고하세요.
단일 워크플로 파일에서 최대 50개의 고유한 재사용 가능한 워크플로를 호출할 수 있습니다. 이 한도에는 최상위 호출자 워크플로 파일에서 시작해서 호출될 수 있는 중첩된 재사용 가능한 워크플로 트리가 모두 포함됩니다.

예를 들어 top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml는 재사용 가능한 워크플로 2개로 계산됩니다.
호출자 워크플로의 워크플로 레벨에서 정의된 env 컨텍스트에 설정된 환경 변수는 호출되는 워크플로로 전파되지 않습니다. 자세한 내용은 Store information in variables와 Contexts reference를 참고하세요.
마찬가지로 호출되는 워크플로에 정의된 env 컨텍스트에 설정된 환경 변수는 호출자 워크플로의 env 컨텍스트에서 접근할 수 없습니다. 대신 재사용 가능한 워크플로의 출력을 사용해야 합니다. 자세한 내용은 Using outputs from a reusable workflow를 참고하세요.
여러 워크플로에서 변수를 재사용하려면 조직, 저장소, 환경 레벨에서 설정하고 vars 컨텍스트로 참조하세요. 자세한 내용은 Store information in variables와 Contexts reference를 참고하세요.
재사용 가능한 워크플로는 잡 스텝이 아니라 잡 안에서 직접 호출됩니다. 따라서 GITHUB_ENV를 사용해서 호출자 워크플로의 잡 스텝에 값을 전달할 수 없습니다.

재사용 가능한 워크플로를 호출하는 잡의 지원 키워드

재사용 가능한 워크플로를 호출할 때 호출을 포함하는 잡에서는 다음 키워드만 사용할 수 있습니다:

jobs.<job_id>.name
jobs.<job_id>.uses
jobs.<job_id>.with
jobs.<job_id>.with.<input_id>
jobs.<job_id>.secrets
jobs.<job_id>.secrets.<secret_id>
jobs.<job_id>.secrets.inherit
jobs.<job_id>.strategy
jobs.<job_id>.needs
jobs.<job_id>.if
jobs.<job_id>.concurrency
jobs.<job_id>.permissions
jobs.<job_id>.cache-mode
[!NOTE]
- 호출 잡에 jobs.<job_id>.permissions를 지정하지 않으면 호출되는 워크플로는 GITHUB_TOKEN의 기본 권한을 가집니다. 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.
- 호출자 워크플로에서 전달된 GITHUB_TOKEN 권한은 호출되는 워크플로에 의해 낮출 수만 있고(승격은 불가) 상승시킬 수 없습니다.
- jobs.<job_id>.concurrency.cancel-in-progress: true를 사용한다면 호출되는 워크플로와 호출자 워크플로에서 jobs.<job_id>.concurrency.group에 같은 값을 사용하지 마세요. 이렇게 하면 이미 실행 중인 워크플로가 취소되기 때문입니다. 호출되는 워크플로는 ${{ github.workflow }}에서 호출자 워크플로의 이름을 사용하므로, 호출자와 호출되는 워크플로 모두에서 이 컨텍스트를 jobs.<job_id>.concurrency.group 값으로 사용하면 호출되는 워크플로가 실행될 때 호출자 워크플로가 취소됩니다.

재사용 가능한 워크플로가 러너를 사용하는 방식

GitHub 호스팅 러너

GitHub 호스팅 러너의 할당은 항상 호출자의 컨텍스트만 사용해서 평가됩니다. GitHub 호스팅 러너에 대한 청구는 항상 호출자와 연결됩니다. 호출자 워크플로는 호출되는 저장소의 GitHub 호스팅 러너를 사용할 수 없습니다. 자세한 내용은 GitHub-hosted runners를 참고하세요.

셀프 호스팅 러너

호출자 워크플로와 같은 사용자나 조직이 소유한 호출되는 워크플로는 호출자의 컨텍스트에서 셀프 호스팅 러너에 접근할 수 있습니다. 즉 호출되는 워크플로는 다음 위치의 셀프 호스팅 러너에 접근할 수 있습니다:

호출자 저장소
러너가 호출자 저장소에 사용 가능하게 된 경우 호출자 저장소의 조직

중첩 워크플로의 접근 및 권한

중첩된 재사용 가능한 워크플로를 포함하는 워크플로는, 그 중첩 워크플로 중 하나라도 최초 호출자 워크플로에 접근할 수 없으면 실패합니다. 자세한 내용은 Access to reusable workflows를 참고하세요.

GITHUB_TOKEN 권한은 중첩 워크플로에서 같거나 더 제한적일 수만 있습니다. 예를 들어 워크플로 체인 A > B > C에서 워크플로 A가 package: read 토큰 권한을 가지면 B와 C는 package: write 권한을 가질 수 없습니다. 자세한 내용은 Use GITHUB_TOKEN for authentication in workflows을 참고하세요.

API를 사용해서 특정 워크플로 실행에 어떤 워크플로 파일이 관여했는지 확인하는 방법은 Reuse workflows를 참고하세요.

잡 재실행 시 재사용 가능한 워크플로의 동작

공개 저장소의 재사용 가능한 워크플로는 SHA, 릴리스 태그, 또는 브랜치 이름으로 참조할 수 있습니다. 자세한 내용은 Reuse workflows를 참고하세요.

재사용 가능한 워크플로를 사용하는 워크플로를 다시 실행할 때 참조가 SHA가 아니라면 알아야 할 몇 가지 동작이 있습니다:

워크플로의 모든 잡을 다시 실행하면 지정된 참조의 재사용 가능한 워크플로를 사용합니다. 워크플로의 모든 잡을 다시 실행하는 방법에 대한 자세한 내용은 Re-running workflows and jobs를 참고하세요.
실패한 잡이나 워크플로의 특정 잡을 다시 실행하면 첫 번째 시도의 커밋 SHA에 있는 재사용 가능한 워크플로를 사용합니다. 워크플로의 실패한 잡을 다시 실행하는 방법에 대한 자세한 내용은 Re-running workflows and jobs를 참고하세요. 워크플로의 특정 잡을 다시 실행하는 방법에 대한 자세한 내용은 Re-running workflows and jobs를 참고하세요.

`github` 컨텍스트

호출자 워크플로가 재사용 가능한 워크플로를 트리거하면 github 컨텍스트는 항상 호출자 워크플로와 연결됩니다. 호출되는 워크플로에는 github.token과 secrets.GITHUB_TOKEN에 대한 접근이 자동으로 부여됩니다. github 컨텍스트에 대한 자세한 내용은 Contexts reference를 참고하세요.

워크플로 템플릿

조직을 위한 워크플로 템플릿을 만들 때 사용할 참고 정보입니다.

워크플로 템플릿 가용성

템플릿 저장소와 일치하거나 더 제한된 가시성을 가진 저장소에서 템플릿을 사용할 수 있습니다.

공개 .github 저장소의 워크플로 템플릿은 모든 저장소 유형에서 사용할 수 있습니다.
내부 .github 저장소의 워크플로 템플릿은 내부 및 비공개 저장소에서만 사용할 수 있습니다.
비공개 .github 저장소의 워크플로 템플릿은 비공개 저장소에서만 사용할 수 있습니다.

비공개/내부 저장소에 대한 접근 부여

비공개 또는 내부 .github 저장소를 사용한다면 템플릿을 사용할 수 있어야 하는 사용자나 팀에게 Read 접근 권한을 부여해야 합니다.

`$default-branch` 자리 표시자

저장소의 기본 브랜치를 참조해야 한다면 워크플로 템플릿에서 $default-branch 자리 표시자를 사용할 수 있습니다. 워크플로가 생성되면 자리 표시자는 저장소의 기본 브랜치 이름으로 자동으로 대체됩니다.

워크플로 템플릿 파일 예시

octo-organization-ci.yml이라는 이 파일은 기본 워크플로를 보여줍니다.

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Run a one-line script
        run: echo Hello from Octo Organization

메타데이터 파일 요구 사항

메타데이터 파일은 워크플로 파일과 같은 이름이어야 하지만, .yml 확장자 대신 .properties.json이 붙어야 합니다. 예를 들어 octo-organization-ci.properties.json이라는 이 파일은 octo-organization-ci.yml이라는 워크플로 파일의 메타데이터를 포함합니다:

{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}

name - 필수. 워크플로의 이름입니다. 사용 가능한 워크플로 목록에 표시됩니다.
description - 필수. 워크플로의 설명입니다. 사용 가능한 워크플로 목록에 표시됩니다.
iconName - 선택. 워크플로 목록에 표시되는 워크플로의 아이콘을 지정합니다. iconName은 다음 유형 중 하나입니다:
- workflow-templates 디렉터리에 저장된 SVG 파일. 파일을 참조하려면 값이 파일 확장자를 뺀 파일 이름이어야 합니다. 예를 들어 example-icon.svg라는 SVG 파일은 example-icon으로 참조됩니다.
- GitHub의 Octicons 집합의 아이콘. octicon을 참조하려면 값이 octicon <icon name>이어야 합니다. 예를 들어 octicon smiley.
categories - 선택. 워크플로가 표시되는 카테고리를 정의합니다. 다음 목록에서 카테고리 이름을 사용할 수 있습니다:
- starter-workflows 저장소의 일반 카테고리 이름.
- linguist 저장소 목록의 Linguist 언어.
- starter-workflows 저장소 목록의 지원되는 기술 스택.
filePatterns - 선택. 사용자 저장소의 루트 디렉터리에 정의된 정규 표현식과 일치하는 파일이 있으면 워크플로를 사용할 수 있게 합니다.

YAML 앵커와 별칭

YAML 앵커와 별칭을 사용해서 워크플로의 반복을 줄일 수 있습니다. 앵커(&로 표시)는 재사용하려는 콘텐츠를 식별하고, 별칭(*로 표시)은 다른 위치에서 그 콘텐츠를 반복합니다.

앵커와 별칭에 대한 자세한 내용은 YAML 사양의 Node Anchors and Aliases를 참고하세요.

환경 변수와 함께 YAML 앵커와 별칭을 사용하는 예시입니다:

jobs:
  job1:
    env: &env_vars # Define the anchor on first use
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Using production settings"

  job2:
    env: *env_vars # Reuse the environment variables
    steps:
      - run: echo "Same environment variables here"

이는 앵커와 별칭 없이 다음 YAML을 작성하는 것과 동일합니다:

jobs:
  job1:
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Using production settings"

  job2:
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Same environment variables here"

전체 잡 구성을 재사용하는 것 같은 더 복잡한 구성에도 앵커를 사용할 수 있습니다:

jobs:
  test: &base_job # Define the anchor on first use
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      NODE_VERSION: '18'
    steps:
      - uses: actions/checkout@v6
      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm test

  alt-test: *base_job # Reuse the entire job configuration

워크플로 구성 재사용하기