GitHub Actions 사용법 기초 — 워크플로·잡·스텝 개념 한 번에 정리

한 줄 요약

GitHub Actions는 저장소에서 일어나는 일을 계기로 빌드, 테스트, 배포를 자동 실행하는 GitHub의 CI/CD 플랫폼이에요.

GitHub Actions

---

1. 핵심 개념

1.1 GitHub Actions란

공식 문서는 GitHub Actions를 빌드, 테스트, 배포 파이프라인을 자동화하는 CI/CD 플랫폼으로 설명해요. 풀 리퀘스트마다 빌드·테스트를 돌리거나, 병합된 코드를 운영 환경에 배포할 수 있어요.

CI/CD 개념 자체는 CI/CD란 무엇인가? 글에서 다뤘어요. 이 글은 GitHub Actions의 구성 요소와 작성법에 집중해요.

 

1.2 구성 요소

구성 요소 설명

워크플로(workflow)	자동화 작업 전체예요. YAML 파일로 정의해요
이벤트(event)	워크플로를 시작시키는 사건이에요 (push, 풀 리퀘스트 등)
잡(job)	같은 러너에서 실행되는 스텝 묶음이에요
스텝(step)	잡 안의 개별 작업이에요. 명령 실행 또는 액션 사용이에요
액션(action)	재사용 가능한 작업 단위예요 (코드 내려받기 등)
러너(runner)	워크플로를 실제로 실행하는 서버예요

풀 리퀘스트(Pull Request): 내가 수정한 코드를 합쳐 달라고 요청하는 GitHub 기능이에요.

 

1.3 왜 중요한가

• 코드 저장소와 자동화 설정이 한곳에 있어요.
• 사람이 매번 빌드·테스트를 실행하지 않아도 돼요.
• 설정이 파일로 남아 변경 이력을 추적할 수 있어요.

---

2. 쉽게 이해하기

GitHub Actions를 공장 자동화 라인에 비유해 볼게요.

• 이벤트는 라인을 켜는 스위치예요.
• 워크플로는 작업 지시서예요.
• 잡은 생산 라인 하나예요. 라인끼리는 동시에 돌 수 있어요.
• 스텝은 라인 안의 공정 순서예요.
• 액션은 규격화된 부품이에요. 가져다 끼우면 돼요.
• 러너는 실제로 일하는 기계예요.

---

3. 워크플로 파일 만들기

3.1 파일 위치

워크플로 파일은 저장소의 .github/workflows 폴더에 둬요. 한 저장소에 여러 워크플로를 만들 수 있어요.

my-project/
└── .github/
    └── workflows/
        └── ci.yml

 

3.2 기본 예시

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 코드 가져오기
        uses: actions/checkout@v6

      - name: 파일 목록 확인
        run: ls -la

      - name: 메시지 출력
        run: echo "Hello, GitHub Actions"

 

3.3 줄별 설명

코드 의미

name	워크플로 이름이에요. Actions 탭에 표시돼요
on	실행 조건이에요
push / pull_request	main 브랜치에 push 또는 풀 리퀘스트가 생기면 실행해요
workflow_dispatch	Actions 탭에서 수동 실행 버튼을 쓸 수 있게 해요
jobs.build	build라는 이름의 잡이에요
runs-on	러너 종류예요. 여기서는 GitHub이 제공하는 Ubuntu예요
uses	액션을 사용해요
run	셸 명령을 실행해요

 

actions/checkout은 저장소 코드를 러너로 내려받는 액션이에요. 대부분의 워크플로에서 첫 스텝으로 써요.

---

4. 잡 순서 정하기

공식 문서에 따르면 잡은 기본적으로 서로 의존하지 않고 병렬로 실행돼요. 순서가 필요하면 needs를 써요.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "테스트"

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: echo "배포"

 

deploy는 test가 끝난 뒤에 실행돼요.

---

5. 비밀 정보 다루기

 

5.1 Secrets

비밀번호, 토큰은 코드에 적지 않고 Secrets에 저장해요.

1. 저장소 Settings 메뉴로 이동해요.
2. Secrets and variables → Actions를 선택해요.
3. New repository secret으로 값을 등록해요.

워크플로에서는 이렇게 사용해요.

- name: 비밀 값 사용
  run: ./deploy.sh
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}

 

5.2 GITHUB_TOKEN

GITHUB_TOKEN은 워크플로 실행 시 자동으로 만들어지는 인증 토큰이에요. 별도 등록 없이 ${{ secrets.GITHUB_TOKEN }}으로 사용해요. 권한은 워크플로의 permissions 항목으로 조정해요.

---

6. 핵심 정리

• GitHub Actions는 GitHub에 내장된 CI/CD 플랫폼이에요.
• 워크플로 > 잡 > 스텝 순서로 구성되고, 이벤트가 실행을 시작해요.
• 워크플로 파일은 .github/workflows 폴더에 YAML로 작성해요.
• 잡은 기본 병렬 실행이고, 순서가 필요하면 needs를 써요.
• 비밀 정보는 Secrets에 저장하고 ${{ secrets.이름 }}으로 사용해요.

---

7. 추가 정보

주의사항

• 액션 버전 고정: 공식 문서는 외부 액션을 커밋 SHA로 고정하는 방식을 권장해요. 태그나 브랜치로 참조하면 예고 없이 내용이 바뀔 수 있어요.
• 요금: 사용 요금과 무료 제공량은 저장소 공개 여부와 요금제에 따라 달라요. 공식 문서의 Billing 페이지에서 확인하세요.
• 러너 선택: GitHub 제공 러너 외에 직접 운영하는 self-hosted runner도 쓸 수 있어요.
• 언어별 빌드 예시(Java with Gradle, Maven 등)는 공식 튜토리얼에 따로 정리되어 있어요.

관련 글

• CI/CD란 무엇인가? 비전공자도 이해하는 CI/CD 개념 정리