GitHub Actions는 이벤트 기반 빌드·테스트·배포 자동화 엔진이다.
구조를 정확히 이해하면 어떤 CI/CD 파이프라인도 논리적으로 설계할 수 있다.

이 글은 Actions를 구성하는 핵심 요소(Workflow, Job, Step, Action)의 본질과 구조적 역할을 실무 관점에서 정리한다.

---

1. GitHub Actions의 전체 구조

GitHub Actions는 아래 순서로 동작한다.

1. 이벤트 발생(push, PR 등)
2. 해당 이벤트를 감지한 Workflow 실행
3. 여러 개의 Job 이 병렬 또는 순차 실행
4. 각 Job 내부의 Step 이 실제 명령 실행
5. Step에서 Action 호출 가능

즉, 전체 자동화 설계는 "이벤트 → Workflow → Job → Step" 구조로 이해하면 충분하다.

---

2. Workflow: 자동화 정의의 최상위 단위

Workflow는 .github/workflows/*.yml 파일로 구성된다.
한 저장소에 여러 Workflow를 둘 수 있으며 각각 독립적으로 실행된다.

최소 실행 예제:

name: basic-workflow

on: push

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello Actions"

구성 요소:

• name: UI에서 보이는 Workflow 이름
• on: 트리거 이벤트 정의
• jobs: 실행할 Job 집합

실무에서는 Workflow를 크게 두 가지로 구분한다.

• CI(Test/Build) Workflow
• CD(Deploy) Workflow

특히 배포는 브랜치 필터 또는 태그 기반 트리거로 분리하는 것이 일반적이다.

---

3. Event Trigger: Workflow 실행의 조건

Event Trigger는 Workflow가 "언제" 실행될지를 결정한다.

대표 트리거:

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

추가 실무 트리거:

• tag push: 버전 배포 자동화
• schedule: cron 기반 실행
• workflow_dispatch: 수동 실행

이벤트는 GitHub Actions의 실행 시작점이므로 구조 설계의 가장 중요한 요소다.

---

4. Job: 독립적인 실행 단위

Job은 여러 Step의 묶음이며 기본적으로 병렬 실행된다.

jobs:
  test:
    runs-on: ubuntu-latest
  build:
    runs-on: ubuntu-latest

각 Job에는 아래 속성이 있다.

• runs-on: 실행 환경 OS
• steps: 실행 단계
• needs: 다른 Job 의존성(순차 실행)

순차 실행 예제:

jobs:
  test:
    runs-on: ubuntu-latest

  deploy:
    runs-on: ubuntu-latest
    needs: test

실무 기준 의존성 규칙:

• 테스트 실패 시 배포 Job 차단
• 병렬 실행해 전체 파이프라인 시간 최소화
• 배포 Job은 반드시 테스트를 선행조건으로 둔다

---

5. Step: Job 내부의 실제 실행 단위

Step은 Bash 명령 또는 Action 호출로 구성된다.

steps:
  - name: Print
    run: echo "Run Step"

여러 Step은 Job 내부에서 순서대로 실행된다.

Step 유형:

• run: 직접 명령 수행
• uses: 액션 호출
• with: 액션 설정

Step은 Side Effect가 없으며 Job 상태가 유지되지 않는다.
즉 모든 Step은 같은 환경에서 실행되지만 상태를 다음 Job에 넘기지 않는다.

---

6. Action: Step에서 재사용하는 기능 모듈

Action은 Workflow의 재사용 가능한 기능 단위다.
공식 또는 커스텀 액션을 사용할 수 있으며, 대부분 실무에서는 아래 두 가지를 필수로 사용한다.

① checkout

- uses: actions/checkout@v4

② Node 환경 설치

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

Action 구조를 이해해야 다음 단계에서 Composite Action 또는 Docker Action 개발이 가능해진다.

---

7. 병렬 실행(Parallel Jobs) 구조

GitHub Actions의 장점은 기본적으로 Job이 병렬로 실행된다는 점이다.

예:

jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    runs-on: ubuntu-latest
  build:
    runs-on: ubuntu-latest

효과:

• 전체 빌드 시간이 단축
• 테스트 분리로 파이프라인 안정성 증가
• 불필요한 대기 시간 제거

병렬 실행을 막고 싶을 때만 needs 로 순차 흐름을 만들어 준다.

---

8. 실무 핵심 요소 빠르게 정리(개념만 분리)

조건 실행(if)

Step 또는 Job 단위로 조건 지정 가능.

if: github.ref == 'refs/heads/main'

Secrets

민감 정보는 반드시 Secrets로 저장해야 하며 출력 금지.

Matrix

Node 16·18·20 같은 다중 환경 테스트에 사용.

strategy:
  matrix:
    node: [16, 18, 20]

Docker Job

컨테이너 기반 환경에서 Actions 실행 가능.

container:
  image: node:18

이 요소들은 CI/CD 확장에서 핵심적인 기능이다.

---

9. 최소 실무형 구동 예제: Test + Build + 병렬 실행

아래 예제는 복붙 즉시 실행 가능한 실무형 최소 CI 구성이다.

name: basic-ci

on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npm test --if-present

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npm run build --if-present

구조적으로 완결된 기본 CI 파이프라인이다.

---

10. 핵심 개념 정리

• Workflow: 자동화 전체를 정의하는 파일
• Event Trigger: Workflow 실행 조건
• Job: 독립 실행 단위(병렬·순차 실행)
• Step: Job 내부 실행 단계
• Action: Step에서 호출하는 모듈
• needs: Job 간 의존성
• Matrix: 다중 환경 테스트
• Docker Job: 컨테이너 기반 실행 환경

Actions 구조를 정확히 이해하면 CI/CD를 체계적으로 확장할 수 있다.

---

11. 실수하기 쉬운 포인트

• checkout 누락 → 소스가 없어 테스트·빌드 불가
• needs 순서 오류 → 배포 Job이 잘못 실행되거나 건너뛰어짐
• Secrets를 env에 그대로 노출 → 즉시 보안 사고
• PR 이벤트와 push 이벤트 구분 실패 → 의도치 않은 자동화 실행
• Step 간 상태 공유 가능하다고 오해 → Job 단위 격리 기반
• 병렬 실행을 고려하지 않은 구조 → 불필요한 전체 빌드 시간 증가

기본 구조를 확실히 이해해 두면 CI/CD 확장 시 불필요한 시행착오를 크게 줄일 수 있다.