GitHub Actions에 대한 메타데이터 구문

참고: GitHub 호스트 실행기는 현재 GitHub Enterprise Server에서 지원되지 않습니다. GitHub public roadmap에 예정된 향후 지원에 대해 자세히 알아볼 수 있습니다.

GitHub Actions에 대한 YAML 구문

모든 작업에는 메타데이터 파일이 필요합니다. 메타데이터 파일 이름은 action.yml 또는 action.yaml이어야 합니다. 메타데이터 파일의 데이터는 작업에 대한 입력, 출력, 실행 구성을 정의합니다.

작업 메타데이터 파일은 YAML 구문을 사용합니다. YAML을 처음 사용하는 경우 "5분 안에 YAML 알아보기"를 읽을 수 있습니다.

`name`

필수 작업의 이름입니다. GitHub은(는) 각 작업을 시각적으로 식별하는 데 도움이 되도록 작업 탭에 name을 표시합니다.

`inputs`

선택 사항 입력 매개 변수를 사용하면 런타임 중에 작업에서 사용할 데이터를 지정할 수 있습니다. GitHub은(는) 입력 매개 변수를 환경 변수로 저장합니다. 소문자 입력 ID를 사용하는 것이 좋습니다.

예: 입력 지정

이 예에서는 두 개의 입력을 구성합니다: num-octocats과 octocat-eye-color입니다. num-octocats 입력은 필수가 아니며 기본값은 1입니다. octocat-eye-color은 필수 입력이며 기본값이 없습니다.

참고: required: true를 사용하는 작업은 입력이 지정되지 않은 경우 자동으로 오류를 반환하지 않습니다.

이 작업을 사용하는 워크플로 파일은 with 키워드를 사용하여 octocat-eye-color에 대한 입력 값을 설정할 수 있습니다. with 구문에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 구문"을 참조하십시오.

inputs:
  num-octocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocat-eye-color:
    description: 'Eye color of the Octocats'
    required: true

입력값을 지정하면 GitHub은(는) 이름이 INPUT_<VARIABLE_NAME>인 입력에 대한 환경 변수를 만듭니다. 만들어진 환경 변수는 입력 이름을 대문자로 변환하고 공백을 _ 문자로 바꿉니다.

작업이 을 사용하여 작성된 경우 자동으로 INPUT_<VARIABLE_NAME>을 가져오지 않습니다. 복합 작업을 사용하면 inputs 워크플로 실행에 대한 컨텍스트 정보에 액세스을 사용하여 작업 입력에 액세스할 수 있습니다.

Docker 컨테이너 작업에서 환경 변수에 액세스하려면 작업 메타데이터 파일에서 args 키워드를 사용하여 입력을 전달해야 합니다. Docker 컨테이너 작업의 작업 메타데이터 파일에 대한 자세한 내용은 "Docker 컨테이너 작업 만들기"을 참조하세요.

예를 들어 워크플로가 num-octocats 및 octocat-eye-color 입력을 정의한 경우 작업 코드는 INPUT_NUM-OCTOCATS 및 INPUT_OCTOCAT-EYE-COLOR 환경 변수를 사용하여 입력 값을 읽을 수 있습니다.

`inputs.<input_id>`

필수 입력과 연결할 string 식별자입니다. <input_id> 값은 입력 메타데이터의 맵입니다. <input_id>은 inputs 개체 내에서 고유한 식별자여야 합니다. <input_id>는 문자 또는 _로 시작해야 하며 영숫자, - 또는 _만 포함해야 합니다.

`inputs.<input_id>.description`

필수 입력 매개 변수에 대한 string 설명입니다.

`inputs.<input_id>.required`

선택 사항 작업에 입력 매개 변수가 필요한지 여부를 나타내는 boolean입니다. 매개 변수가 필요한 경우 true로 설정합니다.

`inputs.<input_id>.default`

선택 사항 기본값을 나타내는 string입니다. 기본값은 입력 매개 변수가 워크플로 파일에 지정되지 않은 경우에 사용됩니다.

`inputs.<input_id>.deprecationMessage`

선택 사항 입력 매개 변수를 사용하면 string이 경고 메시지로 기록됩니다. 이 경고를 사용하여 입력이 사용되지 않음임을 알리고 대안을 언급할 수 있습니다.

Docker 컨테이너 및 JavaScript 작업의 `outputs`

선택 사항 출력 매개 변수를 사용하면 작업이 설정하는 데이터를 선언할 수 있습니다. 워크플로에서 나중에 실행되는 작업은 이전에 실행한 작업의 출력 데이터 세트를 사용할 수 있습니다. 예를 들어 두 개의 입력(x + y = z)을 추가하는 작업을 수행하는 경우 이 작업은 입력으로 사용할 다른 작업에 대한 합계(z)를 출력할 수 있습니다.

출력은 유니코드 문자열이며 최대 1MB일 수 있습니다. 워크플로 실행의 모든 출력 합계는 최대 50MB가 될 수 있습니다.

작업 메타데이터 파일에서 출력을 선언하지 않은 경우에도 출력을 설정하고 워크플로에서 사용할 수 있습니다. 액션의 출력 설정에 대한 자세한 내용은 "GitHub Actions에 대한 워크플로 명령"을 참조하세요.

예: Docker 컨테이너 및 JavaScript 작업에 대한 출력 선언

outputs:
  sum: # id of the output
    description: 'The sum of the inputs'

`outputs.<output_id>`

필수 출력과 연결할 string 식별자입니다. <output_id> 값은 출력 메타데이터의 맵입니다. <output_id>은 outputs 개체 내에서 고유한 식별자여야 합니다. <output_id>는 문자 또는 _로 시작해야 하며 영숫자, - 또는 _만 포함해야 합니다.

`outputs.<output_id>.description`

필수 출력 매개 변수에 대한 string 설명입니다.

복합 작업의 `outputs`

선택 사항 outputs은 outputs.<output_id> 및 outputs.<output_id>.description와 동일한 매개 변수를 사용하지만("outputsDocker 컨테이너 및 JavaScript 작업에 대한 " 참조) value 토큰도 포함되어 있습니다.

출력은 유니코드 문자열이며 최대 1MB일 수 있습니다. 워크플로 실행의 모든 출력 합계는 최대 50MB가 될 수 있습니다.

예: 복합 작업에 대한 출력 선언

outputs:
  random-number:
    description: "Random number"
    value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
  using: "composite"
  steps:
    - id: random-number-generator
      run: echo "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

`outputs.<output_id>.value`

필수 출력 매개 변수가 매핑될 값입니다. string 또는 컨텍스트가 있는 식으로 설정할 수 있습니다. 예를 들어 steps 컨텍스트를 사용하여 출력의 value를 단계의 출력 값으로 설정할 수 있습니다.

컨텍스트 구문을 사용하는 방법에 대한 자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스"을 참조하세요.

`runs`

필수 JavaScript 작업, 복합 작업 또는 Docker 컨테이너 작업인지와 작업 실행 방식을 지정합니다.

JavaScript 작업에 대한 `runs`

필수 작업 코드의 경로와 코드를 실행하는 데 사용되는 런타임을 구성합니다.

예: Node.js v20 사용

runs:
  using: 'node20'
  main: 'main.js'

JavaScript 작업에 대한 `runs.using`

필수 main에 지정된 코드를 실행하는 데 사용되는 런타임입니다.

Node.js v20의 경우 node20을 사용합니다.

`runs.main`

필수 작업 코드가 포함된 파일입니다. using에 지정된 런타임은 이 파일을 실행합니다.

`runs.pre`

선택 사항 main: 작업이 시작되기 전에 작업 시작 시 스크립트를 실행할 수 있습니다. 예를 들어 pre:를 사용하여 필수 조건 설정 스크립트를 실행할 수 있습니다. using 구문으로 지정된 런타임은 이 파일을 실행합니다. pre: 작업은 기본적으로 항상 실행되지만 runs.pre-if를 사용하여 이를 재정의할 수 있습니다.

이 예제에서 pre: 작업은 setup.js라는 스크립트를 실행합니다.

runs:
  using: 'node20'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

`runs.pre-if`

선택 사항 pre: 작업 실행을 위한 조건을 정의할 수 있습니다. pre: 작업은 pre-if의 조건이 충족되는 경우에만 실행됩니다. 설정하지 않으면 pre-if의 기본값은 always()입니다. pre-if에서 상태 검사 함수는 작업 자체의 상태가 아니라 동작의 상태를 기준으로 평가합니다.

아직 실행된 단계가 없으므로 step 컨텍스트를 사용할 수 없습니다.

이 예제에서는 cleanup.js는 Linux 기반 실행기에서만 실행됩니다.

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

`runs.post`

선택 사항 main: 동작이 완료된 후 작업이 끝날 때 스크립트를 실행할 수 있습니다. 예를 들어 post:을 사용하여 특정 프로세스를 종료하거나 필요하지 않은 파일을 제거할 수 있습니다. using 구문으로 지정된 런타임은 이 파일을 실행합니다.

이 예제에서 post: 작업은 cleanup.js라는 스크립트를 실행합니다.

runs:
  using: 'node20'
  main: 'index.js'
  post: 'cleanup.js'

post: 작업은 기본적으로 항상 실행되지만 post-if를 사용하여 이를 재정의할 수 있습니다.

`runs.post-if`

선택 사항 post: 작업 실행을 위한 조건을 정의할 수 있습니다. post: 작업은 post-if의 조건이 충족되는 경우에만 실행됩니다. 설정하지 않으면 post-if의 기본값은 always()입니다. post-if에서 상태 검사 함수는 작업 자체의 상태가 아니라 동작의 상태를 기준으로 평가합니다.

예를 들어 cleanup.js은 Linux 기반 실행기에서만 실행됩니다.

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

복합 작업의 `runs`

필수 복합 작업의 경로를 구성합니다.

`runs.steps`

필수 이 작업에서 실행할 단계입니다. 이는 run 단계 또는 uses 단계일 수 있습니다.

`runs.steps[*].run`

선택 사항 실행하려는 명령입니다. 인라인 또는 작업 저장소에 있는 스크립트일 수 있습니다:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

또는 $GITHUB_ACTION_PATH를 사용할 수 있습니다.

runs:
  using: "composite"
  steps:
    - run: $GITHUB_ACTION_PATH/script.sh
      shell: bash

자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스"을 참조하세요.

`runs.steps[*].shell`

선택 사항 명령을 실행할 셸입니다. "GitHub Actions에 대한 워크플로 구문"에 나열된 모든 셸을 사용할 수 있습니다. run이 설정된 경우 필수입니다.

`runs.steps[*].if`

선택 사항 if 조건을 사용하여 조건이 충족되지 않는 한 단계가 실행되지 않도록 할 수 있습니다. 지원되는 컨텍스트 및 식을 사용하여 조건을 만들 수 있습니다.

if 조건에서 식을 사용하는 경우, 선택에 따라 식 구문(${{ }})을 생략해도 됩니다. GitHub Actions에서 자동으로 if 조건을 식으로 평가하기 때문입니다. 그러나, 이 예외는 어디에나 적용되지는 않습니다.

${{ }} 식 구문을 사용하거나 !이 YAML 형식으로 예약된 표기법이므로 ! 식이 시작될 때 항상 '', "", () 이스케이프를 사용해야 합니다. 예시:

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

자세한 내용은 "워크플로 및 작업에서 식 평가"을 참조하세요.

예: 컨텍스트 사용

이 단계는 이벤트 유형이 pull_request이고 이벤트 작업이 unassigned인 경우에만 실행됩니다.

steps:
  - run: echo This event is a pull request that had an assignee removed.
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}

예: 상태 검사 함수 사용

my backup step은 복합 작업의 이전 단계가 실패한 경우에만 실행됩니다. 자세한 내용은 "워크플로 및 작업에서 식 평가"을 참조하세요.

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

`runs.steps[*].id`

선택 사항 단계의 고유 식별자입니다. id를 사용하여 컨텍스트에서 단계를 참조할 수 있습니다. 자세한 내용은 "워크플로 실행에 대한 컨텍스트 정보에 액세스"을 참조하세요.

`runs.steps[*].env`

선택 사항 해당 단계에 대해서만 환경 변수의 map을 설정합니다. 워크플로에 저장된 환경 변수를 수정하려면 복합 단계에서 echo "{name}={value}" >> $GITHUB_ENV를 사용합니다.

`runs.steps[*].working-directory`

선택 사항 명령이 실행되는 작업 디렉터리를 지정합니다.

`runs.steps[*].uses`

선택 사항 작업 단계의 일부로 실행할 작업을 선택합니다. 작업은 재사용 가능한 코드 단위입니다. 워크플로와 동일한 리포지토리, 퍼블릭 리포지토리 또는 게시된 Docker 컨테이너 이미지에 정의된 작업을 사용할 수 있습니다.

Git 참조, SHA 또는 Docker 태그 번호를 지정하여 사용 중인 작업의 버전을 포함하는 것이 좋습니다. 버전을 지정하지 않으면 작업 소유자가 업데이트를 게시할 때 워크플로가 중단되거나 예기치 않은 동작이 발생할 수 있습니다.

릴리스된 작업 버전의 커밋 SHA를 사용하는 것이 안정성 및 보안 측면에서 가장 안전합니다.
특정 주요 작업 버전을 사용하면 호환성을 유지하면서 중요한 수정 및 보안 패치를 받을 수 있습니다. 또한 워크플로가 계속 작동하도록 합니다.
작업의 기본 분기를 사용하는 것이 편리할 수 있지만 다른 사용자가 호환성이 손상되는 변경으로 새 주 버전을 릴리스하는 경우 워크플로가 중단될 수 있습니다.

일부 작업에는 with 키워드를 사용하여 설정해야 하는 입력이 필요합니다. 작업의 추가 정보 파일을 검토하여 필요한 입력을 확인합니다.

runs:
  using: "composite"
  steps:
    # Reference a specific commit
    - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v4
    # Reference a specific version
    - uses: actions/checkout@v4.2.0
    # Reference a branch
    - uses: actions/checkout@main
    # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
    - uses: actions/aws/ec2@main
    # References a local action
    - uses: ./.github/actions/my-action
    # References a docker public registry action
    - uses: docker://gcr.io/cloud-builders/gradle
    # Reference a docker image published on docker hub
    - uses: docker://alpine:3.8

`runs.steps[*].with`

선택 사항 작업에 의해 정의된 입력 매개 변수의 map입니다. 각 입력 매개 변수는 키/값 쌍입니다. 자세한 내용은 예: 입력 지정을 참조하세요.

runs:
  using: "composite"
  steps:
    - name: My first step
      uses: actions/hello_world@main
      with:
        first_name: Mona
        middle_name: The
        last_name: Octocat

`runs.steps[*].continue-on-error`

선택적 단계가 실패할 때 작업이 실패하지 않도록 합니다. 이 단계가 실패해도 작업이 통과되도록 하려면 true로 설정합니다.

선택 사항 entrypoint 작업이 시작되기 전에 스크립트를 실행할 수 있습니다. 예를 들어 pre-entrypoint:를 사용하여 필수 조건 설정 스크립트를 실행할 수 있습니다. GitHub Actions은(는) docker run을 사용하여 이 작업을 시작하고 동일한 기본 이미지를 사용하는 새 컨테이너 내에서 스크립트를 실행합니다. 즉, 런타임 상태가 주 entrypoint 컨테이너와 다르며 필요한 모든 상태는 작업 영역 HOME 또는 STATE_ 변수로 액세스해야 합니다. pre-entrypoint: 작업은 기본적으로 항상 실행되지만 runs.pre-if를 사용하여 이를 재정의할 수 있습니다.

using 구문으로 지정된 런타임은 이 파일을 실행합니다.

이 예제에서 pre-entrypoint: 작업은 setup.sh라는 스크립트를 실행합니다.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  pre-entrypoint: 'setup.sh'
  entrypoint: 'main.sh'

`runs.image`

필수 작업을 실행하기 위한 컨테이너로 사용할 Docker 이미지입니다. 값은 Docker 기본 이미지 이름, 리포지토리의 로컬 Dockerfile, Docker Hub 또는 다른 레지스트리의 퍼블릭 이미지일 수 있습니다. 리포지토리에 로컬인 Dockerfile을 참조하려면 파일 이름이 Dockerfile이어야 하고 작업 메타데이터 파일에 상대적인 경로를 사용해야 합니다. docker 애플리케이션은 이 파일을 실행합니다.

`runs.env`

선택 사항 컨테이너 환경에서 설정할 환경 변수의 키/값 맵을 지정합니다.

`runs.entrypoint`

선택 사항 Dockerfile의 Docker ENTRYPOINT를 재정의하거나 아직 지정하지 않은 경우 설정합니다. Dockerfile이 ENTRYPOINT를 지정하지 않거나 ENTRYPOINT 명령어를 재정의하려는 경우 entrypoint를 사용합니다. entrypoint를 생략하면 Docker ENTRYPOINT 명령에서 지정한 명령이 실행됩니다. Docker ENTRYPOINT 명령에는 shell 형식과 exec 형식이 있습니다. Docker ENTRYPOINT 문서에서는 ENTRYPOINT 명령의 exec 형식을 사용하는 것이 좋습니다.

entrypoint이 실행되는 방식에 대한 자세한 내용은 "GitHub Actions에 대한 Dockerfile 지원"을 참조하십시오.

`runs.post-entrypoint`

선택 사항 runs.entrypoint 작업이 완료되면 정리 스크립트를 실행할 수 있습니다. GitHub Actions은(는) docker run을 사용하여 이 작업을 시작합니다. GitHub Actions은(는) 동일한 기본 이미지를 사용하여 새 컨테이너 내에서 스크립트를 실행하기 때문에 런타임 상태는 기본 entrypoint 컨테이너와 다릅니다. 작업 영역인 HOME에서 또는 STATE_ 변수로 필요한 모든 상태에 액세스할 수 있습니다. post-entrypoint: 작업은 기본적으로 항상 실행되지만 runs.post-if를 사용하여 이를 재정의할 수 있습니다.

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - 'bzz'
  entrypoint: 'main.sh'
  post-entrypoint: 'cleanup.sh'

`runs.args`

선택 사항 Docker 컨테이너에 대한 입력을 정의하는 문자열 배열입니다. 입력에는 하드 코드된 문자열이 포함될 수 있습니다. GitHub은(는) 컨테이너가 시작될 때 args를 컨테이너의 ENTRYPOINT에 전달합니다.

args는 Dockerfile의 CMD 명령 대신 사용됩니다. Dockerfile에서 CMD를 사용하는 경우 기본 설정에 따라 정렬된 지침을 사용합니다.

작업의 README에서 필요한 인수를 문서화하고 CMD 명령에서 생략합니다.
어떤 args도 지정하지 않고 작업을 사용할 수 있는 기본값을 사용합니다.
작업이 --help 플래그 또는 이와 유사한 항목을 노출 하는 경우 이를 사용하여 작업을 자체 문서화합니다.

환경 변수를 작업에 전달해야 하는 경우 작업이 명령 셸을 실행하여 변수 대체를 수행하는지 확인하세요. 예를 들어 entrypoint 특성이 "sh -c"로 설정된 경우 args는 명령 셸에서 실행됩니다. 또는 Dockerfile이 ENTRYPOINT를 사용하여 동일한 명령("sh -c")을 실행하는 경우 args는 명령 셸에서 실행됩니다.

CMD 명령어를 GitHub Actions와 함께 사용하는 방법에 대한 자세한 내용은 "GitHub Actions에 대한 Dockerfile 지원"을 참조하십시오.

예: Docker 컨테이너에 대한 인수 정의

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

`branding`

선택 사항 색상과 깃털 아이콘을 사용하여 배지를 만들어 작업을 맞춤화하고 구별할 수 있습니다. 배지는 GitHub Marketplace에서 작업 이름 옆에 표시됩니다.

예: 작업에 대한 브랜딩 구성

branding:
  icon: 'award'
  color: 'green'

coffee
columns
divide-circle
divide-square
divide
frown
hexagon
key
meh
mouse-pointer
smile
tool
x-octagon

현재 지원되는 모든 아이콘의 전체 목록

activity
airplay
alert-circle
alert-octagon
alert-triangle
align-center
align-justify
align-left
align-right
anchor
aperture
archive
arrow-down-circle
arrow-down-left
arrow-down-right
arrow-down
arrow-left-circle
arrow-left
arrow-right-circle
arrow-right
arrow-up-circle
arrow-up-left
arrow-up-right
화살표 위로
at-sign
award
bar-chart-2
bar-chart
battery-charging
battery
bell-off
bell
블루투스
bold
book-open
book
bookmark
box
briefcase
calendar
camera-off
camera
cast
check-circle
check-square
check
chevron-down
chevron-left
chevron-right
chevron-up
chevrons-down
chevrons-left
chevrons-right
chevrons-up
circle
clipboard
clock
cloud-drizzle
cloud-lightning
cloud-off
cloud-rain
cloud-snow
cloud
code
command
compass
copy
corner-down-left
corner-down-right
corner-left-down
corner-left-up
corner-right-down
corner-right-up
corner-up-left
corner-up-right
CPU
credit-card
crop
crosshair
database
delete
disc
dollar-sign
download-cloud
download
droplet
edit-2
edit-3
edit
external-link
eye-off
eye
fast-forward
feather
file-minus
file-plus
file-text
file
film
filter
flag
folder-minus
folder-plus
folder
gift
git-branch
git-commit
git-merge
git-pull-request
globe
grid
hard-drive
hash
headphones
heart
help-circle
home
image
inbox
info
italic
layers
layout
life-buoy
link-2
link
list
loader
lock
log-in
log-out
mail
map-pin
map
maximize-2
maximize
menu
message-circle
message-square
mic-off
mic
minimize-2
minimize
minus-circle
minus-square
minus
monitor
moon
more-horizontal
more-vertical
move
music
navigation-2
navigation
octagon
package
paperclip
pause-circle
pause
percent
phone-call
phone-forwarded
phone-incoming
phone-missed
phone-off
phone-outgoing
phone
pie-chart
play-circle
play
plus-circle
plus-square
plus
pocket
power
printer
radio
refresh-ccw
refresh-cw
repeat
rewind
rotate-ccw
rotate-cw
rss
save
scissors
search
send
server
settings
share-2
share
shield-off
shield
shopping-bag
shopping-cart
shuffle
사이드바
skip-back
skip-forward
slash
슬라이더
smartphone
speaker
square
star
stop-circle
sun
sunrise
sunset
table
tablet
tag
target
terminal
thermometer
thumbs-down
thumbs-up
toggle-left
toggle-right
trash-2
trash
trending-down
trending-up
triangle
truck
tv
type
umbrella
밑줄
unlock
upload-cloud
upload
user-check
user-minus
user-plus
user-x
user
users
video-off
video
voicemail
volume-1
volume-2
volume-x
volume
watch
wifi-off
wifi
wind
x-circle
x-square
x
zap-off
zap
zoom-in
zoom-out

이 문서의 내용