> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Build and deploy from GitHub

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`](/cli/project#project-create) to create one, and see [Blueprint Spec](/astropods-package-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

#### Name the blueprint

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

#### 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.

#### 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.

#### 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`**

```yaml title="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](/secrets). The [Deploy Spec](/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

| Symptom                                  | Fix                                                                                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| A push starts no build                   | Check that you pushed to the connected branch, and that a file inside the **Path** changed.                                                 |
| The build fails at the spec step         | Add `astropods.yml` at the connected path, or correct **Path** in **Settings** > **Source**.                                                |
| The build registers, but nothing deploys | Check 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 secret                | A 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 leaves      | Builds use the GitHub access of the person who connected the repository. Disconnect it and connect it again as a current member.            |

## Next steps

* [Deploy Spec](/deploy-spec): every key in `astropods.deploy.yml`
* [Manage environments](/environments): set variables and secrets per environment
* [Use the CLI in CI/CD](/cli/ci): deploy from your own pipeline instead