Skip to navigation

Build and deploy from GitHub

Build a blueprint on every push and deploy it without the CLI
View as Markdown

Connect a GitHub repository to a blueprint, and every push to its branch builds a new version. Add an astropods.deploy.yml, and each build also deploys to the environments the file names.

By the end of this guide, a push to main builds your blueprint and redeploys its production agent.

Before you start

  • A repository with an astropods.yml in it. Run ast project create to create one, and see Blueprint Spec for its keys.
  • A GitHub account that can read the repository. For a public repository, you also need push access.
  • Permission to create or edit the blueprint in your Astropods account. To deploy from builds, you also need permission to deploy agents.

Connect the repository

1

Name the blueprint

Go to Blueprints and select Create blueprint. Enter a name, choose its visibility, and select Continue.

2

Connect your GitHub account

Choose Set up with GitHub, select Connect GitHub, and approve access on GitHub. You do this once for each Astropods account.

3

Pick the repository, branch, and path

Choose the repository and the branch to build from. If astropods.yml isn’t at the repository root, set Path to the directory that holds it, such as agents/support. A push then builds only when a file inside that path changes.

4

Create the blueprint

Select Create blueprint, then confirm with Connect and create blueprint. The first build starts at once.

To connect a blueprint you already have, open it, go to Settings > Source, and select Connect GitHub repo. Pick the repository and branch, then select Connect repository. Connecting it starts a build.

Watch a build

Open the blueprint’s Builds tab. Each push to the branch adds a build, and the build moves from building to registered when the new version is in the registry. Select a build to read its logs.

If the branch has no astropods.yml at the path yet, the build fails at the spec step. Push the file, and the next build picks it up.

Deploy each build

Add an astropods.deploy.yml beside astropods.yml. It names the environments to deploy to and how to configure each one:

astropods.deploy.yml
spec: deploy/v1
environments:
production:
branch: main
interfaces: [web, slack]
variables:
OPENAI_API_KEY: { ref: OPENAI_API_KEY }

Commit the file and push it to the connected branch. After the build registers, Astropods deploys it to each environment whose branch matches the connected branch. An environment with no branch deploys on every build. An environment that doesn’t exist yet is created, with a new agent in it.

Set secrets such as OPENAI_API_KEY in the account or the environment before you push. See Managing secrets. The Deploy Spec lists every key the file takes.

To confirm the deploy, open the agent and check its deployment history for a new revision on the build you pushed.

How deploys behave

  • Deploys run as you. Astropods deploys as the person who connected the repository, with that person’s permissions.
  • A failed deploy doesn’t fail the build. The build stays registered, the other environments still deploy, and the person who connected the repository gets a notification with the reason.
  • Settings-only pushes skip the build. When astropods.deploy.yml is the only file that changed, Astropods redeploys with the new settings and keeps each agent on its current build.
  • Vulnerability checks can delay a deploy. If your account blocks builds that haven’t been scanned, the deploy waits up to 10 minutes for the scan to finish.

Change the branch or disconnect

Open the blueprint’s Settings > Source page:

  • Branch sets the branch that builds. Update branch in astropods.deploy.yml to match, or those environments stop deploying.
  • Disconnect stops builds from the repository. Builds already in the registry stay, and running agents keep running.

To build the branch’s latest commit again without a push, open Builds and select Rebuild branch from the newest build’s menu.

Troubleshooting

SymptomFix
A push starts no buildCheck that you pushed to the connected branch, and that a file inside the Path changed.
The build fails at the spec stepAdd astropods.yml at the connected path, or correct Path in Settings > Source.
The build registers, but nothing deploysCheck that astropods.deploy.yml sits beside astropods.yml, and that each environment’s branch is the connected branch or is left out.
A deploy refuses a secretA secret variable needs { ref: NAME }, not a value. Run ast deploy -f astropods.deploy.yml --dry-run to see the error locally.
Builds fail after a teammate leavesBuilds use the GitHub access of the person who connected the repository. Disconnect it and connect it again as a current member.

Next steps