GitHub Actions로 배포하기

GitHub Actions는 환경(environments), 동시성 그룹(concurrency groups), 보호 규칙을 통해 배포를 세밀하게 제어할 수 있게 해줘요. 이 글에서는 배포 워크플로를 트리거하고, 환경·동시성·보호 규칙을 활용하는 방법을 다뤄요.

출처: 문서

본문

사전 요구 사항

GitHub Actions의 구문에 익숙해야 해요. 자세한 내용은 워크플로 작성하기를 참고하세요.

배포 트리거하기

배포 워크플로를 트리거하는 데 다양한 이벤트를 사용할 수 있어요. 가장 흔한 것은 pull_request, push, workflow_dispatch예요.

예를 들어 다음 트리거를 가진 워크플로는 다음과 같은 경우마다 실행돼요:

main 브랜치로 푸시가 있을 때
main 브랜치를 대상으로 하는 풀 리퀘스트가 열리거나, 동기화되거나, 다시 열릴 때
누군가 수동으로 트리거할 때

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

자세한 내용은 워크플로를 트리거하는 이벤트를 참고하세요.

환경 사용하기

환경은 production, staging, development 같은 일반적인 배포 대상을 설명하는 데 사용돼요. GitHub Actions 워크플로가 환경으로 배포하면 그 환경이 저장소 메인 페이지에 표시돼요. 환경을 사용해 작업이 진행되기 위한 승인을 요구하거나, 어떤 브랜치가 워크플로를 트리거할 수 있는지 제한하거나, 커스텀 배포 보호 규칙으로 배포를 게이팅하거나, 시크릿 접근을 제한할 수 있어요. 환경을 만드는 방법에 대한 자세한 내용은 배포용 환경 관리하기를 참고하세요.

환경을 보호 규칙과 시크릿으로 구성할 수 있어요. 워크플로 작업이 환경을 참조하면, 환경의 모든 보호 규칙이 통과할 때까지 작업이 시작되지 않아요. 또한 모든 배포 보호 규칙이 통과할 때까지 작업은 환경에 정의된 시크릿에 접근할 수도 없어요. 자세한 내용은 이 글의 커스텀 배포 보호 규칙 사용하기를 참고하세요.

동시성 사용하기

동시성(concurrency)은 같은 동시성 그룹을 사용하는 단일 작업이나 워크플로만 동시에 실행되도록 보장해요. 동시성을 사용해 환경에서 한 번에 최대 하나의 배포만 진행되도록 할 수 있어요. 동시성에 대한 자세한 내용은 워크플로와 작업의 동시성 제어하기를 참고하세요.

배포 없이 환경 사용하기

기본적으로 워크플로 작업이 환경을 참조하면 GitHub는 배포를 추적하기 위한 배포 객체를 만들어요. 환경 구성에서 deployment를 false로 설정하면 배포 생성을 선택 해제할 수 있어요. 유효한 값은 true(기본값)와 false예요. 표현식을 사용할 수도 있어요. 예: deployment: ${{ github.ref_name == 'main' }}.

jobs:
  test:
    runs-on: ubuntu-latest
    environment:
      name: staging
      deployment: false
    steps:
      - name: run tests
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: echo "Running tests with staging secrets"

deployment가 false로 설정되면:

작업이 환경 시크릿과 변수에 완전히 접근할 수 있어요.
GitHub 배포 객체가 만들어지지 않아요 — 환경의 배포 기록이 갱신되지 않아요.
대기 타이머 보호 규칙은 여전히 적용돼요 — 작업이 구성된 시간만큼 대기해요.
필수 검토자(required reviewers)는 여전히 적용돼요 — 작업이 실행되기 전에 검토자가 여전히 승인해야 해요.

이는 환경을 다음 용도로 쓰고 싶을 때 유용해요:

시크릿 정리하기 — 배포 기록을 만들지 않고 관련 시크릿을 환경 이름 아래에 그룹화해요.
접근 제어 — 배포 추적 없이 환경 브랜치 정책을 통해 특정 브랜치가 특정 시크릿을 사용할 수 있는지 제한해요.
CI 및 테스트 작업 — 배포 기록에 노이즈를 추가하지 않고 환경의 구성을 참조해요.

보호 규칙과의 상호작용

deployment 속성은 어떤 보호 규칙이 적용되는지 제어해요:

보호 규칙	`deployment: true` (기본값)	`deployment: false`
없음	배포 생성됨, 작업 실행	배포 없음, 작업 실행
대기 타이머	대기 타이머 적용	대기 타이머 여전히 적용
필수 검토자	검토자 승인 필요	검토자 승인 필요
커스텀 배포 보호 규칙 앱	앱 웹훅 전송, 승인 필요	작업이 오류로 실패

커스텀 배포 보호 규칙(GitHub Apps)은 기능하려면 배포 객체가 필요해요. 커스텀 배포 보호 규칙이 있는 환경에서 deployment: false를 설정하면, 환경의 보호 규칙이 deployment: false와 호환되지 않는다는 주석(annotation) 또는 오류 메시지와 함께 작업이 즉시 실패해요. 워크플로에서 deployment: false를 제거하거나, 환경에서 커스텀 배포 보호 규칙을 제거해요.

참고로 concurrency와 environment는 연결되어 있지 않아요. 동시성 값은 어떤 문자열이든 될 수 있으며 환경 이름일 필요는 없어요. 또한 다른 워크플로가 같은 환경을 사용하지만 동시성을 지정하지 않으면, 그 워크플로는 어떤 동시성 규칙에도 적용되지 않아요.

예를 들어 다음 워크플로가 실행되면, production 동시성 그룹을 사용하는 어떤 작업이나 워크플로가 진행 중이면 pending 상태로 일시 중지돼요. 또한 production 동시성 그룹을 사용하고 상태가 pending인 어떤 작업이나 워크플로도 취소해요. 즉, production 동시성 그룹을 사용하는 작업이나 워크플로가 최대 하나 실행 중이고 하나 대기 중이게 돼요.

name: Deployment

concurrency: production

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: deploy
        # ...deployment-specific steps

작업 수준에서 동시성을 지정할 수도 있어요. 이렇게 하면 동시 작업이 pending이어도 워크플로의 다른 작업이 진행될 수 있어요.

name: Deployment

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    concurrency: production
    steps:
      - name: deploy
        # ...deployment-specific steps

cancel-in-progress를 사용해 같은 동시성 그룹의 현재 실행 중인 작업이나 워크플로를 취소할 수도 있어요.

name: Deployment

concurrency:
  group: production
  cancel-in-progress: true

on:
  push:
    branches:
      - main

jobs:
  deployment:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: deploy
        # ...deployment-specific steps

배포 전용 단계 작성에 대한 지침은 배포 예시 찾기를 참고하세요.

배포 기록 보기

GitHub Actions 워크플로가 환경으로 배포하면 환경이 저장소 메인 페이지에 표시돼요. 환경으로의 배포를 보는 방법에 대한 자세한 내용은 배포 기록 보기를 참고하세요.

조직에서 연결된 아티팩트 페이지로 데이터를 업로드해 모든 빌드의 배포 기록을 한 곳에 모을 수 있어요. 연결된 아티팩트 정보를 참고하세요.

워크플로 실행 모니터링

모든 워크플로 실행은 실행 진행 상황을 보여주는 실시간 그래프를 생성해요. 이 그래프를 사용해 배포를 모니터링하고 디버깅할 수 있어요. 자세한 내용은 시각화 그래프 사용하기를 참고하세요.

각 워크플로 실행의 로그와 워크플로 실행 기록도 볼 수 있어요. 자세한 내용은 워크플로 실행 기록 보기를 참고하세요.

워크플로에서 필수 검토 사용하기

필수 검토자가 구성된 환경을 참조하는 작업은 승인을 받을 때까지 대기해요. 작업이 승인 대기 중일 때 상태는 "Waiting"이에요. 작업이 30일 안에 승인되지 않으면 자동으로 실패해요.

환경과 필수 승인에 대한 자세한 내용은 배포용 환경 관리하기를 참고하세요. REST API로 배포를 검토하는 방법은 워크플로 실행을 위한 REST API 엔드포인트를 참고하세요.

커스텀 배포 보호 규칙 사용하기

Note

커스텀 배포 보호 규칙은 현재 공개 미리보기(public preview) 상태이며 변경될 수 있어요.

타사 서비스로 배포를 게이팅하기 위해 나만의 커스텀 보호 규칙을 활성화할 수 있어요. 예를 들어 Datadog, Honeycomb, ServiceNow 같은 서비스를 사용해 GitHub로의 배포에 자동 승인을 제공할 수 있어요.

커스텀 배포 보호 규칙은 GitHub Apps로 구동되며 웹훅과 콜백을 기반으로 실행돼요. 워크플로 작업의 승인 또는 거부는 deployment_protection_rule 웹훅의 소비를 기반으로 결정돼요. 자세한 내용은 웹훅 이벤트와 페이로드와 배포 승인 또는 거부하기를 참고하세요.

커스텀 배포 보호 규칙을 만들고 저장소에 설치하면, 그 규칙이 저장소의 모든 환경에 자동으로 사용 가능해져요.

환경으로의 배포는 IT 서비스 관리(ITSM) 시스템의 승인된 티켓, 종속성의 취약점 스캔 결과, 클라우드 리소스의 안정적인 상태 메트릭 같은 외부 서비스에 정의된 조건을 기준으로 승인되거나 거부될 수 있어요. 배포를 승인할지 거부할지는 통합하는 타사 애플리케이션과 거기에 정의한 게이팅 조건의 재량이에요. 다음은 배포 보호 규칙을 만들 수 있는 몇 가지 사용 사례로요.

ITSM 및 보안 운영: 품질, 보안, 규정 준수 프로세스를 검증해 서비스 준비 상태를 확인할 수 있어요.
관측성 시스템: 안전성과 배포 준비 상태를 검증하기 위해 모니터링 또는 관측성 시스템(자산 성능 관리 시스템, 로그 집계기, 클라우드 리소스 상태 검증 시스템 등)을 조회할 수 있어요.
코드 품질 및 테스트 도구: 환경에 배포해야 하는 CI 빌드의 자동화 테스트를 확인할 수 있어요.

이와 달리 어떤 위의 사용 사례에 대해서도 나만의 보호 규칙을 직접 작성하거나, 사전 프로덕션에서 프로덕션 환경으로의 배포를 안전하게 승인하거나 거부하는 커스텀 로직을 정의할 수 있어요.

앱으로 배포 추적하기

GitHub의 개인 계정이나 조직이 Microsoft Teams 또는 Slack과 통합되어 있다면, Microsoft Teams나 Slack을 통해 환경을 사용하는 배포를 추적할 수 있어요. 예를 들어 배포가 승인 대기 중일 때, 배포가 승인되었을 때, 또는 배포 상태가 변경될 때 앱을 통해 알림을 받을 수 있어요. Microsoft Teams나 Slack 통합에 대한 자세한 내용은 추천 GitHub 통합을 참고하세요.

배포 및 배포 상태 웹훅을 사용해 배포를 추적하는 앱을 만들 수도 있어요. 환경을 참조하는 워크플로 작업이 실행되면 environment 속성이 환경 이름으로 설정된 배포 객체를 만들어요. 워크플로가 진행되면서 environment 속성이 환경 이름으로, environment_url 속성이 환경의 URL(워크플로에 지정된 경우)로, state 속성이 작업 상태로 설정된 배포 상태 객체도 만들어요. 자세한 내용은 GitHub Apps 문서와 웹훅 이벤트와 페이로드를 참고하세요.

러너 선택하기

배포 워크플로를 GitHub 호스팅 러너 또는 자체 호스팅 러너에서 실행할 수 있어요. GitHub 호스팅 러너의 트래픽은 다양한 네트워크 주소에서 올 수 있어요. 내부 환경으로 배포하고 회사가 사설 네트워크로의 외부 트래픽을 제한하는 경우, GitHub 호스팅 러너에서 실행되는 GitHub Actions 워크플로는 내부 서비스나 리소스와 통신하지 못할 수 있어요. 이를 해결하려면 나만의 러너를 호스팅할 수 있어요. 자세한 내용은 자체 호스팅 러너와 GitHub 호스팅 러너를 참고하세요.

상태 배지 표시하기

상태 배지를 사용해 배포 워크플로의 상태를 표시할 수 있어요. 상태 배지는 워크플로가 현재 실패 중인지 통과 중인지 보여줘요. 상태 배지를 추가하기 흔한 위치는 저장소의 README.md 파일이지만, 원하는 어떤 웹 페이지에도 추가할 수 있어요. 기본적으로 배지는 기본 브랜치의 상태를 표시해요. 기본 브랜치에 워크플로 실행이 없으면 모든 브랜치 중 가장 최근 실행의 상태를 표시해요. URL의 branch와 event 쿼리 파라미터를 사용해 특정 브랜치 또는 이벤트에 대한 워크플로 실행 상태를 표시할 수 있어요.

자세한 내용은 워크플로 상태 배지 추가하기를 참고하세요.

배포 예시 찾기

이 글은 배포 워크플로에 추가할 수 있는 GitHub Actions 기능을 설명했어요.

GitHub는 Azure Web App 같은 여러 인기 서비스에 대한 배포 워크플로 템플릿을 제공해요. 워크플로 템플릿을 시작하는 방법은 워크플로 템플릿 사용하기를 참고하거나 배포 워크플로 템플릿 전체 목록을 살펴보세요. Node.js를 Azure App Service에 배포하기 같은 특정 배포 워크플로에 대한 더 자세한 가이드도 확인할 수 있어요.

많은 서비스 제공업체도 GitHub Marketplace에서 자기 서비스로 배포하기 위한 액션을 제공해요. 전체 목록은 GitHub Marketplace를 참고하세요.