GitHub Actions 강좌 #1 워크플로의 구조: 이벤트, 잡, 러너, 그리고 첫 실행

2026년 9월 20일 일요일

5 분 소요

코드를 푸시할 때마다 로컬에서 테스트를 돌리고, 리뷰어는 “테스트 돌려 보셨나요"를 묻고, 배포 날에는 누군가 빌드 명령을 순서대로 칩니다. 이 반복을 사람이 하는 한 언젠가 빠뜨리고, 빠뜨린 날이 하필 사고 나는 날입니다. 저장소에 이벤트(푸시, PR 생성 등)가 일어나면 지정한 작업을 자동으로 실행해 주는 도구가 GitHub Actions이고, GitHub에 저장소가 있다면 추가 설치 없이 바로 쓸 수 있어 CI/CD의 사실상 기본값이 되었습니다. 이 시리즈는 첫 워크플로부터 조직 차원의 재사용, 보안, 운영 패턴까지 열 편으로 다룹니다. 이번 편의 목표는 구조를 이루는 다섯 개념을 잡고 첫 워크플로를 실행해 보는 것입니다.

다섯 개념: 워크플로, 이벤트, 잡, 스텝, 러너 #

GitHub Actions의 모든 것은 다섯 단어로 설명됩니다.

실행 흐름

이벤트(push, PR, ...)가 일어나면
  → 워크플로(.github/workflows/*.yml)가 깨어나고
    → 워크플로 안의 잡(job)들이 각자의 러너(가상 머신)에서 실행되며
      → 잡은 스텝(step)을 위에서 아래로 순서대로 수행합니다

워크플로(workflow): 자동화 한 벌의 정의입니다. 저장소의 .github/workflows/ 디렉터리에 YAML 파일로 두며, 이 경로는 규칙이라 바꿀 수 없습니다.
이벤트(event): 워크플로를 깨우는 계기입니다. 푸시, PR, 예약 시각, 수동 버튼 등 수십 종이 있습니다.
잡(job): 실행 단위입니다. 한 워크플로에 여러 잡을 둘 수 있고, 기본적으로 서로 병렬로 돕니다.
스텝(step): 잡 안의 한 줄 한 줄입니다. 셸 명령(run)이거나, 남이 만들어 둔 액션(uses)입니다.
러너(runner): 잡이 실행되는 머신입니다. GitHub가 제공하는 가상 머신을 쓰는 것이 기본입니다.

첫 워크플로: 푸시마다 테스트 실행 #

파이썬 프로젝트에 테스트 자동화를 붙여 보겠습니다. 저장소에 파일 하나를 추가하는 것이 전부입니다.

.github/workflows/test.yml

# .github/workflows/test.yml
name: test

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install -r requirements.txt
      - run: pytest

위에서 배운 다섯 개념이 전부 들어 있습니다. on이 이벤트(main 푸시와 모든 PR), jobs.test가 잡 하나, runs-on이 러너 지정, steps의 넉 줄이 스텝입니다. 처음 보는 것은 uses로 불러오는 액션입니다. actions/checkout은 러너에 저장소 코드를 내려받는 액션이고, actions/setup-python은 파이썬을 설치하는 액션입니다. 러너는 매번 깨끗한 머신으로 시작하므로 “코드 받기"부터가 우리 일인데, 이런 반복 작업을 포장해 둔 부품이 액션이며 마켓플레이스에 수만 개가 공개되어 있습니다. @v4 같은 접미사는 액션의 버전 지정으로, 자세한 문법과 안전한 고정 방법은 각각 다음 편과 #9에서 다루겠습니다.

이 파일을 커밋해 푸시하면 그 푸시부터 워크플로가 동작합니다. 별도의 등록 절차가 없다는 것, 즉 워크플로 파일의 존재 자체가 등록이라는 점이 GitHub Actions의 문턱을 낮추는 특징입니다.

실행 결과 읽기: Actions 탭 #

푸시 직후 저장소의 Actions 탭에 실행이 나타납니다. 읽는 순서는 실행 목록 → 잡 → 스텝입니다. 실패하면 실패한 스텝이 자동으로 펼쳐져 로그를 보여 주고, PR 화면에도 체크 결과가 표시되어 리뷰어가 “테스트 돌려 보셨나요"를 물을 필요가 없어집니다. README에 상태 배지를 붙이면 저장소 첫 화면에서 최근 실행 상태가 보입니다.

README.md

![test](https://github.com/<owner>/<repo>/actions/workflows/test.yml/badge.svg)

이벤트는 push만이 아닙니다 #

on에 올 수 있는 대표 이벤트를 미리 봐 두면 시리즈 전체의 지도가 됩니다.

이벤트	깨어나는 시점	대표 용도
`push`	브랜치에 푸시	테스트, 빌드
`pull_request`	PR 생성·갱신	리뷰 전 검증
`schedule`	cron 예약 시각	야간 점검, 정기 작업
`workflow_dispatch`	사람이 버튼 클릭	수동 배포, 일회성 작업
`release`	릴리스 발행	패키지 배포

schedule과 workflow_dispatch는 저장소 이벤트 없이도 돌릴 수 있다는 뜻이라, GitHub Actions를 CI를 넘어 범용 자동화 도구로 만들어 주는 조각입니다. 이벤트에 조건(특정 경로, 특정 브랜치)을 붙여 정밀하게 깨우는 방법은 다음 편의 문법에서 다루겠습니다.

러너와 요금의 상식 #

runs-on: ubuntu-latest는 GitHub가 호스팅하는 우분투 가상 머신을 의미하며, macOS와 Windows 러너도 있습니다. 요금은 계정 종류에 따라 다릅니다. 퍼블릭 저장소는 GitHub 호스티드 러너가 무료이고, 프라이빗 저장소는 월 무료 분량(요금제별 상이) 초과분부터 분 단위 과금이며 macOS 러너는 리눅스보다 배수가 높습니다. 정확한 한도와 단가는 변동이 있으니 요금 문서 확인을 전제로 하되, “프라이빗 저장소의 macOS 잡은 비싸다” 정도의 감각은 지금 가져가면 됩니다. 비용을 줄이는 캐시 전략과 셀프호스티드 러너는 각각 #4와 #8의 주제입니다.

정리 #

이번 글에서 다룬 내용입니다.

GitHub Actions는 이벤트 → 워크플로 → 잡 → 스텝의 구조이고, 잡은 러너라는 깨끗한 가상 머신에서 실행됩니다
워크플로는 .github/workflows/의 YAML 파일이며, 파일의 존재가 곧 등록입니다
러너는 매번 초기 상태라 checkout부터 시작하고, 반복 작업은 마켓플레이스의 액션으로 처리합니다
이벤트는 push, pull_request 외에 schedule과 workflow_dispatch가 있어 범용 자동화까지 커버합니다
퍼블릭 저장소는 러너가 무료, 프라이빗은 무료 분량 초과분이 분 단위 과금입니다

다음 글(#2 문법 핵심)에서는 오늘 훑고 지나간 YAML의 문법을 제대로 잡습니다. 스텝 사이에 값을 주고받는 컨텍스트와 표현식, if 조건으로 스텝을 골라 실행하는 방법입니다.