# 워크플로 구성 재사용

기존 워크플로를 다시 사용하고 YAML 앵커 및 별칭을 사용하여 워크플로를.

## 재사용 가능한 워크플로

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

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

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

* 두 워크플로가 모두 동일한 리포지토리에 있습니다.
* 호출된 워크플로는 .의 공용 리포지
  조직에서는 공용 재사용 가능한 워크플로를 사용할 수 있습니다.
* 호출되는 워크플로가 비공개 리포지토리에 저장되어 있으며, 해당 리포지토리의 설정에서 접근이 허용되어 있습니다. 자세한 내용은 [조직과 작업 및 워크플로 공유](/ko/actions/how-tos/reuse-automations/share-with-your-organization) 및 [프라이빗 리포지토리에서 작업 및 워크플로 공유](/ko/actions/how-tos/reuse-automations/share-across-private-repositories).

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

| 호출자 리포지토리 | 액세스 가능한 워크플로 리포지토리 |
| --------- | ------------------ |
| `private` |                    |
| `private` |                    |
| `public`  |                    |
|           |                    |
| `public`  | `public`           |

호출자 리포지토리의 Actions 설정 페이지에서 **작업 권한**이 작업 및 재사용 가능한 워크플로 사용을 허용하도록 구성되어 있어야 합니다. 자세한 내용은 [리포지토리에 대한 GitHub Actions 설정 관리](/ko/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-select-actions-and-reusable-workflows-to-run)를 참조하세요.

내부 또는 호출된 워크플로 리포지토리의 작업 설정 페이지에서 **액세스** 정책을 명시적으로 구성하여 호출자 워크플로가 포함된 리포지토리의 액세스를 허용해야 합니다. [리포지토리에 대한 GitHub Actions 설정 관리](/ko/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository)을 참조하세요.

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

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

* 최대 10개의 4개 연결할 수 있습니다. 자세한 내용은 [재사용 가능한 워크플로 중첩](/ko/actions/how-tos/reuse-automations/reuse-workflows#nesting-reusable-workflows)을 참조하세요.

* 단일 워크플로 파일에서 최대 50 고유한 재사용 가능한 워크플로를 호출할 수 있습니다. 이 제한에는 최상위 호출자 워크플로 파일에서 시작해 호출될 수 있는 모든 중첩된 재사용 가능한 워크플로 트리가 포함됩니다.

  예시: *top-level-caller-workflow\.yml* → *called-workflow-1.yml* → \_called-workflow-2.yml\_는 2개의 사용 가능한 워크플로로 계산됩니다.

* 호출자 워크플로의 워크플로 수준에서 정의된 `env` 컨텍스트에서 설정된 환경 변수는 호출된 워크플로로 전파되지 않습니다. 자세한 내용은 [변수에 정보 저장](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables) 및 [문맥 참조](/ko/actions/reference/workflows-and-actions/contexts#env-context)을 참조하세요.

* 마찬가지로 호출된 워크플로에서 정의된 `env` 컨텍스트에 설정된 환경 변수는 호출자 워크플로의 `env` 컨텍스트에서는 접근할 수 없습니다. 대신 재사용 가능한 워크플로의 출력을 사용해야 합니다 자세한 내용은 [재사용 가능한 워크플로의 출력 사용](/ko/actions/how-tos/reuse-automations/reuse-workflows#using-outputs-from-a-reusable-workflow)을 참조하세요.

* 여러 워크플로에서 변수를 재사용하려면 조직, 리포지토리 또는 환경 수준에서 변수를 설정하고 `vars` 컨텍스트를 사용해 참조하세요. 자세한 내용은 [변수에 정보 저장](/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables) 및 [문맥 참조](/ko/actions/reference/workflows-and-actions/contexts#vars-context)을 참조하세요.

* 재사용 가능한 워크플로는 작업 단계 내에서가 아니라 작업 내에서 직접 호출됩니다. 따라서 `GITHUB_ENV`을 사용해 호출자 워크플로의 작업 단계로 값을 전달할 수는 없습니다.

### 재사용 가능한 워크플로를 호출하는 작업에 대해 지원되는 키워드

재사용 가능한 워크플로를 호출하는 경우 호출이 포함된 작업에서 다음 키워드만 사용할 수 있습니다.

* [`jobs.<job_id>.name`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname)
* [`jobs.<job_id>.uses`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iduses)
* [`jobs.<job_id>.with`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idwith)
* [`jobs.<job_id>.with.<input_id>`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idwithinput_id)
* [`jobs.<job_id>.secrets`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecrets)
* [`jobs.<job_id>.secrets.<secret_id>`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretssecret_id)
* [`jobs.<job_id>.secrets.inherit`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretsinherit)
* [`jobs.<job_id>.strategy`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategy)
* [`jobs.<job_id>.needs`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idneeds)
* [`jobs.<job_id>.if`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idif)
* [`jobs.<job_id>.concurrency`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency)
* [`jobs.<job_id>.permissions`](/ko/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions)

  > \[!NOTE]
  >
  > * 호출 작업에 `jobs.<job_id>.permissions`가 지정되지 않은 경우 호출된 워크플로에 `GITHUB_TOKEN`에 대한 기본 사용 권한이 있습니다. 자세한 내용은 [GitHub Actions에 대한 워크플로 구문](/ko/actions/reference/workflows-and-actions/workflow-syntax#permissions)을(를) 참조하세요.
  > * 호출자 워크플로에서 전달된 `GITHUB_TOKEN` 권한은 호출된 워크플로에 의해서만 다운그레이드(상승되지 않음)할 수 있습니다.
  > *

`jobs.<job_id>.concurrency.cancel-in-progress: true`을 사용하는 경우, 호출된 워크플로와 호출자 워크플로에서 `jobs.<job_id>.concurrency.group`에 동일한 값을 사용하지 마세요. 그렇게 하면 이미 실행 중인 워크플로가 취소됩니다. 호출된 워크플로는 호출자 워크플로의 이름을 사용하므로 호출자 및 호출된 워크플로${{ github.workflow }}의 값 `jobs.<job_id>.concurrency.group` 으로 이 컨텍스트를 사용하면 호출된 워크플로가 실행될 때 호출자 워크플로가 취소됩니다.

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

#### GitHub 호스티드 러너

The assignment of GitHub호스티드 러너의 할당은 항상 호출자의 컨텍스트만 사용하여 평가됩니다.
GitHub 호스티드 러너 요금은 항상 호출자에게 귀속됩니다. 호출자 워크플로는 호출된 리포지토리에서 GitHub 호스팅된 실행기를 사용할 수 없습니다. 자세한 내용은 [GitHub 호스팅 실행기](/ko/actions/concepts/runners/github-hosted-runners)을(를) 참조하세요.

#### 자체 호스팅 실행기

호출된 워크플로우가 호출 워크플로우와 동일한 사용자, 조직에 속한 경우, 호출자의 컨텍스트에서 자체 호스팅된 러너에 접근할 수 있습니다. 즉, 호출된 워크플로는 다음에 위치한 자체 호스팅 실행기에 액세스할 수 있습니다.

* 호출자 리포지토리
* 호출자 리포지토리의 조직에서 실행기가 호출자 리포지토리에 제공된 경우

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

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

`GITHUB_TOKEN` 권한은 중첩된 워크플로에서 동일하거나 더 제한적으로만 설정할 수 있습니다. 예를 들어, 워크플로 체인 A > B > C에서 A 워크플로가 `package: read` 토큰 권한을 가지고 있다면, B와 C는 `package: write` 권한을 가질 수 없습니다. 자세한 내용은 [워크플로에서 인증에 GITHUB\_TOKEN 사용](/ko/actions/tutorials/authenticate-with-github_token)을(를) 참조하세요.

특정 워크플로 실행에 어떤 워크플로 파일이 포함되었는지 API를 사용해 확인하는 방법은 [워크플로 재사용](/ko/actions/how-tos/reuse-automations/reuse-workflows#monitoring-which-workflows-are-being-used)를 참조하세요.

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

퍼블릭 리포지토리에서 재사용 가능한 워크플로는 SHA, 릴리스 태그 또는 분기 이름을 사용하여 참조할 수 있습니다. 자세한 내용은 [워크플로 재사용](/ko/actions/how-tos/reuse-automations/reuse-workflows#calling-a-reusable-workflow)을(를) 참조하세요.

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

* 워크플로에서 모든 작업을 다시 실행하면 지정된 참조에서 재사용 가능한 워크플로가 사용됩니다. 워크플로의 모든 작업을 다시 실행하는 방법에 대한 자세한 내용은 [워크플로 및 작업 다시 실행](/ko/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-all-the-jobs-in-a-workflow)을(를) 참조하세요.
* 실패한 작업 또는 워크플로의 특정 작업을 다시 실행하면 첫 번째 시도와 동일한 커밋 SHA에서 재사용 가능한 워크플로가 사용됩니다. 워크플로에서 실패한 작업을 다시 실행하는 방법에 대한 자세한 내용은 [워크플로 및 작업 다시 실행](/ko/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-failed-jobs-in-a-workflow)을(를) 참조하세요. 워크플로에서 특정 작업을 다시 실행하는 방법에 대한 자세한 내용은 [워크플로 및 작업 다시 실행](/ko/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-a-specific-job-in-a-workflow)을(를) 참조하세요.

### `github` 컨텍스트

재사용 가능한 워크플로가 호출자 워크플로에 의해 트리거되면 `github` 컨텍스트는 항상 호출자 워크플로와 연결됩니다. 호출된 워크플로에 `github.token`대한 액세스 및 `secrets.GITHUB_TOKEN`에 대한 액세스 권한이 자동으로 부여됩니다.
`github` 컨텍스트에 대한 자세한 내용은 [문맥 참조](/ko/actions/reference/workflows-and-actions/contexts#github-context)을(를) 참조하세요.

## 워크플로 템플릿

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

### 워크플로 템플릿 가용성

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

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

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

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

### `$default-branch` 자리 표시자

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

### 예시 워크플로 템플릿 파일

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

```yaml copy
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`라는 이름의 메타데이터가 포함됩니다.

```json copy
{
    "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](https://primer.style/octicons/) 집합의 아이콘입니다. 옥시콘을 참조하려면 값이 `octicon <icon name>`여야 합니다. 예: `octicon smiley`.

* `categories`

- **선택 사항**. 워크플로가 표시되는 범주를 정의합니다. 다음 목록에서 범주 이름을 사용할 수 있습니다.
  * 시작 워크플로 리포지토리의 [일반 범주 이름입니다](https://github.com/actions/starter-workflows/blob/main/README.md#categories) .
  * [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) 리포지토리에 있는 목록의 Linguist 언어입니다.
  * [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) 리포지토리의 목록에서 지원되는 기술 스택입니다.

* `filePatterns`

- **선택 사항**. 사용자 리포지토리의 루트 디렉터리에 정의된 정규식과 일치하는 파일이 있는 경우 워크플로를 사용할 수 있도록 합니다.

## YAML 앵커 및 별칭

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

앵커 및 별칭에 대한 자세한 내용은 [YAML 사양의 노드 앵커 및 별칭](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases)을 참조하세요.

다음은 환경 변수와 함께 YAML 앵커 및 별칭을 사용하는 예입니다.

```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을 작성하는 것과 같습니다.

```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"
```

전체 작업 구성을 다시 사용하는 등 더 복잡한 구성에 앵커를 사용할 수도 있습니다.

```yaml
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@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm test

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