GitHub Actions 워크플로우 핵심 명령어 & 사용법 총정리

GitHub Actions 워크플로우 핵심 명령어 & 사용법 총정리

GitHub Actions는 코드를 자동으로 테스트, 빌드, 배포하는 데 사용되는 워크플로우 자동화 도구입니다. 그 중심에 있는 것은 .yml 형식의 워크플로우 설정 파일이고, 이 안에서 사용되는 명령어와 키워드를 이해하면 어떤 자동화든 쉽게 구성할 수 있습니다. 이 글에서는 GitHub Actions에서 가장 자주 사용되는 핵심 명령어와 구조, 그리고 실전 예제를 정리해드립니다.

---

🧱 기본 구조

name: 워크플로우 이름

on: # 트리거 정의
  push:
    branches: [ main ]

jobs: # 실행할 작업
  작업이름:
    runs-on: ubuntu-latest

    steps: # 단계별 실행 명령
      - name: 단계 이름
        run: 실행할 쉘 명령어

---

🔑 주요 명령어 & 키워드 설명

키워드	역할 / 설명
name	워크플로우 또는 단계의 이름 (UI에 표시됨)
on	트리거 설정 (push, pull_request, schedule, workflow_dispatch 등)
jobs	하나 이상의 작업(Job)을 정의
runs-on	실행 환경 지정 (ubuntu-latest, windows-latest, macos-latest)
steps	한 작업(Job) 안에서 순차적으로 실행할 단계들
uses	외부 액션을 불러올 때 사용 (예: 코드 체크아웃, 캐시 등)
run	실제 명령어 실행 (셸 명령어, 스크립트 등)
env	환경변수 설정
if	조건문 실행 제어 (success(), failure(), always() 등)
with	액션에 전달할 옵션들 (예: 브랜치 이름, 경로)

---

🧪 실전 예제 ① – Python 테스트 자동화

name: Python Test

on:
  push:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: 코드 가져오기
        uses: actions/checkout@v3

      - name: Python 설치
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: 의존성 설치
        run: pip install -r requirements.txt

      - name: 테스트 실행
        run: pytest

반응형

---

🧪 실전 예제 ② – 문서 빌드 & 배포

name: Build and Deploy Docs

on:
  push:
    branches: [ main ]

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: pdoc 설치
        run: pip install pdoc

      - name: 문서 생성
        run: pdoc src/ --html --output-dir docs

      - name: GitHub Pages 배포
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

---

✅ 조건 제어 명령어 (if)

조건	설명
if: success()	이전 단계가 성공했을 때 실행
if: failure()	이전 단계가 실패했을 때 실행
if: always()	성공/실패 관계없이 항상 실행
if: github.ref == 'refs/heads/main'	특정 브랜치일 때만 실행

---

📌 환경 변수 설정 (env)

env:
  NODE_ENV: production

 

사용 예시:

run: echo "환경은 $NODE_ENV 입니다"

---

🧠 외부 액션 불러오기 (uses)

- uses: actions/checkout@v3

 

대표적으로 많이 쓰는 액션들:

액션 이름	설명
actions/checkout	코드 체크아웃
actions/setup-python	Python 버전 설정
actions/cache	캐시 활용
peaceiris/actions-gh-pages	GitHub Pages 배포

GitHub Marketplace에서 더 많은 액션 확인 가능: https://github.com/marketplace/actions

---

📦 변수 활용 (github, secrets)

• ${{ github.ref }} → 현재 브랜치
• ${{ github.repository }} → 현재 저장소
• ${{ secrets.GITHUB_TOKEN }} → GitHub가 자동으로 생성하는 인증 토큰
• ${{ secrets.ENV_SECRET }} → 사용자가 설정한 비밀값

---

🔁 디버깅 팁

run: echo "🔍 현재 브랜치: ${{ github.ref }}"

run: env

환경변수와 실행 로그는 Actions 탭 > 로그에서 확인 가능

---

🏁 마무리 정리

구성 요소	핵심 역할
on:	언제 실행할지 (트리거)
jobs:	어떤 작업을 할지 (Job 묶음)
steps:	작업 안에서 실행할 단계
uses / run	외부 액션 호출 or 직접 명령 실행
if, env, secrets	조건, 환경, 보안 설정 제어