초보자를 위한 GitHub: GitHub Actions 시작하기

GitHub Actions는 GitHub에 내장된 CI/CD 및 자동화 플랫폼으로, YAML 워크플로를 통해 반복 작업과 배포 과정을 자동화한다. 저장소 이벤트가 발생하면 가상 실행 환경에서 작업을 수행하며, 글에서는 새 이슈에 triage 라벨을 자동으로 붙이는 첫 워크플로를 만드는 과정을 설명한다. 핵심 구성 요소는 이벤트(on), 실행 환경(runs-on), 작업(jobs), 단계(steps), 권한(permissions)이다.

GitHub Actions의 역할

• GitHub Actions는 지속적 통합·지속적 배포(CI/CD)와 자동화를 위한 플랫폼이다.
• YAML 파일로 다음과 같은 작업을 자동화할 수 있다.
  • 취약점 검사
  • 테스트 실행
  • 릴리스 생성
  • 팀에 업데이트 알림
  • 배포 프로세스
• 워크플로는 저장소에 저장되며, 코드 푸시·풀 리퀘스트·이슈 생성·예약된 시간 등의 이벤트로 실행된다.
• 이벤트가 발생하면 GitHub가 가상 환경을 준비하고 정의된 작업을 자동으로 실행한다.

워크플로를 구성하는 요소

• 이벤트(Event)
  • 워크플로를 시작시키는 저장소 활동이다.
  • 예: 코드 푸시, 풀 리퀘스트 생성, 이슈 생성, 브랜치 병합
• 실행기(Hosted runner)
  • 워크플로의 작업을 실행하는 가상 머신이다.
  • GitHub가 제공하는 Ubuntu, Windows, macOS 실행기를 사용할 수 있다.
  • 필요하면 자체 호스팅 실행기를 구성할 수도 있다.
• 작업(Job)
  • 하나의 실행기에서 수행되는 단계들의 묶음이다.
• 단계(Step)
  • 셸 명령을 실행하거나 미리 만들어진 재사용 가능한 액션을 호출한다.

Actions 탭과 워크플로 템플릿

• 저장소의 Actions 탭에서는 현재 저장소에 등록된 워크플로를 확인할 수 있다.
• New workflow를 선택하면 저장소에 적합한 추천 템플릿을 확인할 수 있다.
• 템플릿은 YAML 편집기로 열리며, 기본적으로 다음 세 영역을 포함한다.
  • name: 워크플로의 목적을 설명하는 이름
  • on: 워크플로를 실행할 이벤트
  • jobs: 실제 작업 내용

YAML 워크플로 파일 작성

• 워크플로 파일은 저장소의 .github/workflows 디렉터리에 .yml 확장자로 저장한다.
• 파일명은 build-and-test.yml, security-scanner.yml처럼 역할을 바로 알 수 있게 작성하는 것이 좋다.
• 예제에서는 label-new-issue.yml 파일을 만들고 새 이슈에 라벨을 자동으로 추가한다.
• 워크플로 이름은 다음과 같이 지정한다.

name: Label New Issues

이슈 생성 이벤트 설정

• on 키워드로 워크플로의 실행 조건을 정의한다.
• 다음 설정은 이슈가 새로 생성될 때만 워크플로를 실행한다.

on:
  issues:
    types: [opened]

• GitHub Actions는 다양한 이벤트와 세부 이벤트 유형을 지원하므로, 작업 목적에 맞는 트리거를 선택할 수 있다.

작업 환경과 권한 설정

• jobs 아래에 작업 이름을 지정한다.
• runs-on: ubuntu-latest는 GitHub가 제공하는 최신 Ubuntu 실행기를 사용한다는 의미다.
• 작업이 저장소를 읽고 이슈 라벨을 수정하려면 적절한 권한을 명시해야 한다.

jobs:
  label-issues:
    runs-on: ubuntu-latest
    permissions:
      issues: write
      contents: read

• issues: write는 이슈를 수정할 수 있는 권한이다.
• contents: read는 저장소 콘텐츠를 읽을 수 있는 권한이다.
• 작업 수준에서 permissions를 지정하면 해당 작업의 액션과 명령에 그 권한이 적용된다.

저장소 확인과 라벨 추가 단계

• steps에는 작업에서 순서대로 수행할 동작을 작성한다.
• actions/checkout@v6 액션으로 저장소 코드를 실행 환경에 내려받는다.
• 이후 GitHub CLI를 사용해 새 이슈에 triage 라벨을 추가한다.

steps:
  - name: Checkout repository
    uses: actions/checkout@v6

  - name: Add triage label
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      ISSUE_NUMBER: ${{ github.event.issue.number }}
      LABEL: "triage"
    run: gh issue edit "$ISSUE_NUMBER" --add-label "$LABEL"

• uses는 GitHub Marketplace의 미리 만들어진 재사용 액션을 호출한다.
  • 저장소 체크아웃
  • Node.js 설정
  • 기타 반복적인 개발 작업 등에 활용할 수 있다.
• run은 실행기에서 셸 명령을 직접 실행한다.
• GH_TOKEN에는 GitHub가 제공하는 GITHUB_TOKEN을 사용한다.
• ${{ github.event.issue.number }}는 이벤트 정보에서 새로 생성된 이슈 번호를 가져온다.
• gh issue edit 명령은 해당 이슈에 triage 라벨을 추가한다.

처음에는 GitHub Actions의 템플릿을 활용해 간단한 이벤트 기반 자동화를 만들어 보는 것이 좋다. 이후 이벤트 조건, 최소 권한, 재사용 액션과 직접 실행 명령을 조합하면 테스트·보안 검사·이슈 관리·배포까지 확장할 수 있다.