Skip to Content
Agent computeGitHub integration
Raw

GitHub integration

Connecting the Aetherfy GitHub App

Aetherfy integrates with GitHub through a GitHub App. One installation of it covers every repository you grant that installation access to, and your Aetherfy account can hold several installations — your personal GitHub account, and one for each organization whose installation GitHub shows you.

afy github connect

The command prints and opens a GitHub authorization URL. Authorizing attaches every account the Aetherfy App is already installed on that you can reach; if it is installed nowhere yet, GitHub asks where to install it first, and repository selection happens on that installation screen — you choose there whether the Aetherfy App gets all repositories or a specific list. You can change that later from GitHub, and Aetherfy needs no action from you when you do, but the change is not without effect: see changing which repositories Aetherfy can see.

You can connect any organization GitHub shows you — you do not have to be an owner or an admin of it. Installing the App on an organization is what requires owner rights; connecting it afterwards does not, which is what lets the person who installs Aetherfy and the people who deploy with it be different people. Which repositories Aetherfy can reach is set by whoever installed the App, on the installation screen, not by who connects.

Anyone who can connect an organization can deploy from every repository that organization granted to Aetherfy — including repositories they cannot read on GitHub — and see their contents in build logs. The installation is the unit of access: an installation token reaches everything the installation covers, and Aetherfy does not narrow it per person. Grant the Aetherfy App only the repositories you intend to deploy, choosing Only select repositories on the installation screen rather than All repositories. You can change the selection at any time from GitHub — see changing which repositories Aetherfy can see.

The command then waits for you to finish on GitHub and reports the connection when it lands. The link is valid for a limited time; the command tells you until when, and stops there rather than waiting indefinitely. If it runs out before anything is recorded, run afy github connect again for a fresh link. Pressing Ctrl-C only stops the waiting — the link stays valid, and finishing on GitHub still connects the account.

Running it again is how you add another account. It never replaces what you have: a personal account and an organization can both be connected, and each agent deploys through the one its repository belongs to.

Installing the Aetherfy App from GitHub

You can also install the App from its own page on github.com, without starting from Aetherfy. GitHub sends you back afterwards, but it does not tell us who you are on that path, so what happens next depends on how you sign in to Aetherfy.

If you sign in with GitHub, the installation is attached to your account automatically and there is nothing further to do. The installation event is signed by GitHub and names the account that performed it, and that is the same GitHub account your Aetherfy sign-in already proves you own.

If you sign in with email or Google, we have no way to tell which Aetherfy account the installation belongs to — an installation identifier on its own says nothing about who owns it, and attaching it on that basis would let one customer register webhooks on another customer’s repositories. The dashboard will show not connected even though the App really does have access. Run:

afy github connect

GitHub recognises the existing installation and attaches it — authorizing works on installations that already exist, so you are not installing the App twice and you do not need to uninstall it first.

Checking and removing the Aetherfy GitHub connection

afy github status afy github disconnect

afy github status lists every GitHub account connected to your Aetherfy account, with its installation id and when it was connected. Those accounts are not always the one you sign in with, and there can be more than one: each agent deploys through the account its repository belongs to, so the list is what tells you which account a given agent depends on. The dashboard’s Integrations tab shows the same list, one row per account (Settings).

afy github disconnect <account> disconnects one of them. Agents linked to that account’s repositories stop deploying on push; agents deploying through your other accounts are untouched.

afy github disconnect with no argument removes every connected account at once, and is idempotent — running it when nothing is connected is not an error.

Either way, existing deployments on Aetherfy are unaffected and keep running; what stops is automatic deployment on push, whether the repository is public or private.

Uninstalling the App from GitHub does the same thing for that account, by the same route. You do not need to do both.

Your links survive it. Each agent keeps its repository, branch and directory, so reconnecting that account resumes automatic deployment with nothing to set up again. In the agent list, a linked agent is marked AUTO-DEPLOY, and AUTO-DEPLOY OFF while you are disconnected or its branch is deleted (a third badge, AUTO-DEPLOY PAUSED, is for a pause you set yourself). The agent’s GitHub link panel says which, and afy status <agent> says the same in the terminal. These are the only places it is reported, because saying it on the commit would itself need the GitHub access you just withdrew.

Unlinking is the separate, permanent action: use it when you want an agent to forget its repository. To stop pushes from deploying while the agent keeps its repository, branch and directory, pause auto-deploy instead.

Linking a repository to an Aetherfy agent

The agent must already exist before you can link it — linking attaches a repository to an agent, it does not create one. The first deploy is what creates the agent (afy deploy <path>, or afy deploy --from-github); link it after that, and every later push deploys it.

Connecting the App is account-level. Linking is per-agent: it tells Aetherfy which repository, branch, and directory belong to a given agent.

afy github link my-bot myorg/my-agent
FlagShortDefaultPurpose
--branch-bmainThe branch Aetherfy tracks for deployments
--root-dir—repository rootThe repo-relative folder holding this agent’s code and aetherfy.yaml

Linking registers the webhook before it records anything, so a link either works completely or changes nothing. If the Aetherfy App has no access to the repository you named, the link fails with GITHUB_REPO_NOT_FOUND and any existing link on that agent is left untouched.

That error cannot tell you which of two things went wrong, and deliberately so: GitHub hides repositories you lack access to rather than revealing that they exist. So “not found” and “not granted to Aetherfy” arrive identically. If you are sure of the name, the answer is almost always the second — grant the repository to the App and link again.

Changing which repositories Aetherfy can see

Repository access belongs to the installation, not to Aetherfy, so you change it on GitHub: Settings → Applications → Installed GitHub Apps → Aetherfy Bot → Configure. Add or remove repositories there and save. afy github status prints a direct link to that page for each connected account.

Adding a repository takes effect immediately and needs nothing on the Aetherfy side. You can link an agent to it straight away.

Removing one stops that repository deploying, and says so. The webhook stays on the repository and GitHub keeps delivering pushes to it, so the next push still creates a deployment — which fails, naming the repository and telling you to either grant it to the App again or reconnect the account that owns it. Any agent still linked keeps its link throughout.

So you are not left with an agent quietly shipping code from a repository you revoked, and you are not left guessing why it stopped either. The same message appears when the account connected to Aetherfy has changed since the link was made: the two causes are indistinguishable from GitHub’s side, which is why it names both remedies.

Linking an Aetherfy agent to the wrong repository

Linking deploys nothing by itself, so a wrong link is harmless until the next push. Relink the agent to the right repository and there is nothing to undo: relinking replaces the webhook, and the old one is removed once the new link is recorded.

If a push landed first, that push built and deployed, and the agent runs the other repository’s code. Two separate things need doing, in this order.

  1. Relink, or the next push repeats it.
  2. Roll back, to put the previous code back. afy rollback <agent> prints the deployment history and asks which version to return to. See Rollback.

Rolling back without relinking fixes the running agent and leaves the cause in place. Relinking without rolling back stops the bleeding and leaves the wrong code running until the next real push.

Aetherfy will not deploy a repository an agent is not linked to. If a push arrives from another repository than the linked one — which happens when a link moved but its webhook did not — it is ignored rather than built.

The link is to the repository itself, not to its name. Aetherfy records the repository as GitHub identifies it when you link, so the name’s casing does not matter (MyOrg/MyRepo links myorg/myrepo). If you rename the repository on GitHub, or transfer it to another account, pushes keep deploying, and the link takes the new name at the first push after the change. That protects against a stale webhook, not against linking the wrong repository on purpose, which is a valid instruction Aetherfy has no way to second-guess.

Choosing a branch for an Aetherfy agent

Two forms do the same thing — a flag, or an @branch suffix on the repository argument:

afy github link my-bot myorg/my-agent --branch develop afy github link my-bot myorg/my-agent@develop

If you give both and they disagree, --branch wins.

Aetherfy tracks exactly one branch per agent. A push to any other branch does not deploy.

Keeping several Aetherfy agents in one repository

--root-dir names the repo-relative folder that holds one agent’s code and its aetherfy.yaml:

afy github link my-bot myorg/monorepo --root-dir agents/my-bot

The flag does two things at once on Aetherfy, and both matter:

RoleEffect
Config search rootAetherfy looks for aetherfy.yaml inside that subtree, not at the repository root
Build contextOnly that subtree is uploaded. Sibling folders never enter the build.

Because the build context is scoped, this is how several agents live in one repository without each one dragging in the others’ code:

afy github link api-bot myorg/monorepo --root-dir agents/api-bot afy github link report-task myorg/monorepo --root-dir agents/report-task

Omit --root-dir and the whole repository becomes the build context.

Each agent you link this way gets a webhook of its own on the repository, so one push reaches every linked agent. Aetherfy handles each agent’s delivery separately: a push deploys only the agents whose directory it changed, and every other linked agent reports a skip. Each agent posts its own check on the pushed commit, named after the agent — aetherfy/deploy/api-bot and aetherfy/deploy/report-task for the two above — so one agent’s skip never hides another agent’s deployment.

The webhook secret Aetherfy shows once

The response to afy github link prints a webhook secret exactly once. It is not retrievable later — Aetherfy will not show it again, and there is no command that reveals it.

Copy it when it appears. If you lose it, or you want to rotate it, re-run afy github link on the already-linked agent:

afy github link my-bot myorg/my-agent

Re-linking an already-linked agent is supported and is the intended rotation path. Aetherfy creates the new webhook before removing the old one, so automatic deployment keeps working throughout the rotation with no window where pushes are dropped. A link whose auto-deploy is paused stays paused through a re-link.

Unlinking a repository from an Aetherfy agent

afy github unlink my-bot

This removes the link and is idempotent. Aetherfy deletes the webhook from the repository; an unlink still succeeds if GitHub cannot be reached at that moment, and Aetherfy no longer acts on a webhook that remains.

A push that is waiting for a deploy in progress when you unlink is not deployed. Before the link is removed, Aetherfy ends that push’s check as skipped, with “Skipped — agent unlinked from this repository”, so the commit is not left waiting for ever.

Relinking an agent to another repository or branch does the same for the pushes waiting under the old link: they are not deployed, and their checks end as skipped with “Skipped — agent now follows <repo>@<branch>”. Changing only the directory with --root-dir keeps them, and they deploy from the new directory.

Pausing and resuming auto-deploy for an Aetherfy agent

To stop pushes from deploying an agent without unlinking it, pause auto-deploy on its link, and resume it when you want pushes to deploy again:

afy github pause my-bot afy github resume my-bot

Pausing keeps the link as it is: the repository, branch, directory and webhook are untouched, and the agent keeps running. It is not the pause of the agent itself (afy stop, see pausing and resuming), which holds the agent instead; the two are independent. Setting the state the link already has changes nothing and says so (“Auto-deploy for my-bot was already paused.” or “was already on.”), and a pause keeps the time it was first set.

While auto-deploy is paused:

  • A push to the linked branch builds nothing. Its commit shows a grey skipped check, named aetherfy/deploy/<agent-name> like every other check Aetherfy reports, titled “Skipped — auto-deploy is paused for this agent”. Its summary names the two ways to ship: resume auto-deploy and push again, or run afy deploy to deploy the latest code now.
  • That push is never deployed later. Not when you resume, and not when it is redelivered from your repository’s webhook settings.
  • A push that is already being cloned or built when you pause finishes. A push that is waiting for the deploy in progress ends with the pause: it is not deployed, and its check ends skipped with the same title.
  • afy deploy and the other ways to release an agent work as usual, a rollback among them.

Resuming deploys nothing by itself. The next push to the linked branch deploys, or run afy deploy to ship the latest code now. A push that arrived while auto-deploy was paused stays undeployed.

Unlinking the agent clears the pause along with the link. Re-linking an agent whose auto-deploy is paused keeps it paused: it stays paused until you resume it.

Aetherfy shows a pause where you look at the agent. The agent’s card carries an AUTO-DEPLOY PAUSED badge, and AUTO-DEPLOY OFF takes its place while the account is disconnected or the branch is deleted (the agent card’s badges). The agent’s GitHub link panel (MORE → GITHUB LINK) carries a banner headed AUTO-DEPLOY PAUSED and a control, PAUSE AUTO-DEPLOY or RESUME AUTO-DEPLOY. afy status <agent> prints “Auto-deploy paused since” and the time, beside the warnings for a disconnected account and a deleted branch, which are independent of the pause and can hold at the same time. Over the API the link carries auto_deploy_paused_at, the time the pause was set, or null when auto-deploy is on, and POST /api/v1/agents/{agent}/github/pause and /resume pause and resume it, each answering the link and whether the call changed anything (the deployments API).

What a push to Aetherfy does

A push to the tracked branch that touches the agent’s root_dir triggers a deployment. Aetherfy then:

  1. Clones the repository at the exact pushed commit.
  2. Reads the aetherfy.yaml from that commit, in the agent’s root_dir (the repository root when none is set).
  3. Records all of it as that deployment’s configuration.
  4. Builds and deploys. When the new version goes live, the agent runs as that configuration describes.

Step 3 is the one to understand. The pushed file is the whole description of how the agent runs: a field it leaves out takes its default, never the value the agent had before. The full rules are on /agents/aetherfy-yaml.

Every push must carry aetherfy.yaml at that path. A push without one is refused like any failed deployment: nothing deploys, and the commit’s check names the repository, the commit, the branch and the path Aetherfy looked in. Broken YAML fails the deployment loudly too. Aetherfy never silently falls back to a previous configuration.

Pushing while a deploy is running

An agent deploys one push at a time. A push that arrives while one of the agent’s deployments is still queued, building or deploying does not start a second deployment beside it. It waits, and its commit shows a queued check that reads “Waiting for the deploy in progress to finish”. Any deployment counts, not only one started by a push: afy deploy, a rollback and a restore hold later pushes back in the same way.

A waiting push has no deployment yet, so Aetherfy shows it where you look at the agent: the agent’s card in the dashboard carries a PUSH WAITING badge with the commit (the agent card’s badges), and afy status <agent> and afy deployments <agent> print a Push waiting line with the commit and when it arrived. Where several pushes wait, they show the one that will deploy.

A push that is being prepared

Before a push becomes a deployment, Aetherfy clones the repository and checks the push. For that stretch the push has no deployment either, and it counts as the agent’s deployment in progress: a push that arrives meanwhile waits behind it, and deploying, rolling back, redeploying or moving the agent is refused with DEPLOYMENT_IN_PROGRESS, and deleting, pausing or archiving it with AGENT_HAS_PENDING_DEPLOYMENTS. Retry when it has finished. The push shows where you look at the agent: a PUSH PREPARING badge with the commit on the agent’s card in the dashboard, a Push preparing line on afy status <agent> and afy deployments <agent>, and github.push_in_clone on the agent (the API). Both can show at once, the push being prepared first and the push waiting behind it. When preparing ends, the push is the agent’s deployment, in state queued, and the badge and the line are gone.

When the deploy in progress ends, however it ends, the waiting push with the newest commit deploys straight away: the end of that deploy is what starts it. Should Aetherfy restart at that very moment, the push is picked up within a minute instead. The other waiting pushes are skipped. Each skipped commit’s check ends with “Skipped — superseded by a newer commit (<sha>)”, naming the commit that deployed instead. When that newer commit was built on top of the skipped ones, as ordinary pushes to a branch are, their changes ship with it.

Newest means the newest commit, not the push that reached Aetherfy last. Aetherfy reads the order from the pushes themselves. A push made on top of another one (its starting commit is the other push’s resulting commit) is the newer of the two. Where two pushes are not linked that way, the head commit’s timestamp decides. So an old push that arrives late never deploys over a newer one. A redelivery from your repository’s webhook settings is one example.

Aetherfy never guesses. When it cannot tell whether a push is older or newer than another one it would deploy beside, because neither was made on top of the other and their timestamps do not tell them apart, the push that cannot be placed is not deployed. Its check says so: “Skipped — could not be ordered against <sha>; push again to deploy”. A new commit pushed on top of the branch can always be placed, so pushing again deploys it.

A skipped check shows grey on GitHub, as skipped. It is not green, because that commit was not deployed, and it is not red, because nothing in the commit was wrong. The check’s summary says why it was skipped.

A skipped check does not block a merge. GitHub counts a skipped check as passing, so a pull request whose branch protection requires the agent’s check can still be merged when that check was skipped.

If the agent is paused, archived or deleted while a push waits, that push is not deployed either. Its check is skipped too, and says which of the three happened. A push that waits when you pause auto-deploy ends the same way, with the check “Skipped — auto-deploy is paused for this agent”.

When Aetherfy ignores a push

Aetherfy creates no deployment at all in these cases:

CaseResult
The event is not a pushIgnored
The branch does not match the tracked branchIgnored
The repository does not match the linked repositoryIgnored
The agent is pausedAnnounced on the commit, no deployment created
Auto-deploy is paused for the agent’s linkAnnounced on the commit, no deployment created, and the push is never deployed later
The GitHub account this agent deploys through is not connectedNo deployment created, and not announced
The tracked branch was deletedNo deployment created; recorded on the agent’s GitHub link

The disconnected-account row is PER AGENT, not per Aetherfy account: each agent deploys through the GitHub account its repository belongs to, so disconnecting one account stops its agents and leaves the rest deploying.

It is also an exception to Aetherfy reporting a skip on the commit, and that is a limit rather than a choice: reporting a check is itself a GitHub call, and it needs the access that being disconnected removed. A push to a linked repository while that account is disconnected is therefore silent on GitHub. It is reported on the agent’s page in the dashboard, and by afy status <agent>, instead — both of which name the account to reconnect.

None of these are failures, and none of them leave a failed deployment behind. A deliberate non-deploy does not fill your dashboard with red.

On the commit, every one of these skips is a grey skipped check, whose summary says why. A push that changed nothing under the agent’s root_dir says there was nothing to deploy. A paused agent’s check names the command that resumes it, and a link whose auto-deploy is paused says so and names both ways to ship.

The last row is the second Aetherfy cannot tell you about on GitHub, alongside the disconnected account above it, and its reason is the sharper of the two and worth knowing. GitHub reports a deleted branch as a push with no commit in it, so there is no commit for Aetherfy to attach a check to — the place every other skip gets reported simply does not exist. Deleting the branch an agent deploys from also has a consequence the others do not: that agent will not deploy again until the branch is back. So Aetherfy records it on the agent’s GitHub link, and the dashboard and afy status <agent> both say the agent is linked and will not deploy until that branch exists again — naming the branch and when it went. Recreate the branch and push; the link is kept, so deploys resume with nothing to set up. Over the API the same fact is branch_deleted_at on GET /api/v1/agents/{agent}/github.

Path filtering works differently: Aetherfy deploys whenever it cannot show that a push missed your root_dir. That covers force-pushes, branch creations and deletions, and very large commit lists where the changed-file set is not fully available. A push in one of those cases can deploy even though no file under root_dir changed.

A push Aetherfy accepted is always deployed

Aetherfy answers a push webhook once the delivery’s signature checks out. That acknowledgement means Aetherfy has this push, not Aetherfy has deployed it: the delivery is recorded first, and the deploy runs from that record.

Three guarantees follow for a push that Aetherfy accepts to deploy. A push that arrives while auto-deploy is paused is not one of them: it is recorded as skipped, never deployed, and a redelivery of it is ignored.

  • An accepted push is always deployed. It survives platform restarts: after an orderly restart it is picked up at once, after a crash within about a minute, and you do not need to push an empty commit to wake it up.
  • A delivery that never reached Aetherfy is sent again. It shows as a red delivery in your repository’s webhook settings; Aetherfy asks GitHub to resend it, and Redeliver on that delivery does the same immediately.
  • Redelivering never duplicates a deployment. A push an agent has already deployed is recognised and ignored, while a push it accepted and did not finish is run again, so Redeliver is the right button after a failure. The one exception is a newer push of the same agent that has started deploying since: the redelivered push is skipped rather than deployed over it. GitHub gives one push the same delivery identifier on every webhook of the repository, so Aetherfy keeps one record per agent: redelivering a push to one agent does not affect another agent linked to the same repository.

A push gets three attempts. A push that runs out of attempts is marked failed; Redeliver gives it a fresh set.

Aetherfy keeps these delivery records for a few days. They hold the push payload GitHub sent, including commit messages and committer names and addresses. Deleting an agent deletes its records with it.

Checks Aetherfy reports on your commits

Aetherfy reports each deploy on the pushed commit as a GitHub check: queued while it waits, in progress while it builds and deploys, then one of these. Deliberate skips are reported too, so a push that Aetherfy chose not to deploy says so on the commit rather than leaving you to guess from silence:

The pushIts check ends
Deployed and went livesuccess
Failed, or was rejected (a manifest that would not parse, a plan limit)failure
Cancelled before it went livecancelled
Changed nothing under the agent’s root_dirskipped
Superseded by a newer commit (see pushing while a deploy is running)skipped
Could not be ordered against another pushskipped
Agent paused, being deleted, or archived while the push waitedskipped
Auto-deploy paused for the agent’s link, when the push arrived or while it waitedskipped
Agent unlinked while the push waitedskipped
Agent relinked to another repository or branch while the push waitedskipped

The check’s title is one short line. Its summary carries the reason in full and, where there is something to do, what to do.

Each agent reports under a check named after it, aetherfy/deploy/<agent-name>. When several agents link the same repository, the commit carries one Aetherfy check per agent, each with that agent’s own outcome. A check keeps the name the agent had when the push arrived, so renaming an agent in Aetherfy while it is deploying resolves the existing check rather than opening a new one. The name is the one Aetherfy’s commit statuses used before it reported checks, so a branch protection rule that requires it keeps working.

A GitHub account connected before Aetherfy started reporting checks has to accept one new permission. Reporting a check needs the Aetherfy App’s Checks: Read and write permission, and GitHub asks each installation’s owner to accept a permission the App adds: the account owner for a personal account, an owner of the organization for an organization. GitHub notifies them, and the request is under Settings → Applications → Installed GitHub Apps → Aetherfy Bot. Until it is accepted, deploys work as before, but no Aetherfy check appears on that account’s commits. Accounts connected afterwards have it from the start.

This makes the pushed commit the single place to look when you are unsure whether a change deployed.

A failure usually says what went wrong and what to do — the repository Aetherfy cannot reach, the branch that no longer exists, the manifest that would not parse. When something fails for a reason that is ours rather than yours, the check says so plainly and carries a reference like Reference: 11ced866-a5e9-40df-aa78-a0012ea836c1. That is the deployment’s own id, which you can also see in the dashboard — quote it if you contact support, and retry the push, because these failures are not caused by anything in your repository.

Private repositories in github_dependencies on Aetherfy

The github_dependencies field in aetherfy.yaml lists repositories to pull in at build time, each as owner/repo@ref:

runtime: python3.12 github_dependencies: - myorg/[email protected] - myorg/protocols@main

Each entry must fullmatch [A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[A-Za-z0-9._/-]+. The @ref is a tag, a branch or a commit SHA.

Private repositories listed here require the Aetherfy GitHub App to be connected and to have access to them. Run afy github connect first, and make sure the dependency repositories are among those you granted on GitHub’s installation screen.

How Aetherfy installs a github dependency

Aetherfy installs the source archive for the ref you named, not a git clone — https://github.com/{owner}/{repo}/archive/{ref}.tar.gz, handed to uv pip install, npm install or bun add depending on your runtime. Private repositories get the same URL with a build-time token that never enters an image layer.

A dependency that builds itself on install is not built. npm runs no prepare script for a tarball, so a JavaScript package whose published form is compiled from its source ships only that source, and importing it fails at runtime. Depend on such a package from a registry instead, or commit its built output to the repository you are depending on. Python packages are unaffected: pip and uv build a source distribution as a matter of course.

This is why the archive is used rather than git+https://: an Aetherfy runtime image has no git binary, so a git install cannot run in one at all.

Last updated on