GitHub Actions는 GitHub 저장소에서 직접 빌드·테스트·배포 작업을 자동화(CI/CD) 할 수 있는 워크플로우 도구다.
코드가 push되면, 정해둔 스크립트를 실행하고, 안정적인 배포 프로세스를 만들 수 있다.
이 문서는 GitHub Actions의 기본 구조, 사용 방식, 권한, 동작 흐름을 이해하기 쉽게 정리한다.
GitHub Actions란 무엇인가?
GitHub Actions는 다음 작업을 자동화해주는 GitHub 내장 기능이다.
- 코드 테스트 자동 실행
- 빌드 자동화
- 정적 사이트 자동 배포(GitHub Pages)
- Docker 이미지 빌드/배포
- 백엔드 서버 자동 배포(CI/CD)
- 스케줄러 작업(cron)
- PR 품질 체크
즉, GitHub Events(push, pull request 등) → 자동 실행되는 서버리스 환경 → 코드 실행 이런 구조다.
GitHub Actions 사용 목적
- 빌드/테스트 배포를 누락하지 않게 자동화
- 팀원과 동일한 환경에서 실행 → 환경 편차 제거
- GitHub 에코시스템과 자연스럽게 연결
- 무료로 시작 가능
CI = Continuous Integration
CD = Continuous Delivery/Deployment
→ Actions는 이 둘을 완전히 자동화할 수 있다.
GitHub Actions의 구성 요소
워크플로우(workflow)는 다음 구성요소들로 이루어진다.
Workflow
.github/workflows/*.yml 파일 하나 자체
→ 실행 단위
Event
push, pull_request, schedule 등 워크플로우를 실행하는 “트리거”
Jobs
여러 작업 단위. 서로 병렬 또는 순차 실행 가능
Steps
각 job 안에서 실행되는 명령 단계
Actions
GitHub 또는 외부가 만든 “특정 동작을 수행하는 재사용 스크립트”
대표 예:
actions/checkout@v4 → 저장소 코드를 가져오는 액션
actions/setup-node@v4 → Node.js 설치 액션
GitHub Actions 작성 위치와 구조
프로젝트 구조 내 반드시 다음처럼 생성된다.
.github/
└─ workflows/
└─ workflow-name.ymlYAML 형식으로 작업을 정의하며, 예시는 다음과 같다.
name: Example Workflow
on:
push:
branches: ["main"]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Run a shell command
run: echo "Hello GitHub Actions"GitHub Actions에서 사용되는 권한(Permissions)
GitHub Actions는 보안 정책을 따르기 때문에,
배포나 파일 액세스를 하려면 반드시 권한을 선언해야 한다.
대표적인 권한:
| 권한 | 설명 |
|---|---|
contents: read/write | 저장소 파일 접근/수정 |
pages: write | GitHub Pages 배포 권한 |
id-token: write | 인증 토큰 생성(배포 시 필요) |
예시:
permissions:
contents: read
pages: write
id-token: write※ GitHub Pages 배포는 pages + id-token 권한이 필수이다.
GitHub Actions 동작 흐름(전체 구조)
[코드 작성]
↓
git push
↓
GitHub가 이벤트(push)를 감지
↓
해당 workflow 실행
↓
checkout → 의존성 설치 → 테스트 → 빌드 → 배포
↓
결과가 Actions 탭에 표시됨GitHub Actions의 장점
- 모든 구성원이 동일한 빌드 파이프라인을 공유
- 서버 비용 없이 GitHub에서 모든 작업 처리
- 정적 사이트 배포 자동화 가능
- Docker, AWS, Firebase, Cloudflare 등 어디든 연동 가능
- 반복 작업을 자동화하여 배포 실수 감소
GitHub Pages와 Actions의 차이 (표 정리)
| 항목 | Deploy from Branch | GitHub Actions |
|----------------|--------------------------------|--------------------------------|
| 설정 위치 | Settings > Pages | .github/workflows/ |
| 자동 빌드 여부 | ❌ 수동 빌드 후 커밋 필요 | ✅ push 시 자동 빌드·배포 |
| 정적 파일 경로 | 직접 지정 (/docs, /) | 빌드 결과(dist) 자동 처리 |
| 유연성 | 낮음 | 높음 |
| 권장 대상 | HTML/CSS 단순 정적 사이트 | React / Vue / Vite 등 빌드 필요 프로젝트 |GitHub Actions로 자동 배포하는 가장 흔한 패턴
예:
- React / Vite 프로젝트 빌드 → dist 업로드
- Node.js로 API 자동 테스트
- Docker 이미지 빌드 후 서버에 배포
- cron 스케줄러로 자동 데이터 백업
- PR 생성 시 lint 자동 검사
GitHub Actions는 프론트엔드·백엔드 모두 활용 가능한 전천후 자동화 도구다.
마무리
GitHub Actions는 GitHub에 코드를 push하는 흐름에 자연스럽게 연동되어
CI/CD를 완전히 자동화할 수 있는 강력한 도구이다.
특히 Vite·React 같은 프론트엔드 빌드 환경과 궁합이 매우 좋고,
GitHub Pages와 결합하면 비용 없이도 완전 자동 배포 시스템을 만들 수 있다.
