Branches
Sacred branches (staging, uat, main) each map to one Fly config file, one GitHub Actions workflow, and one Fly org—so the branch name is always the file name.
Three primary branches
Section titled “Three primary branches”These branches are sacred—protected in GitHub, tied to a Fly org tier, and almost always paired with a matching config and workflow:
| Git branch | Fly config | GitHub workflow | Fly org |
|---|---|---|---|
staging | fly.staging.toml | fly-deploy-staging.yml | Staging |
uat | fly.uat.toml | fly-deploy-uat.yml | UAT |
main | fly.main.toml | fly-deploy-main.yml | Production |
main deploys to the production Fly org, but the file name stays fly.main.toml—never fly.production.toml or fly.prod.toml.
The branch name is the file name
Section titled “The branch name is the file name”If you know the branch, you know the Fly config and the workflow—no special “production” filenames.
Never use: fly.production.toml, fly.prod.toml, fly.stag.toml, deploy-production.yml, deploy-prod.yml.
One Dockerfile per repo
Section titled “One Dockerfile per repo”Each API repo has one shared Dockerfile. The same container image is deployed to staging, UAT, and production; each fly.*.toml defines app name, target org, env vars, and tunnel settings for that tier.
Main-only repos
Section titled “Main-only repos”Some services only run in production today. Those repos may have only fly.main.toml and fly-deploy-main.yml—do not add fake staging/UAT files until those tiers exist.
Naming patterns: Naming conventions · Deploy rules: GitHub · Fly