워크플로 다시 사용

기존 워크플로를 다시 사용하여 워크플로를 만들 때 중복을 방지하는 방법을 알아봅니다.

이 문서의 내용

재사용 가능한 워크플로 만들기

재사용 가능한 워크플로는 YAML 형식의 파일로, 다른 워크플로 파일과 매우 유사합니다. 다른 워크플로 파일과 마찬가지로 리포지토리의 .github/workflows 디렉터리에서 재사용 가능한 워크플로를 찾습니다. workflows 디렉터리의 하위 디렉터리가 지원되지 않습니다.

워크플로를 다시 사용하려면 다음 on 값이 workflow_call을 포함해야 합니다.

on:
  workflow_call:

재사용 가능한 워크플로에서 입력 및 비밀 사용

호출자 워크플로에서 전달된 다음 호출된 워크플로 내에서 사용할 수 있는 입력 및 비밀을 정의할 수 있습니다. 재사용 가능한 워크플로에서 입력 또는 비밀을 사용하는 세 가지 단계가 있습니다.

  1. 재사용 가능한 워크플로에서 inputs 및 secrets 키워드를 사용하여 호출자 워크플로에서 전달될 입력 또는 비밀을 정의합니다.

    on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      personal_access_token:
        required: true

입력 및 비밀을 정의하는 구문에 대한 자세한 내용은 on.workflow_call.inputs 및 on.workflow_call.secrets를 참조하세요.

  1. 다시 사용 가능한 워크플로에서 이전 단계에서 on 키에 정의한 입력 또는 비밀을 참조합니다.

    참고 항목

    비밀이 호출 워크플로에서 secrets: inherit를 사용하여 상속되는 경우에는 on 키에 명시적으로 정의되지 않더라도 비밀을 참조할 수 있습니다. 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

    jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.personal_access_token }}
        configuration-path: ${{ inputs.config-path }}

    위의 예제에서 personal_access_token은 리포지토리 또는 조직 수준에서 정의된 비밀입니다.

    경고

    on.workflow_call은 environment 키워드를 지원하지 않으므로 호출자 워크플로에서 환경 비밀을 전달할 수 없습니다. 작업 수준에서 재사용 가능한 워크플로에 environment를 포함하면 호출자 워크플로에서 전달된 비밀이 아니라 환경 비밀이 사용됩니다. 자세한 내용은 배포 환경 관리 및 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

  2. 호출자 워크플로에서 입력 또는 비밀을 전달합니다.

    명명된 입력을 호출된 워크플로에 전달하려면 작업에서 with 키워드를 사용합니다. 명명된 비밀을 전달하려면 secrets 키워드를 사용합니다. 입력의 경우 입력 값의 데이터 형식은 호출된 워크플로에 지정된 형식(부울, 숫자 또는 문자열)과 일치해야 합니다.

    jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      personal_access_token: ${{ secrets.token }}

    동일한 조직 또는 엔터프라이즈에서 재사용 가능한 워크플로를 호출하는 워크플로는 inherit 키워드를 사용하여 비밀을 암시적으로 전달할 수 있습니다.

    jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

재사용 가능한 워크플로 예시

이 재사용 가능한 workflow-B.yml라는 워크플로 파일(뒷부분의 예시 호출자 워크플로에서 참조)은 호출자 워크플로에서 입력 문자열과 비밀을 가져와서 작업에서 사용합니다.

YAML
name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

재사용 가능한 워크플로 호출

uses 키워드를 사용하여 재사용 가능한 워크플로를 호출합니다. 워크플로 내에서 작업을 사용하는 경우와 달리 작업 단계 내에서가 아니라 작업 내에서 직접 재사용 가능한 워크플로를 호출합니다.

jobs.<job_id>.uses

다음 구문 중 하나를 사용하여 재사용 가능한 워크플로 파일을 참조합니다.

  • 퍼블릭 및 프라이빗 리포지토리에서 재사용 가능한 워크플로의 경우 {owner}/{repo}/.github/workflows/{filename}@{ref}입니다.
  • 동일한 리포지토리에서 다시 사용할 수 있는 워크플로의 경우 ./.github/workflows/{filename}입니다.

첫 번째 선택에서 {ref}은(는) SHA, 릴리스 태그 또는 분기 이름을 사용할 수 있습니다. 릴리스 태그와 분기의 이름이 같으면 릴리스 태그가 분기 이름보다 우선합니다. 안정성과 보안을 위해서는 커밋 SHA를 사용하는 것이 가장 안전합니다. 자세한 내용은 보안 사용 참조을(를) 참조하세요.

두 번째 구문 옵션({owner}/{repo}, @{ref} 없음)을 사용하는 경우 호출된 워크플로는 호출자 워크플로와 동일한 커밋에서 가져옵니다. refs/heads, refs/tags 등의 참조 접두사는 사용할 수 없습니다. 이 키워드에는 컨텍스트 또는 식을 사용할 수 없습니다.

별도의 작업에서 각각을 참조하여 여러 워크플로를 호출할 수 있습니다.

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

호출자 워크플로 예시

이 워크플로 파일은 두 개의 워크플로 파일을 호출합니다. 이 중 두 번째인 (재사용 가능한 워크플로 예시에 나타난) workflow-B.yml에 입력(config-path) 및 비밀(token)을 전달합니다.

YAML
name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    permissions:
      contents: read
      pull-requests: write
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

재사용 가능한 워크플로에서 입력 및 비밀 전달

명명된 입력을 호출된 워크플로에 전달하려면 작업에서 with 키워드를 사용합니다. 명명된 비밀을 전달하려면 secrets 키워드를 사용합니다. 입력의 경우 입력 값의 데이터 형식은 호출된 워크플로에 지정된 형식(부울, 숫자 또는 문자열)과 일치해야 합니다.

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      personal_access_token: ${{ secrets.token }}

동일한 조직 또는 엔터프라이즈에서 재사용 가능한 워크플로를 호출하는 워크플로는 inherit 키워드를 사용하여 비밀을 암시적으로 전달할 수 있습니다.

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

재사용 가능한 워크플로에 행렬 전략 사용

행렬 전략을 사용하는 작업은 재사용 가능한 워크플로를 호출할 수 있습니다.

매트릭스 전략을 사용하면 단일 작업 정의에서 변수를 사용하여 변수의 조합을 기반으로 하는 여러 작업 실행을 자동으로 만들 수 있습니다. 예를 들어 행렬 전략을 사용하여 재사용 가능한 워크플로에 다른 입력을 전달할 수 있습니다. 행렬에 대한 자세한 내용은 워크플로에서 작업 변형 실행을(를) 참조하세요.

아래 예시 작업은 재사용 가능한 워크플로를 호출하고 값 [dev, stage, prod](으)로 변수 target을(를) 정의하여 행렬형 컨텍스트를 참조합니다. 변수의 각 값에 대해 하나씩 3개의 작업을 실행합니다.

YAML
jobs:
  ReusableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

재사용 가능한 워크플로 중첩

최대 4개의 워크플로 수준(즉, 1개의 최상위 호출자 워크플로 및 최대 3개 수준의 재사용 가능한 워크플로)을 연결할 수 있습니다. 예시: caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml → called-workflow-3.yml. 워크플로 트리의 루프는 허용되지 않습니다.

참고 항목

중첩된 재사용 가능한 워크플로를 사용하려면 체인의 모든 워크플로에 호출자가 액세스할 수 있어야 하며, 권한은 체인 전체에서 유지관리 또는 축소될 수만 있고 상승될 수는 없습니다. 자세한 내용은 재사용 가능한 워크플로 참조을(를) 참조하세요.

재사용 가능한 워크플로 내에서 재사용 가능한 다른 워크플로를 호출할 수 있습니다.

YAML
name: Reusable workflow

on:
  workflow_call:

jobs:
  call-another-reusable:
    uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1

중첩된 워크플로에 비밀 전달

호출 워크플로에서 jobs.<job_id>.secrets를 사용하여 명명된 비밀을 직접 호출된 워크플로에 전달할 수 있습니다. 또는 jobs.<job_id>.secrets.inherit를 사용하여 호출 워크플로의 모든 비밀을 직접 호출된 워크플로에 전달할 수 있습니다. 자세한 내용은 위의 섹션 워크플로 다시 사용 및 참조 문서 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요. 비밀은 직접 호출된 워크플로에만 전달되므로 워크플로 체인 A > B > C에서 워크플로 C는 비밀이 A에서 B로 전달된 다음 B에서 C로 전달된 경우에만 A로부터 비밀을 받습니다.

다음 예시에서 워크플로 A는 inherit 키워드를 사용하여 모든 비밀을 워크플로 B에 전달하지만 워크플로 B는 비밀을 하나만 워크플로 C에 전달합니다. 워크플로 B에 전달된 다른 비밀은 모두 워크플로 C에서 사용할 수 없습니다.

jobs:
  workflowA-calls-workflowB:
    uses: octo-org/example-repo/.github/workflows/B.yml@main
    secrets: inherit # pass all secrets

jobs:
  workflowB-calls-workflowC:
    uses: different-org/example-repo/.github/workflows/C.yml@main
    secrets:
      repo-token: ${{ secrets.personal_access_token }} # pass just this secret

재사용 가능한 워크플로의 출력 사용

재사용 가능한 워크플로는 호출자 워크플로에서 사용하려는 데이터를 생성할 수 있습니다. 출력을 사용하려면 재사용 가능한 워크플로의 출력으로 지정해야 합니다.

출력을 설정하는 재사용 가능한 워크플로가 행렬 전략으로 실행되는 경우 출력은 실제로 값을 설정하는 행렬의 재사용 가능한 워크플로를 마지막으로 성공적으로 완료하여 설정한 출력이 됩니다. 즉, 재사용 가능한 워크플로의 마지막 성공적 완료가 출력에 대해 빈 문자열을 설정하고, 재사용 가능한 워크플로의 마지막 두 번째 성공적 완료가 출력에 대한 실제 값을 설정하는 경우 출력에는 재사용 가능한 워크플로의 마지막 두 번째 완료의 값이 포함됩니다.

다음 재사용 가능한 워크플로에는 두 단계를 포함하는 단일 작업이 있습니다. 각 단계에서는 “hello” 및 “world”라는 단일 단어를 출력으로 설정합니다. 작업의 outputs 섹션에서는 다음 단계 출력을 output1 또는 output2라는 작업 출력에 매핑합니다. 그런 다음 on.workflow_call.outputs 섹션에서는 워크플로 자체에 대해 두 개의 출력을 정의합니다. 하나는 output1에 매핑되는 firstword라는 출력이고 다른 하나는 output2에 매핑되는 secondword라는 출력입니다.

value는 호출된 워크플로 내에서 작업 수준 출력의 값으로 설정해야 합니다. 단계 수준 출력은 먼저 아래와 같이 작업 수준 출력에 매핑되어야 합니다.

자세한 내용은 작업 간에 정보 전달 및 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

YAML
name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

이제 동일한 워크플로 내의 작업에서 출력을 사용하는 것과 동일한 방식으로 호출자 워크플로의 출력을 사용할 수 있습니다. 다시 사용할 수 있는 워크플로의 워크플로 수준에서 정의된 이름(firstword 및 secondword)를 사용하여 출력을 참조합니다. 이 워크플로에서는 job1에서 재사용 가능한 워크플로를 호출하고 job2에서 재사용 가능한 워크플로의 출력(“hello world”)을 워크플로 로그의 표준 출력으로 출력합니다.

YAML
name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

작업 출력 사용에 대한 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요. 워크플로 간에 변수 이외의 항목(예시: 빌드 아티팩트)을 공유하려면 Store and share data with workflow artifacts을(를) 참조하세요.

사용 중인 워크플로 모니터링

GitHub Enterprise Cloud를 사용하는 조직은 GitHub REST API를 통해 감사 로그와 상호 작용하여 어떤 워크플로가 사용되고 있는지 모니터링할 수 있습니다. 자세한 내용은 GitHub Enterprise Cloud 설명서를 참조하세요.

다음 단계

워크플로 재사용의 복잡성에 대한 정보를 찾으려면 재사용 가능한 워크플로 참조을(를) 참조하세요.