GitHub Actions로 자동화 시작하기

반복 작업은 자동화할 수 있다

개발을 하다 보면 같은 일을 계속 반복하게 됩니다.

예를 들어 다음과 같은 작업입니다.

• 코드를 올릴 때마다 테스트 실행하기

• 문법 오류가 없는지 검사하기

• 프로젝트가 정상적으로 빌드되는지 확인하기

• 배포 파일 만들기

• Pull Request가 열릴 때 자동으로 확인 작업 실행하기

처음에는 사람이 직접 해도 괜찮습니다. 하지만 프로젝트가 커지고 협업자가 늘어나면 매번 직접 확인하기 어렵습니다. 깜빡할 수도 있고, 사람마다 실행하는 방식이 다를 수도 있습니다.

GitHub Actions는 이런 반복 작업을 GitHub 안에서 자동으로 실행해 주는 기능입니다.

예를 들어 main 브랜치에 코드를 push하면 GitHub가 자동으로 테스트를 실행하게 만들 수 있습니다. Pull Request가 열릴 때마다 코드 검사를 실행하게 할 수도 있습니다.

핵심은 단순합니다.

어떤 일이 발생하면, 정해 둔 작업을 자동으로 실행한다.

여기서 '어떤 일'은 push, Pull Request 생성, Issue 생성 같은 GitHub 이벤트입니다. 그리고 '정해 둔 작업'은 우리가 YAML 파일에 작성한 자동화 명령입니다.

GitHub Actions의 기본 구조

GitHub Actions를 이해하려면 몇 가지 단어를 먼저 알아야 합니다.

Workflow

Workflow는 자동화 작업 전체를 뜻합니다.

예를 들어 다음과 같은 자동화 하나하나가 워크플로우입니다.

• push할 때 파일 목록 확인하기

• Pull Request가 열릴 때 테스트 실행하기

• 태그를 만들면 릴리스 생성하기

• 매일 새벽에 정기 작업 실행하기

워크플로우는 저장소 안의 .github/workflows 폴더에 YAML 파일로 저장합니다.

예를 들어 이런 파일을 만들 수 있습니다.

.github/workflows/first-action.yml

GitHub는 이 폴더 안에 있는 YAML 파일을 자동화 설정 파일로 인식합니다.

Event

Event는 워크플로우를 실행시키는 계기입니다.

대표적인 이벤트는 다음과 같습니다.

• push: 코드가 원격 저장소에 올라왔을 때

• pull_request: Pull Request가 열리거나 수정되었을 때

• issues: Issue가 생성되거나 수정되었을 때

• workflow_dispatch: 사용자가 직접 실행 버튼을 눌렀을 때

예를 들어 push 이벤트를 설정하면, 누군가 저장소에 push할 때마다 워크플로우가 실행됩니다.

Job

Job은 워크플로우 안에서 실행되는 작업 묶음입니다.

하나의 워크플로우 안에는 하나 이상의 job이 들어갈 수 있습니다.

예를 들어 다음처럼 나눌 수 있습니다.

• test: 테스트 실행

• build: 빌드 실행

• deploy: 배포 실행

처음에는 job을 하나만 사용해도 충분합니다.

Step

Step은 job 안에서 실제로 실행되는 한 단계입니다.

예를 들어 하나의 job 안에 이런 step들이 있을 수 있습니다.

1. 저장소 코드 가져오기

2. 필요한 프로그램 설치하기

3. 테스트 실행하기

4. 결과 출력하기

step은 위에서 아래 순서대로 실행됩니다. 중간에 실패하면 그 뒤 step은 보통 실행되지 않습니다.

Runner

Runner는 작업을 실제로 실행하는 컴퓨터입니다.

GitHub Actions는 우리가 설정한 자동화 작업을 GitHub가 준비한 가상 컴퓨터에서 실행합니다. 이 실행 환경을 runner라고 부릅니다.

예를 들어 다음 설정은 Ubuntu 리눅스 환경에서 작업을 실행하겠다는 뜻입니다.

runs-on: ubuntu-latest

초보자는 우선 ubuntu-latest를 가장 많이 사용한다고 기억하면 됩니다.

YAML 파일의 기본 모양

GitHub Actions 설정은 YAML 문법으로 작성합니다. YAML은 들여쓰기로 구조를 표현하는 파일 형식입니다.

가장 중요한 점은 들여쓰기입니다. 같은 수준의 항목은 같은 칸에 맞춰야 합니다.

아래는 아주 기본적인 워크플로우 예시입니다.

name: First GitHub Actions

on:
  push:
    branches: [main]

jobs:
  first-job:
    runs-on: ubuntu-latest
    steps:
      - name: 인사 출력하기
        run: echo 'GitHub Actions가 실행되었습니다.'

하나씩 보면 어렵지 않습니다.

• name: 워크플로우 이름입니다. GitHub Actions 화면에 표시됩니다.

• on: 어떤 이벤트에서 실행할지 정합니다.

• push: push가 발생했을 때 실행합니다.

• branches: [main]: main 브랜치에 push될 때만 실행합니다.

• jobs: 실행할 작업 묶음입니다.

• first-job: job의 이름입니다. 원하는 이름으로 정할 수 있습니다.

• runs-on: 어떤 runner에서 실행할지 정합니다.

• steps: 실제 실행 단계 목록입니다.

• run: 터미널 명령어를 실행합니다.

여기서 run은 우리가 터미널에 직접 입력할 수 있는 명령을 실행할 때 사용합니다.

uses와 run의 차이

step을 작성할 때 자주 보게 되는 키워드가 uses와 run입니다.

둘은 역할이 다릅니다.

run

run은 명령어를 직접 실행합니다.

예를 들어 다음 step은 화면에 문장을 출력합니다.

- name: 메시지 출력
  run: echo '자동화 실행 중'

다음 step은 현재 폴더의 파일 목록을 보여 줍니다.

- name: 파일 목록 보기
  run: ls -la

즉, run은 터미널 명령을 직접 쓰는 방식입니다.

uses

uses는 누군가 미리 만들어 둔 Action을 가져와 사용하는 방식입니다.

가장 자주 쓰는 예시는 다음입니다.

- name: 저장소 코드 가져오기
  uses: actions/checkout@v4

GitHub Actions의 runner는 처음 실행될 때 내 저장소 코드를 자동으로 가지고 있지 않습니다. 그래서 저장소 파일을 사용하려면 먼저 코드를 가져와야 합니다.

이때 actions/checkout@v4를 사용합니다.

정리하면 다음과 같습니다.

• run: 내가 명령어를 직접 실행한다.

• uses: 만들어진 Action을 가져와 실행한다.

처음에는 actions/checkout@v4와 run만 알아도 충분합니다.

첫 번째 자동화 만들기

이제 실제로 push가 발생할 때 자동으로 실행되는 워크플로우를 만들어 보겠습니다.

목표는 단순합니다.

1. main 브랜치에 push한다.

2. GitHub Actions가 실행된다.

3. 메시지를 출력한다.

4. 저장소 파일 목록을 확인한다.

먼저 프로젝트 루트에 다음 폴더를 만듭니다.

.github/workflows

그 안에 first-action.yml 파일을 만듭니다.

.github/workflows/first-action.yml

그리고 아래 내용을 입력합니다.

name: First GitHub Actions

on:
  push:
    branches: [main]

jobs:
  check-files:
    runs-on: ubuntu-latest

    steps:
      - name: 저장소 코드 가져오기
        uses: actions/checkout@v4

      - name: 실행 메시지 출력하기
        run: echo 'GitHub Actions가 실행되었습니다.'

      - name: 현재 위치 확인하기
        run: pwd

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

이 워크플로우는 main 브랜치에 push가 발생하면 실행됩니다.

실행 순서는 다음과 같습니다.

1. Ubuntu runner를 준비합니다.

2. actions/checkout@v4로 저장소 코드를 가져옵니다.

3. echo 명령으로 메시지를 출력합니다.

4. pwd 명령으로 현재 위치를 확인합니다.

5. ls -la 명령으로 파일 목록을 출력합니다.

아직 테스트나 배포는 하지 않습니다. 하지만 이 예제만으로도 GitHub Actions의 기본 구조를 충분히 확인할 수 있습니다.

변경 사항 커밋하고 push하기

워크플로우 파일을 만들었다면 Git으로 저장하고 GitHub에 올립니다.

git status
git add .github/workflows/first-action.yml
git commit -m 'Add first GitHub Actions workflow'
git push origin main

여기서 중요한 점은 GitHub Actions 설정 파일도 일반 코드 파일과 같다는 것입니다.

즉, 파일을 만들기만 해서는 GitHub에서 실행되지 않습니다. 반드시 커밋하고 원격 저장소에 push해야 합니다.

push가 완료되면 GitHub 저장소 페이지로 이동합니다.

Actions 탭에서 실행 결과 확인하기

GitHub 저장소 상단 메뉴에서 Actions 탭을 클릭합니다.

그러면 방금 만든 워크플로우 이름인 First GitHub Actions가 보입니다. push 직후라면 실행 중이거나 이미 완료되었을 수 있습니다.

실행 결과는 보통 다음 상태 중 하나로 표시됩니다.

• 초록색 체크: 성공

• 노란색 아이콘: 실행 중

• 빨간색 X: 실패

실행 항목을 클릭하면 job 목록이 나옵니다. 이 예제에서는 check-files job이 보입니다.

job을 클릭하면 step별 로그를 확인할 수 있습니다.

예를 들어 다음 step들의 실행 결과를 볼 수 있습니다.

• 저장소 코드 가져오기

• 실행 메시지 출력하기

• 현재 위치 확인하기

• 파일 목록 확인하기

각 step을 펼치면 실제 터미널 출력이 보입니다. echo로 출력한 문장, pwd의 결과, ls -la의 파일 목록을 확인할 수 있습니다.

이 로그는 매우 중요합니다. 자동화가 실패했을 때 어디에서 문제가 생겼는지 알려 주기 때문입니다.

실패 지점 확인하기

GitHub Actions를 쓰다 보면 실패는 자연스럽게 발생합니다.

오타가 있을 수도 있고, 명령어가 잘못되었을 수도 있고, 필요한 파일이 없을 수도 있습니다.

예를 들어 다음과 같이 존재하지 않는 명령어를 실행하면 실패합니다.

- name: 일부러 실패시키기
  run: wrong-command

이 경우 Actions 로그에서 해당 step이 빨간색으로 표시됩니다. 펼쳐 보면 어떤 명령어가 실패했는지, 어떤 오류 메시지가 나왔는지 확인할 수 있습니다.

문제가 생겼을 때는 다음 순서로 보면 됩니다.

1. 어떤 workflow가 실패했는지 확인합니다.

2. 어떤 job이 실패했는지 확인합니다.

3. 어떤 step에서 멈췄는지 확인합니다.

4. 로그의 오류 메시지를 읽습니다.

5. YAML 파일이나 코드 파일을 수정합니다.

6. 다시 커밋하고 push합니다.

자동화의 장점은 실패를 빨리 발견할 수 있다는 점입니다. 사람이 직접 확인하지 않아도 GitHub가 문제를 알려 줍니다.

워크플로우 다시 실행하기

때로는 코드를 수정하지 않고 같은 워크플로우를 다시 실행하고 싶을 수 있습니다.

GitHub Actions 실행 상세 화면에는 재실행 버튼이 있습니다. 보통 Re-run jobs 또는 Re-run all jobs 같은 버튼으로 표시됩니다.

이 버튼을 누르면 같은 커밋 기준으로 워크플로우를 다시 실행할 수 있습니다.

다만 설정 파일 자체를 수정했다면 다시 커밋하고 push하는 편이 좋습니다. 그래야 수정된 설정으로 새 실행이 시작됩니다.

초보자가 자주 하는 실수

GitHub Actions를 처음 사용할 때는 다음 실수를 자주 합니다.

폴더 위치를 잘못 만든다

워크플로우 파일은 반드시 아래 폴더 안에 있어야 합니다.

.github/workflows

.github/workflow처럼 단수로 쓰거나, 다른 위치에 만들면 GitHub가 자동화 파일로 인식하지 못합니다.

YAML 들여쓰기가 틀린다

YAML은 들여쓰기가 중요합니다.

예를 들어 steps는 특정 job 안에 들어가야 합니다. 들여쓰기가 어긋나면 워크플로우가 실행되지 않거나, GitHub가 설정 파일을 읽지 못합니다.

문제가 생기면 먼저 들여쓰기를 확인하세요.

push 이벤트를 설정했지만 push하지 않는다

on: push로 설정했다면 push가 발생해야 실행됩니다.

파일을 로컬에서 만들기만 하고 push하지 않으면 GitHub Actions는 실행되지 않습니다.

checkout 없이 파일을 찾으려 한다

runner에서 저장소 파일을 사용하려면 보통 actions/checkout@v4가 필요합니다.

파일 목록을 확인하거나 테스트를 실행하려면 먼저 저장소 코드를 가져와야 합니다.

이번 장의 핵심 정리

GitHub Actions는 GitHub에서 반복 작업을 자동으로 실행하는 기능입니다.

기본 흐름은 다음과 같습니다.

1. 이벤트가 발생합니다. 예: push, pull_request, issue

2. .github/workflows 폴더의 YAML 파일을 GitHub가 읽습니다.

3. workflow가 실행됩니다.

4. workflow 안의 job이 실행됩니다.

5. job 안의 step이 순서대로 실행됩니다.

6. runner가 실제 명령을 수행합니다.

7. Actions 탭에서 결과와 로그를 확인합니다.

이번 장에서는 push가 발생했을 때 메시지를 출력하고 파일 목록을 확인하는 간단한 자동화를 만들었습니다.

작업 자체는 단순하지만 구조는 실무 자동화와 같습니다. 테스트를 실행하든, 빌드를 하든, 배포를 하든 기본 원리는 같습니다.

다음 장에서는 이 흐름을 Pull Request와 연결합니다. PR이 열릴 때마다 자동으로 테스트를 실행하면, main 브랜치에 문제가 들어가기 전에 미리 확인할 수 있습니다.