Act란 무엇인가?

Act는 로컬에서 GitHub Actions Workflow를 실행할 수 있게 해주는 오픈소스 커맨드라인 도구다. 코드를 GitHub에 푸시하지 않고도 CI/CD 파이프라인을 테스트하고 디버깅할 수 있다.

GitHub Actions를 자주 작성하는 개발자에게 이는 효율성 신기원이다:

  • 빠른 반복: workflow 수정 후 즉시 로컬에서 실행, GitHub 대기열과 실행 시간을 기다릴 필요 없음
  • 리소스 절약: GitHub Actions 분(minute) 소모 없음(특히 프라이빗 저장소)
  • 오프라인 디버깅: 네트워크 연결 없이도 workflow 테스트 가능
  • 보안 테스트: 격리된 환경에서 workflow 보안 검증, 위험한 작업의 실수 실행 방지

왜 Act가 필요한가?

GitHub Actions는 강력한 CI/CD 플랫폼이지만, workflow 디버깅에는 한 가지 골칫거리가 있다:

.github/workflows/test.yml 수정 
→ git commit 
→ git push 
→ GitHub 대기열 대기(몇 분에서 몇 시간까지)
→ 로그 확인 후 오류 발견
→ 위 단계 반복

이 사이클은 매우 시간이 많이 든다. Act를 사용하면:

.github/workflows/test.yml 수정 
→ act -j test    # 로컬에서 즉시 실행
→ 출력 확인, 문제 수정
→ 다시 실행, 문제없음 확인 후 푸시

효율성이 최소 10배 향상된다.

Act vs 다른 솔루션

특성 Act GitHub 웹 UI Docker Compose 시뮬레이션
실행 속도 ⚡ 로컬 즉시 🐌 대기열 필요 ⚡ 로컬이지만 설정 복잡
실제성 ✅ 실제 GitHub Actions runner 이미지 사용 ✅ 완전 실제 ❌ 수동 시뮬레이션 필요
비용 💰 무료(로컬 실행) 💰 Actions 분 소모 💰 무료
사용 편의성 ✅ 단일 명령어 ✅ 그래픽 인터페이스 ❌ 설정 번거로움
오프라인 지원 ✅ 완전 오프라인 ❌ 네트워크 필요 ✅ 오프라인 가능

Act 설치

macOS(Homebrew)

BASH 
brew install act

Linux

Ubuntu/Debian:

BASH 
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Arch Linux:

BASH 
yay -S act
# 또는
paru -S act

Windows

Chocolatey:

POWERSHELL 
choco install act-cli

Scoop:

POWERSHELL 
scoop install act

설치 확인

BASH 
act --version
# 출력 예시: act version 0.2.x

빠르게 시작하기: 첫 번째 Workflow 실행

사전 조건

프로젝트 루트 디렉토리에 .github/workflows/ 디렉토리가 있고, 그 안에 최소 하나의 workflow 파일(.yml 또는 .yaml)이 있는지 확인한다.

사용 가능한 Workflow 나열

BASH 
cd /path/to/your/project
act -l

출력 예시:

Stage  Job ID  Job name  Workflow name  Workflow file  Events
0      test    Test      CI             ci.yml         push,pull_request
0      build   Build     CI             ci.yml         push,pull_request

특정 Job 실행

BASH 
# test라는 이름의 job 실행
act -j test

# 모든 job 실행
act

# 특정 이벤트로 트리거되는 workflow 실행(pull_request 등)
act pull_request

첫 실행 시 주의사항

처음 실행할 때 Act는 필요한 Docker 이미지를 다운로드한다(보통 catthehacker/ubuntu:act-latest). 이 과정은 몇 분 정도 걸릴 수 있다. 이후 실행에서는 캐시를 사용하여 더 빠르게 진행된다.

INFO[0000] Using docker host 'unix:///var/run/docker.sock'
INFO[0000] Pulling image 'catthehacker/ubuntu:act-latest'
...

고급 활용법

1. 다른 Runner 이미지 사용

Act는 기본적으로 Ubuntu 이미지를 사용하지만, -P 파라미터로 다른 플랫폼을 지정할 수 있다:

BASH 
# Ubuntu 22.04 사용
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04

# Ubuntu 20.04 사용
act -P ubuntu-latest=catthehacker/ubuntu:act-20.04

# 경량 이미지 사용(더 빠르지만 기능 제한적)
act -P ubuntu-latest=node:16-buster-slim

2. Secret과 환경 변수 전달

많은 workflow가 secret(API 키, Token 등)에 의존한다. .env 파일이나 커맨드라인으로 전달할 수 있다:

방법 1: .env 파일 사용

프로젝트 루트에 .env 파일 생성:

BASH 
MY_API_KEY=your_secret_key
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

그런 다음 실행:

BASH 
act --secret-file .env

방법 2: 커맨드라인 직접 전달

BASH 
act -s MY_API_KEY=your_secret_key -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. 여러 Job 병렬 실행

workflow에 독립적인 job이 여러 개 있다면 --parallel로 속도를 높일 수 있다:

BASH 
act --parallel

4. 드라이 런 모드(Dry Run)

실제 실행 없이 실행될 단계만 출력:

BASH 
act -n

5. 사용자 정의 작업 디렉토리

workflow가 특정 디렉토리 구조에 의존한다면 바인드 마운트를 사용할 수 있다:

BASH 
act --bind

현재 디렉토리를 컨테이너 내부에 마운트하여 파일 수정이 실시간으로 반영되도록 한다.

실전 사례

사례 1: Node.js 프로젝트 CI 디버깅

Node.js 프로젝트가 있고, workflow가 다음과 같다고 가정하자:

YAML 
# .github/workflows/nodejs.yml
name: Node.js CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

로컬에서 실행:

BASH 
act -j test

테스트가 실패하면 Act가 전체 로그 출력을 표시하므로 문제 위치 파악이 쉽다.

사례 2: 다중 버전 Python 매트릭스 테스트

YAML 
# .github/workflows/python.yml
name: Python Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11', '3.12']

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run tests
        run: pytest

모든 Python 버전 테스트 실행:

BASH 
act -j test

Act가 자동으로 매트릭스의 모든 조합을 순회하며 차례로 실행한다.

사례 3: Docker 빌드 디버깅

YAML 
# .github/workflows/docker.yml
name: Build Docker Image

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Run tests in container
        run: docker run myapp:${{ github.sha }} npm test

로컬에서 실행하기 전에 Docker daemon이 실행 중인지 확인:

BASH 
# Docker 사용 가능 여부 확인
docker info

# workflow 실행
act -j build

일반적인 문제 해결

문제 1: 권한 오류

현상: permission denied while trying to connect to the Docker daemon socket

해결:

BASH 
# 현재 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER
# 재로그인하거나 newgrp docker 실행

또는 sudo로 Act 실행(권장하지 않음):

BASH 
sudo act

문제 2: 메모리 부족

현상: 대형 workflow 실행 시 OOM(Out of Memory)

해결: 동시 job 수 제한

BASH 
act --max-parallel 1

문제 3: Action을 찾을 수 없음

현상: unable to find action 'actions/checkout@v4'

해결: Act는 GitHub에서 action을 다운로드해야 하므로 네트워크 연결이 정상인지 확인한다. 프라이빗 action의 경우 GITHUB_TOKEN을 설정해야 한다.

문제 4: 환경 변수가 적용되지 않음

현상: workflow에서 참조하는 환경 변수가 비어 있음

해결: --secret-file 또는 -s로 변수를 올바르게 전달했는지, 그리고 workflow에서 ${{ env.VAR_NAME }} 또는 ${{ secrets.VAR_NAME }}로 참조하는지 확인한다.

모범 사례

  1. 푸시 전 항상 로컬 테스트: workflow 수정 후 Act로 먼저 검증하는 습관 들이기
  2. .env 파일로 secret 관리: 민감 정보 하드코딩 금지, .env를 .gitignore에 추가
  3. Act 정기 업데이트: brew upgrade act 또는 최신 버전 재다운로드 설치
  4. VS Code와 함께 사용: GitHub Actions 확장 설치, 에디터에서 workflow 직접 미리보기
  5. CI에서 Act를 선택적 단계로 유지: PR 템플릿에 기여자에게 로컬 테스트 안내 포함

요약

Act는 GitHub Actions 개발자의 필수 도구로, 원래 몇 분에서 몇 시간이 걸리던 디버깅 사이클을 몇 초로 단축시킨다. 간단한 단위 테스트 workflow부터 복잡한 다단계 배포 파이프라인까지, Act를 사용하면 로컬에서 빠르게 검증할 수 있다.

핵심 장점 리뷰: - ⚡ 빠른 반복: 로컬 즉시 실행, GitHub 대기열 불필요 - 💰 비용 절감: GitHub Actions 분 소모 없음 - 🔒 보안 격리: 컨테이너에서 실행, 호스트 환경 영향 없음 - 🛠️ 실제 환경: GitHub와 동일한 runner 이미지 사용, 결과 신뢰성 확보

GitHub Actions workflow를 자주 작성하거나 유지보수한다면 Act를 도구 상자에 추가하기를 강력히 권장한다.

관련 링크: - Act GitHub 저장소 - Act 공식 문서 - GitHub Actions 문서