[Experimental] Deployments API

When you deploy using flyctl you’re letting our go code run api calls to our Machines API based on your current source code and fly.toml.

We also have the Launch UI which is connectable to GitHub and can be used to skip flyctl locally entirely

The deployments API experiment

We deployed an api that matches the UX from launch UI but can be scripted into however you want with simple HTTP calls. As of now it covers launching a repo (if you have permissions on our GitHub integration) and deploying apps with it.

Understandably it is limited (you can’t pass custom image refs or point at non GitHub sources for example) but we will dogfood into it and see what shape this API needs to be.

Try it out

If you are okay with the fact that this API is prone to changes then give it a try. Checkout the open api spec at: https://fly.io/openapi/deployments.json

If you just want to sneak peek into it, I asked an agent to summarize it.

:robot: text below here was written by a robot

Endpoints for apps that deploy from GitHub through the Fly.io dashboard: read what happened, find out why a deploy failed, start new deploys, and launch an app from a repository.

  • Base URL: https://api.fly.io/api/v1/apps/{app}
  • Auth: Authorization: Bearer <Fly.io token>
    • Reading needs a token that can read the app (for example fly tokens create readonly).
    • Deploying needs one that can deploy it (for example fly tokens create deploy).
    • Launching needs a token with a user who belongs to the organization (for example fly auth token).
  • {id} can be a deployment id or latest.

Read

Endpoint Description
GET /deployments List the app’s deployments, newest first. Query: limit (1–100), before (deployment id, for paging).
GET /deployments/{id} One deployment: status, current step, commit, release, failure, steps, errors, repository settings and the files Fly.io generated for the build. Add ?wait=N (1–30 s) to wait until a running deployment changes.
GET /deployments/{id}/logs The deployment’s log lines. Query: step (e.g. build), limit (last N lines). If the log can’t be read, the answer is still 200, with available: false and a reason (expired or temporarily_unavailable).
GET /deployments/{id}/diagnosis A Markdown brief of the deployment for a person or coding agent: the failed step and where the fix usually is, errors, a log excerpt, generated files, repository settings, the last deployment that worked, and next steps. Query: lines (log lines to include).
GET /deployments/source The app’s repository settings: repository, branch, deploy on push, fly.toml path, working directory.

Deploy

Endpoint Description
POST /deployments Deploy the repository, like “Deploy now” in the dashboard. Body: ref (branch or commit SHA, optional), replace (true to stop a running deployment and start this one).
POST /deployments/{id}/retry Deploy the same commit as that deployment again.
POST /deployments/{id}/cancel Stop a running deployment.
PATCH /deployments/source Change the repository settings. Body: any of branch, auto_deploy, config_path, working_directory.

Each app can start 5 deployments through the API per 10 minutes, and only one can run at a time unless replace is set.

Launch an app from a repository

Endpoint Description
POST /deployments/launch Link a GitHub repository to an existing app and deploy it for the first time. Body: repository (owner/repo, required), branch, config_path, working_directory, review_plan. If the repository has this app’s fly.toml, it deploys it as is. Otherwise Fly.io detects a plan, generates the missing files (pushed to a flyio-new-files branch) and deploys.
GET /deployments/{id}/plan The plan a launch detected: status (detecting, awaiting_confirmation, confirmed, unavailable), settings (region, port, VM size, databases) and the files it will generate.
POST /deployments/{id}/confirm Confirm the plan of a launch started with review_plan: true. Body: settings, optional overrides for region, http_service_port, vm_size, vm_memory, vm_cpus, vm_cpukind. Without review_plan, Fly.io confirms the plan automatically.

When a person has to act before a launch can continue, the answer is 409 with an action_required object containing a kind and a url to hand them:

kind What the person needs to do
github_app_install Install the Fly.io GitHub App on the repository’s owner.
github_repo_access Grant the installed GitHub App access to this repository.
github_collaborator Make a member of the Fly.io organization (with a linked GitHub account) a collaborator on the repository.
launch_prerequisites Fix the organization’s billing, account review or machine quota.

Errors

Every error is JSON: {"error": "<message meant for the user>"}.

Status Meaning
400 Bad parameter or body field
403 The token’s user can’t deploy or launch this app
404 Unknown app or deployment, or a token without access
409 A deployment is already running, it already finished, or a person needs to act (action_required)
422 The app has no linked repository, the branch doesn’t exist, or a setting is invalid
429 Too many API deployments for this app; wait a few minutes
503 GitHub or the deployer is unavailable; try again