Fly.io와 GitHub Actions로 연속 배포 설정하기

원문 보기 위키 갱신 2026.10.08

이 가이드는 앱의 GitHub 저장소에서 Fly.io로 연속 배포를 설정하는 과정을 안내합니다. go-example이라는 예제 애플리케이션으로 시작해서, 그 앱이 GitHub에서 Fly.io로 자동 배포되도록 만드는 빠른 실행 과정과 각 단계를 자세히 살펴보는 과정을 함께 다룹니다.

출처: 문서

본문

이 가이드는 앱의 GitHub 저장소에서 Fly.io로 연속 배포를 설정하는 과정을 안내합니다. GitHub Actions로 리뷰 앱을 배포하는 방법에 대한 저희 블루프린트도 좋아하실 거예요: GitHub Actions로 리뷰 앱 배포하기.

go-example이라는 예제 애플리케이션으로 시작할 거예요. 요청을 처리한 Fly.io 리전을 표시하는 간단하고 가벼운 앱입니다.

첫 번째 섹션은 go-example 앱이 GitHub에서 Fly.io로 자동 배포되도록 만드는 단계들의 스피드 런입니다. 다음 섹션에서는 각 단계를 더 자세히 다시 살펴봅니다.

연속 배포로 가는 스피드 런

go-example 저장소를 GitHub 계정으로 포크(fork)합니다.
새 저장소를 로컬 머신에 클론합니다.
프로젝트 소스 디렉터리 안에서 fly launch --no-deploy를 실행해 새 앱과 fly.toml 구성 파일을 만듭니다.
설정을 조정하라는 프롬프트에 y를 입력하고 앱 이름을 입력합니다. 리전 같은 다른 설정도 필요에 따라 조정합니다. 그런 다음 Confirm Settings를 클릭하세요.
여전히 프로젝트 소스 디렉터리에서 fly tokens create deploy -x 999999h를 실행해 Fly API 배포 토큰을 얻습니다. FlyV1과 앞의 공백을 포함해 출력을 복사하세요.
GitHub의 새로 만든 저장소로 이동해 Settings를 선택합니다.
Secrets and variables 아래에서 Actions를 선택하고, FLY_API_TOKEN이라는 새 저장소 시크릿을 5단계의 토큰 값으로 만들어 주세요.

프로젝트 소스 디렉터리로 돌아와 다음 내용으로 .github/workflows/fly.yml을 만듭니다:

name: Fly Deploy
on:
  push:
    branches:
      - master    # change to main if needed
jobs:
  deploy:
    name: Deploy app
    runs-on: ubuntu-latest
    concurrency: deploy-group    # optional: ensure only one action runs at a time
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

**참고:** `go-example`의 기본 브랜치는 `master`입니다. 다른 앱을 사용한다면 여러분의 앱은 `main`일 수도 있어요. 그에 맞게 `fly.yml` 파일의 `branches` 값을 변경하세요.

변경 사항을 커밋하고 GitHub에 푸시합니다. fly.toml, Fly Launch 구성 파일, 그리고 fly.yml, GitHub 액션 파일 두 개의 새 파일을 푸시해야 합니다.

그러면 마법이 일어납니다. 푸시가 배포를 트리거하고, 이제부터 변경 사항을 푸시할 때마다 앱이 자동으로 재배포됩니다.

그 과정을 직접 지켜보고 싶다면 저장소로 이동해 Actions 탭을 선택하세요. 실행 중인 명령의 라이브 로그를 볼 수 있습니다.

배포 과정 자세히 보기

`fly.toml`과 저장소

1단계는 단순한 GitHub 포크입니다. 배포하는 저장소를 제어하고 싶기 때문에 꼭 해야 한다는 것 외에 할 말이 많지 않아요.

2단계는 단순히 저장소를 로컬 시스템에 클론해서 편집하고 변경 사항을 푸시할 수 있게 하는 것입니다.

3단계와 4단계는 Fly.io에 새 앱과 저장소에 들어갈 fly.toml 구성 파일을 만듭니다.

저장소의 `fly.toml`에 대한 참고: 보통 Fly.io가 예제를 출시할 때는 `.gitignore` 파일에 `fly.toml`을 포함해 저장소에 넣지 않는 것을 피합니다. 그리고 사용자는 `fly launch` 명령으로 자신의 `fly.toml`을 직접 만들어야 합니다. 하지만 GitHub Actions를 사용할 때는 배포 과정에서 액션이 사용할 수 있도록 `fly.toml`을 저장소에 넣고 싶을 거예요.

API 토큰

5단계는 API 토큰을 얻는 것입니다. 특정 애플리케이션을 승인하는 데 사용할 배포 토큰을 생성할 수 있어요. 그것이 flyctl tokens create deploy -x 999999h가 제공하는 것입니다. 앞의 FlyV1과 공백을 포함해 출력에서 토큰 전체를 복사하는 것을 잊지 마세요. 여러 애플리케이션을 관리할 수 있는 더 강력한 토큰은 flyctl auth token을 실행하세요.

6단계와 7단계는 저장소에 대해 실행되는 GitHub Actions가 새 토큰을 사용할 수 있게 만듭니다. 저장소 설정에서 토큰을 시크릿으로 추가합니다. Settings 탭 아래에서 Secrets and variables로 가서 Actions를 선택하세요. 초록색 "New repository secret" 버튼을 클릭하고 이름을 FLY_API_TOKEN으로 입력한 다음 토큰을 시크릿으로 복사합니다.

환경 시크릿(environment secret)을 원한다면, 배포 단계에서 선택한 환경을 나열해야 합니다. 예를 들어:

deploy:
    name: Deploy app
    runs-on: ubuntu-latest
    environment: production

워크플로 빌드와 배포

8단계는 프로세스의 핵심으로, 워크플로를 배치하는 곳입니다. GitHub에는 워크플로를 선택하고 편집할 수 있는 UI가 있지만, 저장소의 일부로도 수정할 수 있어요. 그래서 .github/workflows/fly.yml을 만듭니다. 디렉터리를 빠르게 만들려면 mkdir -p .github/workflows를 실행하면 좋아요. 그리고 GitHub Action 레시피로 파일을 채웁니다.

GitHub Action 레시피를 줄 단위로 살펴볼게요:

name: Fly Deploy

이것은 액션의 표시 이름을 설정합니다.

on:
  push:
    branches:
      - master

이 액션은 언제 실행되어야 할까요. 옵션이 많지만, 이 경우에는 저장소의 master 브랜치로의 모든 push에 대응합니다. 저장소가 master가 아닌 다른 기본 브랜치(예: main)를 사용한다면 여기서 변경해야 합니다.

jobs:
  deploy:
      name: Deploy app
      runs-on: ubuntu-latest
      concurrency: deploy-group

액션은 이름 있는 작업(jobs)으로 구성됩니다. 이 경우에는 애플리케이션을 배포하는 하나의 작업입니다. 작업은 가상 머신에서 실행됩니다. 이 섹션은 "deploy" 작업에 "Deploy app"이라는 이름을 주고 GitHub Actions에 최신 버전의 Ubuntu가 있는 가상 머신에서 실행하라고 지시합니다. 선택적으로 concurrency 키를 사용자 지정 그룹 이름과 함께 사용해 해당 그룹에 대해 한 번에 하나의 액션만 실행되도록 할 수 있어요.

다음 부분은 이 작업을 완료하는 데 필요한 단계를 설정하는 것입니다.

      steps:
        - uses: actions/checkout@v4

첫 번째 단계는 내장된 Actions 단계 중 하나입니다. 이 단계는 checkout@v4 action을 uses하여 저장소를 가상 머신의 디렉터리에 체크아웃합니다. 이제 배포할 준비가 되었어요.

        - uses: superfly/flyctl-actions/setup-flyctl@master
        - run: flyctl deploy --remote-only

이 단계는 superfly/flyctl-actions action을 uses합니다. 이는 Fly.io가 만든 GitHub 액션으로 flyctl 명령을 감싸는(wrap) 것입니다. 래퍼는 deploy 인자로 호출되며, 애플리케이션을 빌드하고 Fly.io 인프라로 이동하는 과정을 대신 처리해요. fly.toml 파일의 설정을 사용해 안내하고, FLY_API_TOKEN을 사용해 Fly.io GraphQL API에 대한 접근을 승인합니다.

          env:
            FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

이것은 GitHub의 시크릿 엔진에서 API 토큰을 가져와 액션에 전달되는 환경 변수에 넣습니다.

9단계는 두 개의 새 파일을 저장소로 푸시합니다. fly.toml, 앱 구성 파일과 fly.yml, GitHub 액션 파일입니다. 푸시는 첫 번째 자동 배포를 트리거합니다. 이제 GitHub 액션은 저장소에 변경 사항을 푸시할 때마다 재배포를 트리거합니다.

결론과 추가 자료

그것이 배포 과정입니다. 물론 GitHub Actions 환경을 활용해 더 정교한 배포를 관리하거나, 다른 애플리케이션과 상호 작용하고 — 예를 들어 완료 시 Slack 메시지를 보내는 등 — 상상할 수 있는 어떤 것이든 처리할 수 있어요.

읽어보기 (Read):

보기 (See):

flyctl용 GitHub Actions