github action 워크플로우 작성방법 및 구성요소

❖ 워크플로우 작성

• 프로젝트 최상단에 .github/workflows 디렉토리를 만들고 ci or cd 스크립트를 실행할 yml or yaml 파일을 생성합니다.
• 여러개의 파일을 구분하여 워크플로우를 작성할 수 있습니다.

.github/workflows/ci.yml
.github/workflows/cd.yml
...

• 워크플로우 파일 예제

# 선택사항 - 워크플로우 이름
name: learn-github-actions

#선택사항 - github repository's "Actions" tab에 보여질 이름입니다.
run-name: ${{ github.actor }} is learning GitHub Actions

# 트리거를 지정합니다.
on: [push]

jobs:
  check-bats-version: # check-bats-version으로 job 이름 정의
    runs-on: ubuntu-latest # 우분투 최신버전으로 실행한다.
    steps:
      - uses: actions/checkout@v4 # 체크아웃 합니다.
      - uses: actions/setup-node@v4 # node 20 version을 설치합니다.
        with:
          node-version: '20'
      - run: npm install -g bats # bats를 설치합니다.
      - run: bats -v # bats 버전을 출력합니다.

❖ 워크플로우 옵션

◆ ON

• 워크플로우를 트리거하는 옵션들이 굉장히 많습니다. 가장 많이 사용되는 내용으로 정리하였습니다.
• 필요한 트리거가 있는지는 문서를 참고해주세요.
  https://docs.github.com/ko/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows
• 여러개의 트리거를 워크플로우로 정의할 수 있습니다.

1. push - 레포지토리에 변경사항이 푸시될 때 워크플로우가 실행됩니다.

• branches - 특정 브랜치에 푸시된 경우 워크플로우가 실행됩니다.
• tags - 매칭되는 특정 태그가 푸시된 경우 워크플로우가 실행됩니다.
• paths - 특정 파일 경로나 패턴에 맞는 파일이 푸시된 경우 워크플로우가 실행됩니다.

on:
  push:
    branches:
      - main
    tags:
      - 'v1.*'
    paths:
      - 'src/**'

 

2. pull_request - 풀 리퀘스트가 열리거가 업데이트 될 때 실행됩니다.

• types
  • opened - 새로운 풀 리퀘스트가 생성될때
  • synchronize - 이미 열린 풀리퀘스트에 새로운 커밋이 추가될 때
  • reopened - 풀 리퀘스트를 다시 요청할 경우

on:
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize
      - reopened

 

3. schedule - 정기적으로 실행합니다.

• cron - 스케줄을 정의합니다.
• minute (0 - 59), hour (0 - 23), day of the month (1 - 31), month (1 - 12 or JAN-DEC), day of the week (0 - 6 or SUN-SAT)

on:
  schedule:
    - cron: '0 0 * * 1'

 

4. workflow_dispatch

• 수동으로 워크플로우를 트리거할 수 있는 옵션입니다.
• 공식 문서 : https://docs.github.com/ko/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch
• github 의 UI에서 버튼을 클릭하여 실행할 수 있습니다.
• inputs
  • 워크플로우를 수동으로 실행 할 때 사용자 입력값을 받을 수 있습니다.
• 주의
  • 해당 설정 후 진행된 이후 버전의 브랜치에서 사용할 수 있습니다.
  • 그 이전에는 워크플로우 파일이 존재하지 않기 때문에 사용이 불가능합니다.

name: Deploy

on:
  workflow_dispatch:
    inputs:
      stage:
        description: '배포할 환경을 선택하세요'
        required: true
        default: 'dev'
        type: choice
        options:
          - dev
          - stg
          - qa
          - prod

jobs:
    print_data:
        name: build
        runs-on: ubuntu-latest

        steps:
            - uses: actions/checkout@v2
            - name: print env
              run: |
                echo "stage: ${{ github.event.inputs.stage }}"
                echo "Branch name: ${GITHUB_REF#refs/heads/}"
                echo "Tag name: ${GITHUB_REF#refs/tags/}"
                echo "ref name: ${github.ref_name}" # 브랜치라면 브랜치명, tag라면 tag명이 설정된다.

◆ job

• 기본구조

이름	설명
jobs	여러개의 job을 정의할 수 있는 상위 키워드입니다.
job_id	각 job의 고유 식별자, 다른 job에서 의존성을 설정 할 때 사용됩니다.
name	각 job에 대한 설명적인 이름을 정의합니다.
runs-on	job이 실행될 가상환경을 지정합니다.
step	job에서 수행될 구체적인 작업 단계들이며, 각 단계는 순차적으로 실행됩니다.

 

1. runs-on

• job이 실행될 환경을 지정합니다.
• github에서 제공하는 표준 가상 환경을 사용할 수 있으며, 이는 기본적으로 세가지 환경을 지원합니다.
  • https://docs.github.com/ko/actions/writing-workflows/workflow-syntax-for-github-actions#choosing-github-hosted-runners  
  • Ubuntu: ubuntu-latest, ubuntu-24.04, ubuntu-20.04
  • Windows: windows-latest, windows-2022, windows-2019
  • macOS: macos-latest, macos-14, macos-13

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Check Ubuntu version
        run: lsb_release -a

• Self-hosted runner
  • 직접 호스팅한 서버에서 job을 실행할 수도 있습니다. 이 경우 runs-on 필드에 self-hosted라고 지정합니다.
  • https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow

jobs:
  self-hosted-job:
    runs-on: [self-hosted, linux, x64, gpu]
    steps:
      - name: Run on self-hosted runner
        run: echo "Running on self-hosted runner!"

 

2. steps

• steps는 job 내에서 실행될 구체적인 작업을 정의하는 부분입니다.
• name - 각 step의 이름
• uses - 다른 액션 또는 재사용 가능한 작업을 실행할 때 사용합니다.
             github에서 제공하는 기본 액션이나 사용자 정의 액션을 실행할 때 사용됩니다.
• run - 직접 쉘 명령을 실행할 때 사용합니다. 스크립트나 명령을 실행할 때 주로 사용됩니다.
• evn - 각 단계에서 사용할 환경 변수를 설정 할 수 있습니다.

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Run a script
        run: |
          echo "This is a multi-line script"
          ls -al
          
		  - name: Print a custom environment variable
		    run: echo "My variable is $MY_ENV_VAR"
		    env:
		      MY_ENV_VAR: "Hello World"

 

3. job간의 의존성 설정

• needs 키워드를 사용하여 특정 job이 다른 job의 실행 결과에 의존하도록 설정 할 수 있습니다.
• 여러개의 job의 의존성을 연결을 할 경우 대괄호로 정의합니다. [job1, job2]
• needs에 설정 된 job이 완료가 되면 해당 job이 실행됩니다.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build the project
        run: echo "Building..."

  test:
    runs-on: ubuntu-latest
    needs: build  # build job이 완료된 후에 실행됨
    steps:
      - name: Test the project
        run: echo "Testing..."

 

4. 조건부 실행

• job 레벨 조건부

jobs:
  conditional-job:
    runs-on: ubuntu-latest
    if: github.event_name == 'push'  # push 이벤트일 때만 실행
    steps:
      - run: echo "This job runs only on push events"

• step 레벨의 조건부

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Conditional step
        run: echo "This step runs only on the main branch"
        if: github.ref == 'refs/heads/main'

 

5. strategy

• strategy 키워드를 사용하면 여러 환경에서 동일한 job을 반복적으로 실행 할 수 있습니다.
• node의 10, 12, 14 버전을 실행하며 코드를 실행할 수 있습니다.
• 공식 문서 : https://docs.github.com/ko/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [10, 12, 14]
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}

      - name: Run tests
        run: npm test

 

6. timeout-minutes

• job이 너무 오래 실행 될 경우 자동으로 종료되도록 제한 시간을 설정 할 수 있습니다.

jobs:
  example-job:
    runs-on: ubuntu-latest
    timeout-minutes: 10  # 10분 후에 작업이 자동으로 중단됨
    steps:
      - run: sleep 600

 

7. continue-on-error

• 특정 job이 실패해도 워크플로우의 나머지 작업이 계속되도록 설정할 수 있습니다.

jobs:
  example-job:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - run: exit 1  # 실패하지만 계속 진행