워크플로 구성 재사용

재사용 가능한 워크플로

재사용 가능한 워크플로의 참조 정보입니다.

재사용 가능한 워크플로에 대한 액세스

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

두 워크플로가 모두 동일한 리포지토리에 있습니다.
호출된 워크플로는 GitHub Enterprise Server의 퍼블릭 리포지토리에 저장됩니다.

GitHub.com에 정의된 재사용 가능한 워크플로는 직접 사용할 수 없습니다. 대신 GitHub Enterprise Server 인스턴스에 재사용 가능한 워크플로의 복사본을 저장하고 해당 경로에서 워크플로를 호출합니다.
호출된 워크플로는 내부 리포지토리에 저장되며 해당 리포지토리에 대한 설정을 통해 액세스할 수 있습니다. 자세한 내용은 엔터프라이즈와 작업 및 워크플로 공유을(를) 참조하세요.
호출된 워크플로는 프라이빗 리포지토리에 저장되며 해당 리포지토리에 대한 설정을 통해 액세스할 수 있습니다. 자세한 내용은 엔터프라이즈와 작업 및 워크플로 공유을(를) 참조하세요.

다음 표에서는 호스트 리포지토리의 표시 유형에 따라 재사용 가능한 워크플로가 호출자 워크플로우에 액세스할 수 있는지를 보여줍니다.

호출자 리포지토리	액세스 가능한 워크플로 리포지토리
`private`	`private`, `internal`, and `public`
`internal`	`internal` 및 `public`
`public`	`public`

호출자 리포지토리의 작업 설정 페이지에서 작업 및 재사용 가능한 워크플로를 사용할 수 있도록 작업 권한을 구성해야 합니다. 리포지토리에 대한 GitHub Actions 설정 관리을(를) 참조하세요.

내부 또는 프라이빗 리포지토리의 경우 호출된 워크플로 리포지토리의 작업 설정 페이지에 있는 액세스 정책을 명시적으로 구성하여 호출자 워크플로가 포함된 리포지토리의 액세스를 허용해야 합니다. 리포지토리에 대한 GitHub Actions 설정 관리을(를) 참조하세요.

참고 항목

보안을 강화하기 위해 GitHub Actions는 작업이나 재사용할 수 있는 워크플로의 리디렉션을 지원하지 않습니다. 즉, 소유자, 작업 리포지토리의 이름, 또는 작업 이름이 변경되면, 이전 이름으로 해당 작업을 사용하는 워크플로가 작동하지 않습니다.

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

최대 4개 수준의 워크플로를 연결할 수 있습니다. 자세한 내용은 재사용 가능한 워크플로 중첩을 참조하세요.
단일 워크플로 파일에서 최대 20개의 재사용 가능한 특정 워크플로를 호출할 수 있습니다. 이 제한에는 최상위 호출자 워크플로 파일에서 시작하여 호출할 수 있는 중첩된 재사용 가능한 워크플로의 트리가 포함됩니다.

예시: top-level-caller-workflow.yml → called-workflow-1.yml → _called-workflow-2.yml_는 2개의 사용 가능한 워크플로로 계산됩니다.
호출자 워크플로의 워크플로 수준에서 정의된 env 컨텍스트에서 설정된 환경 변수는 호출된 워크플로로 전파되지 않습니다. 자세한 내용은 변수에 정보 저장 및 컨텍스트 참조을(를) 참조하세요.
마찬가지로 호출된 워크플로에 정의된 env 컨텍스트에서 설정된 환경 변수는 호출자 워크플로의 env 컨텍스트에서 액세스할 수 없습니다. 대신 재사용 가능한 워크플로의 출력을 사용해야 합니다. 자세한 내용은 재사용 가능한 워크플로의 출력 사용을 참조하세요.
여러 워크플로에서 변수를 다시 사용하려면 조직, 리포지토리 또는 환경 수준에서 변수를 설정하고 vars 컨텍스트를 사용하여 참조합니다. 자세한 내용은 변수에 정보 저장 및 컨텍스트 참조을(를) 참조하세요.
재사용 가능한 워크플로는 작업 단계 내에서 호출되는 것이 아니라 작업 내에서 직접 호출됩니다. 따라서 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>.permissions가 지정되지 않은 경우 호출된 워크플로에 GITHUB_TOKEN에 대한 기본 사용 권한이 있습니다. 자세한 내용은 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 호스팅 실행기을(를) 참조하세요.

자체 호스팅 실행기

호출자 워크플로와 동일한 사용자, 조직 또는 엔터프라이즈에서 소유한 호출된 워크플로는 호출자의 컨텍스트에서 자체 호스트형 실행기에 액세스할 수 있습니다. 즉, 호출된 워크플로는 다음에 위치한 자체 호스팅 실행기에 액세스할 수 있습니다.

호출자 리포지토리
호출자 리포지토리의 조직또는 엔터프라이즈에서, 호출자 리포지토리가 실행기를 사용할 수 있는 경우.

중첩된 워크플로에 대한 액세스 및 권한

중첩된 재사용 가능 워크플로를 포함하고 있는 워크플로는 중첩된 워크플로 중 하나라도 초기 호출자 워크플로에 액세스할 수 없는 경우 실패합니다. 자세한 내용은 재사용 가능한 워크플로에 대한 액세스를 참조하세요.

GITHUB_TOKEN 사용 권한은 중첩된 워크플로에서 동일하거나 더 제한적일 수 있습니다. 예를 들어 워크플로 체인 A > B > C에서 워크플로 A에 package: read 토큰 권한이 있는 경우 B와 C는 package: write 사용 권한을 가질 수 없습니다. 자세한 내용은 워크플로에서 인증에 GITHUB_TOKEN 사용을(를) 참조하세요.

API를 사용하여 특정 워크플로 실행에 관련된 워크플로 파일을 확인하는 방법에 대한 자세한 내용은 워크플로 다시 사용을(를) 참조하세요.

작업을 다시 실행할 때 재사용 가능한 워크플로의 동작

퍼블릭 리포지토리에서 재사용 가능한 워크플로는 SHA, 릴리스 태그 또는 분기 이름을 사용하여 참조할 수 있습니다. 자세한 내용은 워크플로 다시 사용을(를) 참조하세요.

재사용 가능한 워크플로를 사용하는 워크플로를 다시 실행했으며 참조가 SHA가 아닌 경우 다음과 같은 몇 가지 동작을 주의해야 합니다.

워크플로에서 모든 작업을 다시 실행하면 지정된 참조에서 재사용 가능한 워크플로가 사용됩니다. 워크플로의 모든 작업을 다시 실행하는 방법에 대한 자세한 내용은 워크플로 및 작업 다시 실행을(를) 참조하세요.
실패한 작업 또는 워크플로의 특정 작업을 다시 실행하면 첫 번째 시도와 동일한 커밋 SHA에서 재사용 가능한 워크플로가 사용됩니다. 워크플로에서 실패한 작업을 다시 실행하는 방법에 대한 자세한 내용은 워크플로 및 작업 다시 실행을(를) 참조하세요. 워크플로에서 특정 작업을 다시 실행하는 방법에 대한 자세한 내용은 워크플로 및 작업 다시 실행을(를) 참조하세요.

`github` 컨텍스트

재사용 가능한 워크플로가 호출자 워크플로에 의해 트리거되면 github 컨텍스트는 항상 호출자 워크플로와 연결됩니다. 호출된 워크플로에는 github.token에 대한 액세스 및 secrets.GITHUB_TOKEN에 대한 액세스 권한이 자동으로 부여됩니다. github 컨텍스트에 대한 자세한 내용은 컨텍스트 참조을(를) 참조하세요.

워크플로 템플릿

조직의 워크플로 템플릿을 만들 때 사용할 수 있는 참조 정보입니다.

워크플로 템플릿 가용성

템플릿 리포지토리와 일치하거나 더 제한적인 가용성이 있는 리포지토리에서 템플릿을 사용할 수 있습니다.

퍼블릭 .github 리포지토리의 워크플로 템플릿은 모든 유형의 리포지토리에서 사용할 수 있습니다.
내부 .github 리포지토리의 워크플로 템플릿은 내부 및 프라이빗 리포지토리에서만 사용할 수 있습니다.
프라이빗 .github 리포지토리의 워크플로 템플릿은 프라이빗 리포지토리에서만 사용할 수 있습니다.

프라이빗/내부 리포지토리에 대한 액세스 권한 부여

프라이빗 또는 내부 .github 리포지토리를 사용하는 경우, 템플릿을 사용할 수 있도록 사용자 또는 팀에 읽기 권한을 부여해야 합니다.

`$default-branch` 자리 표시자

리포지토리의 기본 분기를 참조해야 하는 경우, 워크플로 템플릿에서 $default-branch 자리 표시자를 사용할 수 있습니다. 워크플로가 생성될 때 자리 표시자는 리포지토리의 기본 분기 이름으로 자동으로 대체됩니다.

`runs-on` 키의 자리 표시자 값

runs-on 키의 다음 값은 자리 표시자로도 처리됩니다.

ubuntu-latest가 [ self-hosted ]로 바뀝니다.
windows-latest가 [ self-hosted, windows ]로 바뀝니다.
macos-latest"가 [ self-hosted, macOS ]로 바뀝니다.

예시 워크플로 템플릿 파일

이름이 octo-organization-ci.yml로 지정된 이 파일은 기본 워크플로를 보여 줍니다.

YAML

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

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

메타데이터 파일 요구 사항

메타데이터 파일의 이름은 워크플로 파일과 동일해야 하지만 .yml 확장명 대신 .properties.json을 추가해야 합니다. 예를 들어, octo-organization-ci.properties.json이라는 이름의 이 파일에는 다음과 같이 워크플로 파일에 대한 octo-organization-ci.yml라는 이름의 메타데이터가 포함됩니다.

JSON

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

{
    "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 <icon name>여야 합니다. 예들 들어 octicon smiley입니다.
categories - 선택 사항. 워크플로가 표시되는 범주를 정의합니다. 다음 목록에서 범주 이름을 사용할 수 있습니다.
- 시작 워크플로 리포지토리의 일반 범주 이름입니다 .
- linguist 리포지토리에 있는 목록의 Linguist 언어입니다.
- starter-workflows 리포지토리의 목록에서 지원되는 기술 스택입니다.
filePatterns - 선택 사항. 사용자 리포지토리의 루트 디렉터리에 정의된 정규식과 일치하는 파일이 있는 경우 워크플로를 사용할 수 있도록 합니다.

이 문서의 내용