GitHub Actions Workflow 문법 정리

들어가며

골든 이미지 파이프라인을 구성하면서 Github repo에 특정 이벤트가 발생했을 때 작업을 트리거하는 설정이 필요했다. 이 과정에서 Github Actions을 사용하게 되었고, 작업을 실행하는 workflow를 구성해야 했다. workflow는 리포지토리에 체크인된 YAML 파일에 의해 정의되기 때문에 파일 작성을 위한 syntax 공부가 필요했다.

이 글에은 해당 workflow 구성 파일 작성을 위해 공식 문서를 보면서 정리한 내용이다.

 

 

Workflow syntax for GitHub Actions

설명에 사용하는 전체 예제 코드는 다음과 같다.

# https://docs.github.com/en/actions/using-workflows/about-workflows

name: learn-github-actions
run-name: ${{ github.actor }} is learning GitHub Actions
on: [push]

jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

위 코드는 Github UI에서 다음과 같이 표현된다.

🔘 name - 선택사항

workflow의 이름. 리포지토리의 Actions 탭에 표시된다.

name: learn-github-actions

 

🔘 run-name - 선택사항

workflow에서 생성된 workflow 실행 이름

리포지토리의 Actions 탭에 있는 workflow 실행 목록에 표시된다. 실행 이름이 작성되지 않은 경우 이벤트별 정보로 설정된다. 예를들어 push 나 pull_request에 의해 트리거된 workflow라면 커밋 메시지가 표시되는 식이다.

# 실행을 트리거한 github.actor의 이름을 표시
run-name: ${{ github.actor }} is learning GitHub Actions

 

🔘 on

workflow를 트리거하는 이벤트

on: [push, fork]와 같이 한 번에 여러 이벤트를 설정할 수도 있고, 시간을 지정하거나 특정 파일, 태그, 브랜치 변경이 발생한 경우에만 workflow가 실행되도록 제한할 수도 있다.

# branch에 상관없이 push가 발생할 때마다 workflow 실행
on: [push]

 

on.<pull_request|pull_request_target>.<branches|branches-ignore>

pull_request 및 pull_request_target 이벤트를 사용할 때 특정 브랜치를 대상으로 하는 요청에 대해서만 워크플로우를 실행하도록 구성할 수 있다. 브랜치 이름은 *, **, +,?,! 같은 문자를 사용해서 패턴으로 정의하는 것도 가능하다. 특정 브랜치를 포함하는 것뿐만 아니라 특정 브랜치만 제외하는 것도 가능하다

# main 브랜치에 pull_request가 발생했을 때 workflow 실행 
on:
  pull_request:
    branches:    
      - main

 

on.push.<branches|tags|branches-ignore|tags-ignore>

push 이벤트를 사용할 때 특정 브랜치 또는 태그에서 실행되도록 정의할 수도 있다.

# 다음 대상에서 push 이벤트가 발생할 때 workflow 실행 
# - 브랜치 이름이 main, mona/octocat이거나 releases/로 시작하는 경우 
# - tag 이름이 v2이거나 v1.으로 시작하는 경우 
on:
  push:
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    tags:        
      - v2
      - v1.*

 

🔘 jobs

workflow 실행은 하나 이상의 jobs로 구성된다. 이 job들은 기본적으로 병렬로 실행되기 때문에 순차적인 작업 수행이 필요한 경우 jobs.<job_id>.needs 또는 steps 키워드를 사용해서 순차적으로 실행되도록 의존성을 추가해야한다.

jobs:

모든 job은 string 형식의 id를 가지며, run-on으로 지정된 러너 환경에서 실행된다.

# 최신버전의 ubuntu에서 실행되는 check-bats-version이라는 작업을 정의 
  check-bats-version:
    runs-on: ubuntu-latest

 

jobs.<job_id>

jobs 하위에 job_id를 부여하여 각 작업을 구별할 수 있다. 다음 예시에서는 job_id가 my_first_job, my_second_job인 두 개의 job이 생성되었다. job_id의 하위 키는 해당 작업의 속성을 정의한다.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

 

jobs.<job_id>.name

여기서 정의한 name은 Github UI에 표시된다.

 

jobs.<job_id>.needs

앞서 설명했듯 job은 기본적으로 병렬적으로 실행된다. needs 조건을 추가하면 종속성이 생성되어 특정 작업이 완료될때까지 다음 작업이 시작되지 않는다. 즉 종속성에 따라 암시적으로 순서가 정의되고, 하나라도 실패하면 해당 작업이 실행되지 않는다. 대신 종속성이 없는 작업의 경우 병렬적으로 실행된다.

# job2가 시작되기 전에 job1이 완료되어야 하고, job3을 실행하기 전에 job1,2가 성공해야한다. 
# job1, job2, job3이 순차적으로 실행되도록 하는 예시 
jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

 

jobs.<job_id>.runs-on

job을 실행할 머신의 타입을 정의하는 부분이다. 머신의 유형에는 Github-hosted runner와 self-hosted runner가 있다.

# linux, x64, and gpu 라벨을 가진 자체 호스팅 러너에서만 실행
runs-on: [self-hosted, linux, x64, gpu]

# GitHub-hosted runner로 최신 ubuntu 이미지 사용  
runs-on: ubuntu-latest

다음은 사용 가능한 GitHub-hosted runner 유형이다. (2023.06.22 기준)

Runner image	YAML workflow label	Notes
Windows Server 2022	windows-latest or windows-2022	The windows-latest label currently uses the Windows Server 2022 runner image.
Windows Server 2019	windows-2019	None
Ubuntu 22.04	ubuntu-latest or ubuntu-22.04	The ubuntu-latest label currently uses the Ubuntu 22.04 runner image.
Ubuntu 20.04	ubuntu-20.04	None
macOS 13 Ventura [Beta]	macos-13 or macos-13-xl	None
macOS 12 Monterey	macos-latest, macos-12, macos-latest-xl or macos-12-xl	The macos-latest and macos-latest-xl workflow labels currently uses the macOS 12 runner image.
macOS 11 Big Sur	macos-11	None

 

jobs.<job_id>.steps

steps를 사용하면 각 작업이 파일에 명시된 순서대로 실행된다.

 

jobs.<job_id>.steps[*].uses

작업 단계의 일부로 실행할 작업을 선택하는 부분으로 uses 값은 사용할 작업의 이름과 버전을 나타낸다. {owner}/{repo}@{ref}와 같은 형식으로 표시된다. actions/*는 Github에서 제공하는 공식 작업이다.

# actions 조직에서 만든 checkout 작업의 버전3을 사용
# checkout: https://github.com/actions/checkout
    steps:
      - uses: actions/checkout@v3

# Docker 컨테이너 이미지를 작업으로 사용
    steps:
      -  uses: docker://alpine:3.8

 

jobs.<job_id>.steps[*].with

with 값은 특정 액션에 매개변수를 전달하는 데 사용된다. with 키워드는 run 키워드가 사용되는 단계에서는 사용할 수 없다. with에서 사용할 수 있는 매개변수는 각 액션의 문서에서 확인할 수 있다. (checkout 액션에 대해 사용할 수 있는 with 값은 여기)

# node-version이 14라는 매개변수를 actions/setup-node@v3 액션에 전달
     steps:
      - uses: actions/setup-node@v3
        with:
          node-version: '14'

 

jobs.<job_id>.steps[*].run

각 단계별로 실행할 명령을 정의한다. 이 명령은 runner의 셸에서 실행된다.

# npm install -g bats 명령 실행 후 bats -v 명령 실행 
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

---

 

참고자료

https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions