fly deploy: Usage, Options & Common CI Errors

Deploy your app to Fly.io from a fly.toml configuration.

fly deploy (flyctl) builds and releases your app to Fly.io based on fly.toml. In CI you authenticate with a Fly API token via an environment variable rather than an interactive login.

What it does

fly deploy builds your image (remotely on Fly builders by default, or locally), pushes it, and performs a release - creating Machines and running health checks before shifting traffic. It reads app name, build, and service config from fly.toml in the working directory.

Common usage

Terminal

# Deploy using fly.toml in the current directory
fly deploy

# CI: authenticate via env, deploy without a remote builder
export FLY_API_TOKEN=fo1_xxxxxxxx
fly deploy --local-only

# Deploy a specific image and app
fly deploy --app myapp --image registry.fly.io/myapp:abc123

Common error in CI: not authenticated / health checks failed

deploy fails with "Error: No access token available. Please login with 'fly auth login'" or "smoke checks / health checks failed" during release. Fix: set FLY_API_TOKEN (from fly tokens create deploy) as an env var so CI skips interactive login, and when a release fails its health checks, read fly logs/fly status - the new Machines did not pass checks, so the deploy rolls back. Fix the app or the check definition in fly.toml before redeploying.

Key options

Option	Purpose
--app NAME	Target app (overrides fly.toml)
--image REF	Deploy a prebuilt image
--local-only	Build locally, not on Fly builders
--strategy	Rollout strategy (rolling, immediate, …)
--build-arg KEY=VAL	Pass Docker build args