0. 들어가며

[BASIC #2]에서 첫 번째 워크플로우를 작성하고 실행해보았다. 이번 포스팅에서는 GitHub Actions의 핵심 문법을 체계적으로 정리하겠다. 모든 문법을 외울 필요는 없지만, 자주 사용되는 패턴은 익혀두면 실무에서 매우 유용하다.

1. 워크플로우 기본 구조

1.1. 가장 기본적인 형태 (name, on, jobs, runs-on, steps)

name: Workflow Name

on: [push]

jobs:
  job-id:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello World"

1.2. 각 요소의 역할

요소  설명  필수 여부
name 워크플로우 이름 선택
on 트리거 이벤트 필수
jobs 실행할 Job들 필수
jobs.<job_id> Job의 고유 식별자 필수
runs-on 실행 환경 필수
steps 실행할 Step들 필수

2. Event (트리거) 상세

2.1. 단일 이벤트

on: push

2.2. 여러 이벤트

on: [push, pull_request]

2.3. 세부 조건 지정

on:
  push:
    branches:
      - main
      - develop
    paths:
      - 'src/**'
      - '!**.md'  # 마크다운 파일 제외
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize
      - reopened

2.4. 주요 이벤트 종류

이벤트  설명
push 코드 push 시
pull_request PR 생성/수정 시
schedule cron으로 정기 실행
workflow_dispatch 수동 실행
release 릴리스 생성 시
issues 이슈 생성/수정 시
watch 스타(Star) 누를 시

2.5. Schedule 예시 (cron)

on:
  schedule:
    # 매일 오전 9시 (UTC) → 한국 시간 오후 6시
    - cron: '0 9 * * *'
    # 매주 월요일 오전 3시
    - cron: '0 3 * * 1'

cron 표현식: 분 시 일 월 요일

3. Runner (실행 환경)

3.1. GitHub 호스팅 러너

jobs:
  ubuntu-job:
    runs-on: ubuntu-latest  # 최신 Ubuntu
  windows-job:
    runs-on: windows-latest  # 최신 Windows Server
  macos-job:
    runs-on: macos-latest    # 최신 macOS

3.2. 특정 버전 지정

runs-on: ubuntu-20.04  # Ubuntu 20.04
runs-on: windows-2019  # Windows Server 2019
runs-on: macos-11      # macOS 11 (Big Sur)

3.3. Self-hosted Runner

runs-on: self-hosted
# 또는 라벨로 지정
runs-on: [self-hosted, linux, x64]

4. Job과 Step 상세

4.1. 여러 Job 정의

jobs:
  build: # 단순 job name
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building..."

  test: # 단순 job name
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing..."

  deploy: # 단순 job name
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

기본적으로 모든 Job은 병렬 실행된다.

4.2. Job 간 의존성 설정 (needs)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building..."

  test:
    needs: build  # build가 성공해야 실행
    runs-on: ubuntu-latest
    steps:
      - run: echo "Testing..."

  deploy:
    needs: [build, test]  # build와 test가 모두 성공해야 실행
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

4.3. Step에서 사용할 수 있는 것들

① uses: Action 사용

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '18'

② run: Shell 명령어 실행

steps:
  - run: echo "Hello World"
  - run: |
      npm install
      npm run build
  - run: |
      if [ -f "file.txt" ]; then
        echo "File exists"
      fi

③ name: Step 이름 지정

steps:
  - name: Print current time
    run: date
  - name: Install dependencies
    run: npm install

5. Action 사용법

5.1. Action이란?

Action은 재사용 가능한 코드 블록이다. 복잡한 작업을 간단하게 사용할 수 있도록 패키징되어 있다.

5.2. 주요 공식 Action

Action  설명
actions/checkout 저장소 코드 가져오기
actions/setup-node Node.js 설치
actions/setup-java Java 설치
actions/setup-python Python 설치
actions/upload-artifact 빌드 결과물 업로드
actions/download-artifact 빌드 결과물 다운로드
actions/cache 의존성 캐싱

5.3. 버전 지정

# 주요 버전 (권장)
- uses: actions/checkout@v4

# 특정 커밋
- uses: actions/checkout@a81bbbf

# 브랜치
- uses: actions/checkout@main

# 도커 이미지
- uses: docker://alpine:3.8

5.4. Marketplace에서 Action 찾기

GitHub Marketplace(https://github.com/marketplace?type=actions)에서 수많은 Action을 찾을 수 있다.

인기 Action 예시:

  • docker/build-push-action: Docker 이미지 빌드 및 Push
  • aws-actions/configure-aws-credentials: AWS 인증 설정
  • google-github-actions/auth: GCP 인증 설정
  • slackapi/slack-github-action: Slack 알림

6. 환경 변수

6.1. Workflow 레벨 환경 변수

env:
  GLOBAL_VAR: "모든 Job에서 사용 가능"

jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - run: echo $GLOBAL_VAR

6.2. Job 레벨 환경 변수

jobs:
  job1:
    runs-on: ubuntu-latest
    env:
      JOB_VAR: "이 Job에서만 사용 가능"
    steps:
      - run: echo $JOB_VAR

6.3. Step 레벨 환경 변수

steps:
  - name: Step with env
    env:
      STEP_VAR: "이 Step에서만 사용 가능"
    run: echo $STEP_VAR

6.4. 환경 변수 사용하기

steps:
  - run: |
      echo "값 출력: $MY_VAR"
      echo "값 출력: ${MY_VAR}"
    env:
      MY_VAR: hello

7. Context (컨텍스트) 변수

7.1. Context란?

GitHub Actions에서 미리 정의된 변수들을 Context라고 한다. ${{ context.property }} 형태로 사용한다.

7.2. 주요 Context

Context  설명  예시
github GitHub 관련 정보 ${{ github.repository }}
env 환경 변수 ${{ env.MY_VAR }}
secrets 비밀 값 ${{ secrets.API_KEY }}
runner Runner 정보 ${{ runner.os }}
job 현재 Job 정보 ${{ job.status }}
steps Step 출력값 ${{ steps.step_id.outputs.result }}

7.3. github Context 예시

steps:
  - run: |
      echo "저장소: ${{ github.repository }}"
      echo "브랜치: ${{ github.ref_name }}"
      echo "커밋 SHA: ${{ github.sha }}"
      echo "액터(실행자): ${{ github.actor }}"
      echo "이벤트 이름: ${{ github.event_name }}"
github 속성  설명
github.repository 소유자/저장소명 (예: octocat/Hello-World)
github.ref_name 브랜치 또는 태그명
github.sha 커밋 SHA
github.actor 워크플로우를 실행한 사용자
github.event_name 트리거된 이벤트 이름
github.workspace Runner의 작업 디렉토리 경로

7.4. secrets Context

민감한 정보는 저장소 Settings > Secrets and variables > Actions에 저장한다.

steps:
  - name: Deploy to server
    env:
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
      API_TOKEN: ${{ secrets.API_TOKEN }}
    run: |
      echo "API 토큰으로 배포 실행"
      # 실제 배포 명령어

8. 조건부 실행 (if)

8.1. 기본 조건문

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'  # main 브랜치에서만 실행
    runs-on: ubuntu-latest
    steps:
      - run: echo "배포 중..."

8.2. 다양한 조건 예시

steps:
  # 특정 파일이 변경된 경우에만 실행
  - name: Run only if src 변경
    if: contains(github.event.head_commit.modified, 'src/')
    run: echo "src 파일이 변경됨"

  # 이전 Step이 실패한 경우에만 실행
  - name: Notify on failure
    if: failure()
    run: echo "이전 Step 실패!"

  # 항상 실행 (성공/실패 관계없이)
  - name: Cleanup
    if: always()
    run: echo "정리 작업"

  # 특정 Job의 결과에 따라
  - name: Run if build succeeded
    if: success() && github.ref == 'refs/heads/main'
    run: echo "빌드 성공!"

8.3. 조건 함수

함수  설명
success() 이전 Step이 모두 성공
failure() 이전 Step 중 실패 있음
always() 항상 실행
cancelled() 워크플로우가 취소됨

9. Matrix 전략

9.1. 기본 Matrix

여러 버전, 여러 환경에서 동시에 테스트할 때 사용한다.

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [14, 16, 18]
        os: [ubuntu-latest, windows-latest]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm test

이 설정은 총 3(node) × 2(os) = 6개의 Job이 병렬 실행된다.

9.2. Matrix 결과 활용

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        include:
          - os: ubuntu-latest
            build-command: apt-get install
          - os: macos-latest
            build-command: brew install
    steps:
      - run: ${{ matrix.build-command }}

10. 출력값 전달하기

10.1. Step 간 출력값 전달

steps:
  - name: Generate output
    id: generator
    run: echo "result=hello" >> $GITHUB_OUTPUT

  - name: Use output
    run: echo "이전 Step의 출력값: ${{ steps.generator.outputs.result }}"

10.2. Job 간 출력값 전달

jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      output1: ${{ steps.step1.outputs.result }}
    steps:
      - name: Step1
        id: step1
        run: echo "result=world" >> $GITHUB_OUTPUT

  job2:
    needs: job1
    runs-on: ubuntu-latest
    steps:
      - run: echo "job1의 출력값: ${{ needs.job1.outputs.output1 }}"

11. 아티팩트 (Artifacts)

11.1. 아티팩트 업로드

빌드 결과물을 저장하고 다음 Job에서 사용하거나 다운로드할 수 있다.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: |
          mkdir dist
          echo "Build result" > dist/output.txt

      - uses: actions/upload-artifact@v3
        with:
          name: build-output
          path: dist/

11.2. 아티팩트 다운로드

jobs:
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: build-output
          path: ./downloaded

      - run: cat downloaded/output.txt

12. 정리

이번 포스팅에서는 GitHub Actions의 핵심 문법을 체계적으로 정리해보았다.

구분  주요 내용
Event push, pull_request, schedule, workflow_dispatch
Runner ubuntu-latest, windows-latest, macos-latest
Job needs로 의존성 설정, 병렬 실행
Step uses(Action), run(쉘 명령어)
Context github, secrets, env, runner
조건문 if, success(), failure(), always()
Matrix 여러 버전/환경 동시 테스트
Artifact 빌드 결과물 저장/공유

'CI&CD > GitHub Actions' 카테고리의 다른 글

[ADVANED #1] GitHub Actions에서 Docker 고급 빌드 전략 (Buildx, 캐싱, 보안)  (0) 2026.02.24
[BASIC #5] 실전 프로젝트: Spring Boot 앱 CI/CD 파이프라인 구축하기  (0) 2026.02.24
[BASIC #4] GitHub Actions 변수와 컨텍스트 마스터하기  (0) 2026.02.24
[BASIC #2] 워크플로우 생성 및 실행 실습  (0) 2025.06.24
[BASIC #1] CI/CD 개념부터 GitHub Actions 이해하기 - 이론편  (0) 2025.06.17

티스토리툴바