IaC/CI CD Tool

2. Github Action (With Syntax)

Somaz 2023. 5. 22. 18:36
728x90
반응형

Overview

이번 글에서는 GitHub Actions를 사용할 때 반드시 이해하고 넘어가야 할 워크플로 문법(Syntax) 전반을 정리했다.

 

GitHub Actions는 단순한 CI/CD 도구를 넘어, 코드 기반으로 모든 자동화 파이프라인을 정의할 수 있게 해주는 강력한 플랫폼이다. 특히 복잡한 트리거 조건, 다양한 입력/출력, 재사용 가능한 워크플로 설계 등 유연한 구성 능력이 큰 장점이다.

 

 

이번 포스팅에서 다룬 주요 항목은 다음과 같다.

  • on 구문을 통한 트리거 조건 설정 (push, pull_request, workflow_dispatch, workflow_run 등)
  • workflow_call을 활용한 재사용 가능한 워크플로 설계
  • jobs 및 steps의 구조 이해와 needs, if, outputs, secrets, env 사용법
  • runs-on, uses, with 등 실행 환경 및 워크플로 구성 방식
  • workflow_dispatch.inputs와 workflow_call.inputs의 차이점과 활용 팁

 

이러한 문법 요소들을 종합적으로 이해하고 활용한다면, GitHub Actions로 복잡한 자동화 로직도 깔끔하고 재사용성 높은 구조로 작성할 수 있다.

 

 

https://docs.github.com/ko/enterprise-cloud@latest/actions/using-workflows/about-workflows

 

 

📅 관련 글

2023.04.27 - [IaC/CI CD Tool] - 1. Github Action이란?

2023.05.22 - [IaC/CI CD Tool] - 2. Github Action (With Syntax)

2023.05.22 - [IaC/CI CD Tool] - 3. Github Action (With Automate Pull Request)

2024.03.12 - [IaC/CI CD Tool] - 4. Github Action (With Matrix Strategy)

2024.03.12 - [IaC/CI CD Tool] - 5. Github Action (With Using jobs in a workflow & Choosing the runner for a job)

2024.03.15 - [IaC/CI CD Tool] - 6. Github Action (With Using Concurrency)

2024.05.28 - [IaC/CI CD Tool] - 7. Github Action Build and Push(with GCP Artifact Registry)

2024.05.28 - [IaC/CI CD Tool] - 7. Github Action Build and Push(with GCP Artifact Registry)

2024.06.20 - [IaC/CI CD Tool] - 8. Github Action Template 생성후 MarketPlace 등록하기

2024.11.10 - [IaC/CI CD Tool] - 9. Github Action Steps Context 활용법

2025.01.22 - [IaC/CI CD Tool] - 10. Github Action Hosted Runner 생성

 

 

 

 

 

Github Action 문법

 

 

Workflow란?

GitHub Actions에서 최상위 개념은 워크플로(Workflow)이다.

워크플로는 쉽게 말해 '작업의 흐름'으로, 특정한 목적을 위한 일련의 실행 트리거, 환경, 기능들을 모두 포함한다.

​

 

 

 

 

Workflow syntax for GitHub Actions

워크플로는 하나 이상의 작업으로 구성된 구성 가능한 자동 프로세스이다.

워크플로 구성을 정의하려면 YAML 파일을 생성해야 한다.

​

 

 

on

워크플로를 자동으로 트리거하려면 를 사용하여 on 워크플로를 실행할 수 있는 이벤트를 정의한다.

on:
  push:
    branches:
      - main
      - 'releases/**'
  • 특정 예에서 'releases/**'는 계층 구조의 깊이에 관계없이 releases/로 시작하는 모든 branch와 일치한다. releases/v1, releases/v2, releases/2023/may/ver3 등과 같은 branch와 일치할 수 있다.
  • 반면에 releases/*를 사용한 경우 releases/ 바로 아래의 branch만 일치하고 releases/2023/may/ver3과 같은 하위 디렉토리의 branch는 일치하지 않는다.

 

on:
  pull_request:
    branches: [master]
  • push 뿐 아니라 pull request에 대해서도 트리거를 설정할 수 있다.

 

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
  • 패턴이 branches-ignore패턴과 일치하면 워크플로가 실행되지 않는다.
  • A branch named mona/octocat (refs/heads/mona/octocat)
  • A branch whose name matches releases/**-alpha, like releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

 

 

 

on.workflow_call.inputs & .ouputs & .secrets 

재사용 가능한 워크플로의 입력 및 출력을 정의하는 데 사용한다. 호출된 워크플로에 사용할 수 있는 암호를 매핑할 수도 있다.

# call workflow 구문
  call-ts-generate:
    needs: [ check-diff, call-artifact, call-data-deploy ]
    name: Call ts-generate workflow
    uses: ./.github/workflows/somaz-generate.yml
    with:
      environment: ${{ needs.check-diff.outputs.environment }}
    secrets: inherit
  • with을 사용해 environment 변수를 somaz-generate.yml에 전달한다.
  • 재사용 가능한 워크플로를 호출하는 워크플로는 inherit키워드를 사용하여 암호를 암시적으로 전달할 수 있다.
    • 동일한 organization에 속한 경우 secrets을 공유한다.

키워드를 사용하여 inherit모든 호출 워크플로의 암호를 호출된 워크플로에 전달한다. 

여기에는 호출 워크플로가 액세스할 수 있는 모든 비밀, 즉 조직, 리포지토리 및 환경 비밀이 포함된다. 

키워드 inherit는 동일한 조직 내의 리포지토리 간에 또는 동일한 엔터프라이즈 내의 조직 간에 비밀을 전달하는 데 사용할 수 있다.

​

GitHub Organization secrets

 

name: Trigger somaz-generate

on:
  workflow_call:
    inputs:
      environment:
        description: Target Branch
        type: string
        required: true
    secrets:
      CICD_PAT:
        required: true
  • 위와 같이 environment와 secrets의 변수를 받을 수 있다.
  • required 옵션을 줘서 작업을 완료하는 데 필요한 모든 데이터가 워크플로에 있는지 확인할 수 있다. 

 

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}
  • outputs은 말 그대로 출력내용이다. 위의 예시는 재사용 가능한 출력내용 예시이다.

 

 

 

on.workflow_run.<branches|branches-ignore>

이벤트 를 사용할 때 워크플로를 트리거하기 위해 트리거 워크플로가 실행되어야 하는 branch를 지정할 수 있다.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      
on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'
  • 예를들어  빌드라는 워크플로가 ' releases/** ' 로 시작하는 모든 branch 에서만 실행되도록 할 수 있다.
  • branches-ignore 옵션을 줘서 빌드라는 워크플로가 canary 라는 이름이 아닌 분기에서 실행되는 경우에만 실행된다.
  • 빌드라는 워크플로가 releases/10 또는 releases/beta/mona라는 branch에서 실행되지만 releases/10-alpha, releases/beta/3-alpha 또는 main이 아닐때 다음 트리거가 있는 워크플로가 실행된다.

 

 

on.workflow_dispatch.inputs & .outputs & .secrets

웹에서 수동으로 트리거될때 해당 값들을 input 받을 수 있다.

workflow_dispatch는 workflow를 수동으로 trigger시킨다는 의미이다.

on:
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
    inputs:
      environment:
        type: environment
        description: Select the environment
        required: true
      service:
        description: Which service to be built. api or admin or etc...
        required: true
        type: choice
        options:
          - adam

Github action workflow run 화면

on.workflow_dispatch.inputs & .outputs & .secrets 은 workflow_call에서 사용했던 방법과 동일하다.

중요한 점은 수동으로 트리거시킬때 사용한다.

 

 

 

env

워크플로의 모든 작업 단계에서 사용할 수 있는 변수이다. type은 map이다.

env:
  SERVER: production

 

아래와 같이 여러가지 변수를 정의할수도 있다.

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

 

 

 

 

 

 

 

 

 

jobs

워크플로는 하나 이상의 작업으로 구성된다. 작업은 명령을 실행하거나, 스크립트를 실행하거나, 작업(별도의 리포지토리에 저장된 미리 작성된 스크립트)을 호출하는 단계이다.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: 14
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

 

 

 

jobs.<job_id>.outputs & .secrets & .env 

jobs.<job_id>.outputs & .secrets & .env 사용법은 위에서 설명했던 내용과 동일하다.

 

 

 

jobs.<job_id>.needs

needs는 해당 작업이 시작되기전에 완료되어야 하는 작업을 정의한다.

  call-deploy:
    needs: [ build ]
    name: Call deploy workflow
    uses: ./.github/workflows/deploy.yml
    with:
      service: ${{ github.event.inputs.service }}
      environment: ${{ github.event.inputs.environment }}
      tag: ${{ needs.build.outputs.tag }}
      trigger_user: ${{ github.event.sender.login }}
    secrets: inherit
  • build 작업이 완료되기 전까지는 call-deploy 작업은 시작되지 않는다.
  • github.event는 워크플로를 트리거한 이벤트의 페이로드를 나타낸다.
    • pull_request 또는 push 또는 그 밖의 event
  • workflow_dispatch 이벤트로 수동으로 트리거된 경우에 github.event.inputs가 사용된다.
  • github.event.sender.login은 이벤트를 트리거한 사용자의 사용자 이름을 나타낸다.
jobs:
  job1:
    ...
  job2:
    needs: job1
    ...
  job3:
    needs: [job1, job2]
    runs-on: ubuntu-latest
    if: always()
    steps:
      - name: Check job1 and job2 outcome
        run: |
          echo "Job1 outcome: ${{ needs.job1.result }}"
          echo "Job2 outcome: ${{ needs.job2.result }}"
  • always()는 job1 및 job2의 결과에 관계없이 job3이 항상 실행되도록 한다.
  • always()가 없으면 job3은 job1과 job2가 모두 성공한 경우에만 실행된다.
  • needs.job1,2.result를 사용해서 해당 job의 결과를 확인할 수 있다.

 

 

 

jobs.<job_id>.if

조건이 충족되지 않는 한 작업이 실행되지 않도록 할 수 있다.

name: 1.Build

on:
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
    inputs:
      environment:
        type: environment
        description: Select the environment
        required: true

jobs:
  build:
    name: Build Image
    runs-on: ubuntu-20.04

    steps:
      - name: Check out branch
        uses: actions/checkout@v2

      - name: Set AWS region JP for prod environment
        if: ${{ github.event.inputs.environment == 'stage' || github.event.inputs.environment == 'production' }}
        id: set-prod-region
        run: echo "AWS_REGION=ap-northeast-1" >> $GITHUB_ENV

      - name: Set AWS region KR
        if: ${{ steps.set-prod-region.outcome == 'skipped' }}
        run: echo "AWS_REGION=ap-northeast-2" >> $GITHUB_ENV
  • environment 변수의 값이 stage 나 production이면 AWS_REGION의 변수의 값을 ap-northeast-1(도쿄)로 지정한다.
  • steps.set-prod-region.outcome의 값이 skipped이면 AWS_REGION의 변수의 값을 ap-northeast-2(한국)로 지정한다.

'outcome'은 다음과 같은 여러 상태 중 하나를 가질 수 있다.

  • success
  • failure
  • cancelled
  • skipped

​

 

 

jobs.<job_id>.runs-on

jobs.<job_id>.runs-on작업을 실행할 시스템 OS를 정의하는 데 사용한다.

https://docs.github.com/ko/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on

jobs:
  build:
    name: Build Image
    runs-on: ubuntu-20.04

 

 

 

jobs.<job_id>.uses

job으로 실행할 재사용 가능한 워크플로 파일의 위치를 지정하면 된다.

  • {owner}/{repo}/.github/workflows/{filename}@{ref} 
    • for reusable workflows in public, internal and private repositories.
  • ./.github/workflows/{filename} 
    • for reusable workflows in the same repository.
jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

 

 

 

jobs.<job_id>.with

재사용 가능한 워크플로를 호출하는 데 작업이 사용되는 경우 with을 사용하여 호출된 워크플로에 전달시킬 수 있다.

전달하는 모든 변수는 호출된 워크플로에 정의된 변수와 일치해야 한다.

  call-deploy:
    needs: [ build ]
    name: Call deploy workflow
    uses: ./.github/workflows/deploy.yml
    with:
      service: ${{ inputs.service }}
      environment: ${{ inputs.environment }}
      tag: ${{ needs.build.outputs.tag }}
      trigger_user: ${{ github.event.sender.login }}
      is_build_triggered_by_workflow_dispatch: ${{ needs.build.outputs.is_build_triggered_by_workflow_dispatch }}
      build_branch: ${{ github.ref_name }}
    secrets: inherit
  workflow_call:
    inputs:
      service:
        type: string
        description: Which service to be built. api or admin or etc...
        required: true
      environment:
        type: string
        description: Select the environment
        required: true
      tag:
        type: string
        description: Built image tag
        required: true
      trigger_user:
        type: string
        description: CI&CD trigger user
        required: true
      is_build_triggered_by_workflow_dispatch:
        type: string
        description: Value for determine build workflow trigger
        required: true
      build_branch:
        type: string
        description: Build source branch
        required: true

 

 

 

 

 

 

 

 

 

마무리

GitHub Actions는 단순한 트리거 기반 빌드를 넘어, 협업과 배포, 테스트, 보안 등 다양한 DevOps 영역에 걸친 자동화를 코드로 정의할 수 있게 도와준다.

 

특히 이번 글에서 다룬 문법들은 다음과 같은 상황에 유용하게 쓰일 수 있다.

  • 동적 환경에 따른 분기 처리
  • 다양한 트리거에 대응한 복잡한 워크플로 설계
  • 여러 레포 간의 재사용 가능한 액션 설계
  • 보안 비밀(secret) 및 context 변수 활용

 

이제 단순한 push 빌드 설정을 넘어, 진짜 프로덕션 환경에 적용 가능한 실전형 GitHub Actions 설계에 도전해보자.

 

 

 

 

 

 

Reference

https://docs.github.com/ko/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions

 

https://www.daleseo.com/github-actions-steps/

 

 

 

 

728x90
반응형

'IaC > CI CD Tool' 카테고리의 다른 글

4. GitLab 버전 업그레이드  (0) 2023.08.08
3. Github Action (With Automate Pull Request)  (0) 2023.05.23
1. Github Action이란?  (0) 2023.05.19
ArgoCD란?  (0) 2023.05.17
3. GitLab이란? / GitLab CI/CD  (0) 2023.04.24

'IaC/CI CD Tool'의 다른글

  • 현재글2. Github Action (With Syntax)

관련글

댓글

티스토리툴바