본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

GitHub의 Git Branch 미리보기 환경 (Git Branch Preview Environments on Github)

원문 보기 위키 갱신

GitHub Actions를 활용해 각 풀 리퀘스트(PR)마다 Fly.io에 일시적인 "리뷰 앱(review app)"을 자동으로 만들어 보는 방법을 알려드려요. 새 기능, 변경사항, 버그 수정을 미리 확인하는 데 아주 유용하답니다.

출처: 문서

본문

개요 (Overview)

리뷰 앱은 새 기능, 변경사항, 버그 수정을 미리 보는 데 아주 좋은 방법이에요. 이 가이드는 GitHub Actions를 사용해 각 풀 리퀘스트(PR)마다 Fly.io에 일시적인 "리뷰 앱"을 자동으로 생성하는 방법을 가르쳐 드려요. 이 접근 방식은 브랜칭과 훅(hooks)을 지원하는 다른 Git 서비스나 소스 코드 버전 관리 소프트웨어에도 적용할 수 있어요.

빠른 시작 (Quick Start)

GitHub Actions를 다뤄본 적이 있고 바로 시작하고 싶다면, 다음 단계를 따라 하세요:

  1. GitHub 리포지토리에 FLY_API_TOKEN이라는 새 리포지토리 시크릿을 만들고, fly tokens org <ORG NAME>의 반환값으로 채워 넣으세요.
  2. 프로젝트의 .github/workflows/fly-review.yml에 새 워크플로우를 만들고 다음 YAML 코드를 추가하세요.
  3. GitHub 워크플로우가 포함된 변경사항을 커밋하고 push하세요.

그게 전부예요! 새 풀 리퀘스트가 생기면 애플리케이션용 리뷰 앱 생성이 트리거돼요.

기본적으로 리뷰 앱은 https://pr-<PR number>-<repository owner>-<repository name>.fly.dev에서 사용할 수 있어요.

위에서 설명한 워크플로우는 다른 리소스 없이 단일 애플리케이션을 띄워요. 데이터 저장소, 여러 Fly App, 또는 다른 리소스가 필요하다면 워크플로우 커스터마이징을 참고하세요.

각 단계에 대한 자세한 내용은 아래 가이드를 따라 하세요.

Fly.io에서 리뷰 앱 설정하기

Fly API 토큰 설정

GitHub Action이 Fly.io에서 새 리뷰 앱을 배포하고 관리하려면 Fly API 토큰이 필요해요. 다음 flyctl 명령으로 이 토큰을 얻을 수 있어요:

fly tokens org <ORG NAME>

이 토큰은 단일 Fly.io 조직에만 특정되며, 해당 조직에 속한 애플리케이션에 대해 유효해요.

다음으로, API 토큰을 GitHub 리포지토리의 시크릿으로 저장해 볼게요. 리포지토리에서 Settings 탭으로 이동한 다음 Secrets and variables → Actions로 가세요. 또는 https://github.com/<username or org>/<repository>/settings/secrets/actions를 방문해도 돼요. 거기에서 토큰 값을 사용해 FLY_API_TOKEN이라는 새 Repository Secret을 만드세요.

GitHub Action 만들기

다음으로, 앱 리포지토리에 워크플로우용 새 YAML 파일을 만들어 새 GitHub Action을 만듭시다:

touch .github/workflows/fly-review.yml

그런 다음 새 fly-review.yml 파일에 다음을 추가하세요:

name: Deploy Review App
on:
  # Run this workflow on every PR event. Existing review apps will be updated when the PR is updated.
  pull_request:
    types: [opened, reopened, synchronize, closed]

env:
  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
  # Set these to your Fly.io organization and preferred region.
  FLY_REGION: iad
  FLY_ORG: personal

jobs:
  review_app:
    runs-on: ubuntu-latest
    outputs:
      url: ${{ steps.deploy.outputs.url }}
    # Only run one deployment at a time per PR.
    concurrency:
      group: pr-${{ github.event.number }}

    # Deploying apps with this "review" environment allows the URL for the app to be displayed in the PR UI.
    # Feel free to change the name of this environment.
    environment:
      name: review
      # The script in the `deploy` sets the URL output for each review app.
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - name: Get code
        uses: actions/checkout@v4

      - name: Deploy PR app to Fly.io
        id: deploy
        uses: superfly/fly-pr-review-apps@1.2.1

deploy 단계에서 superfly/fly-pr-review에는 리뷰 앱을 생성하고 배포하는 셸 스크립트가 담긴 커스텀 Action이 들어 있어요. 스크립트가 어떻게 동작하는지 자세히 보고 싶다면 entrypoint.sh를 확인해 보세요.

워크플로우 커밋하고 push하기

마지막으로, 변경사항을 커밋하고 GitHub 리포지토리에 push하세요. push하고 나면 새 PR이 생길 때마다 Fly.io에서 코드를 미리 볼 수 있는 리뷰 앱이 뜨게 돼요.

워크플로우 커스터마이징 (Customize your workflow)

우리 앱은 종종 단독으로 동작하지 않고 다른 리소스를 필요로 해요. 위의 샘플 워크플로우는 독립 실행형 Fly App을 띄우지만, fly-review.yml GitHub 워크플로우를 커스터마이징해 Redis, Memcached 등의 추가 Fly App과 리소스를 만들 수 있어요. 예시는 superfly/fly-pr-review-apps의 README에서 찾을 수 있어요.

입력값으로 커스터마이징

superfly/fly-pr-review-apps 커스텀 GitHub Action은 동작을 조정하는 데 추가할 수 있는 다양한 inputs(입력값) 도 제공해요. 전체 목록은 README를 참고하세요.

이 입력값들은 워크플로우의 deploy 단계에 with 키를 사용해 추가할 수 있어요:

# fly-review.yml
# ...
    steps:
      # ...
      - name: Deploy PR app to Fly.io
        id: deploy
        uses: superfly/fly-pr-review-apps@1.2.1
        with:
          name: my-app-name-pr-${{ github.event.number }}
          config: fly.review.toml

리소스 스펙 정의하기

리뷰 앱이 사용하는 Fly Machines에는 프로덕션 앱과 동일한 스펙이 필요하지 않을 가능성이 높아요. 리뷰 앱에서 사용하는 리소스를 재정의하는 방법은 두 가지가 있어요.

1. 다른 config 파일 지정하기: 기본적으로 리뷰 앱은 애플리케이션 루트의 fly.toml을 사용하지만, config 입력값을 사용해 다른 스펙을 가진 별도의 TOML 파일을 만들 수 있어요:

# fly-review.yml
# ...
    steps:
      # ...
      - name: Deploy PR app to Fly.io
        id: deploy
        uses: superfly/fly-pr-review-apps@1.2.1
        with:
          config: fly.review.toml

2. GitHub Action 입력값에 스펙 설정하기: 또는 다음 입력값을 사용해 리뷰 앱이 사용하는 Fly Machines의 스펙을 설정할 수 있어요:

  • vmsize
  • cpu
  • cpukind
  • memory
  • ha

기본 시크릿과 환경 변수

리뷰 앱이 요구하는 시크릿이나 환경 변수의 기본값을 설정해서 각각 개별 설정하지 않도록 하는 걸 권장해요. 각 시크릿을 GitHub 리포지토리에 repository secret(리포지토리 시크릿) 또는 environment secret(환경 시크릿) 으로 정의하면 돼요. 환경 시크릿을 사용한다면, 워크플로우에서 사용하는 환경(예: review)에 설정해야 해요.

GitHub에서 시크릿과 환경 변수를 설정했으면, 각각을 fly-review.yml 워크플로우에 공백으로 구분해 추가하세요:

# fly-review.yml
# ...
    steps:
      # ...
      - name: Deploy PR app to Fly.io
        id: deploy
        uses: superfly/fly-pr-review-apps@1.2.1
        with:
          secrets: FOOBAR=${{ secrets.FOOBAR }} SOME_API_KEY=${{ secrets.SOME_API_KEY}}

더 알아보기 (Learn more)