Deploying from GitHub

Connect a repository once and every push deploys. agenthost clones the branch, builds it and ships it, with no CI to write and no secrets to hand over.

An app can build from a GitHub repository instead of from source your agent hands over on every deploy. Connect it once and a push is a deploy: no workflow file, no runner, no deploy key, and no token for anyone to paste anywhere.

This is for apps — anything that runs code. A static site has no build step for a repository to feed, so it deploys its files directly; see Runtimes.

Connecting

Three steps, and only the middle one is yours.

Your agent calls connect_github and gives you a link.
You open it and install the agenthost app on your GitHub account or organization, choosing which repositories it may read. Pick as few as you like — you can change it later, and agenthost only ever sees what you selected. GitHub sends you back to agenthost, which asks for the email on your account and mails you a six-digit code.
Your agent calls link_repo with the app and the repository. It deploys the branch straight away.

Why the sign-in

GitHub tells us the installation is genuinely yours. What it cannot tell us is which agenthost account it belongs to, and that is the part a link alone should never decide: anyone can send someone a link. Signing in is how your repositories become readable by your account and nobody else's. It happens once per GitHub account, not once per deploy.

link_repo(service_id: "…", repo: "acme/website", branch: "main")

Omit branch and agenthost uses the repository's default branch.

agenthost never asks for a GitHub password or token

Access comes from the GitHub app you installed, scoped to the repositories you picked and revocable at any time from your GitHub settings. Nothing is stored on our side that would still work after you revoke it.

What happens on a push

Every push to the connected branch clones it, builds it and deploys it — the same build your agent would get from deploy_app, from source we read ourselves instead of source it typed. The app's URL, environment variables and databases are untouched.

The commit gets a deployment on GitHub, so the commit page, the pull request that merged it and the repository's Environments tab all show where it went and whether it came up.

Turn it off with auto_deploy: false and nothing deploys until someone asks:

deploy_from_repo(service_id: "…")                  # the connected branch, now
deploy_from_repo(service_id: "…", ref: "v2.1.0")   # a tag
deploy_from_repo(service_id: "…", ref: "9f2db26")  # a specific commit

Controlling the build

Most repositories need nothing: the runtime conventions apply exactly as they do to source handed over inline. When yours does not match them, commit an agenthost.yaml at the root of the repository:

runtime: node:22
install: npm ci --omit=dev
build: |
  npm run build
  node scripts/postbuild.js
start: node dist/server.js

Every value is a shell command, so ./scripts/build.sh is as valid as npm run build. See agenthost.yaml for every setting, what each runtime does with it, and what happens when it is wrong.

For anything beyond those four settings, commit a Dockerfile. agenthost never generates one over the top of yours.

Rolling back

Deploys from a repository join the same history as every other deploy, so list_deploys and rollback_app work unchanged — including after a force push, or after the branch is deleted. agenthost keeps its own copy of every tree it built, so what you rolled back to is what actually shipped.

What to keep out of the repository

The build reads your repository as it is, so the usual rules apply, and one extra:

Secrets are not source. Environment variables are set by you at /secrets-manager, which stores them apart from your code and injects them at run time. A .env committed to the repository becomes part of the image.
Build output and dependencies. node_modules, .venv, dist — they are installed and built on our side. If they are in .gitignore already, there is nothing to do.

When it stops working

"agenthost cannot see acme/website" — the repository was not selected when the app was installed. Run connect_github again and open the link; GitHub lets you add repositories to an existing installation.
A push did not deploy — check the branch. link_repo connects exactly one, and pushes to any other are ignored on purpose.
You uninstalled the app on GitHub — every app connected through that installation is disconnected. They keep running the last build they got; reconnect and link them again.