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 connectThe 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 connectGitHub 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 disconnectafy 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| Flag | Short | Default | Purpose |
|---|---|---|---|
--branch | -b | main | The branch Aetherfy tracks for deployments |
--root-dir | — | repository root | The 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.
- Relink, or the next push repeats it.
- 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@developIf 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-botThe flag does two things at once on Aetherfy, and both matter:
| Role | Effect |
|---|---|
| Config search root | Aetherfy looks for aetherfy.yaml inside that subtree, not at the repository root |
| Build context | Only 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-taskOmit --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-agentRe-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-botThis 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-botPausing 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 runafy deployto 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 deployand 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:
- Clones the repository at the exact pushed commit.
- Reads the
aetherfy.yamlfrom that commit, in the agent’sroot_dir(the repository root when none is set). - Records all of it as that deployment’s configuration.
- 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:
| Case | Result |
|---|---|
| The event is not a push | Ignored |
| The branch does not match the tracked branch | Ignored |
| The repository does not match the linked repository | Ignored |
| The agent is paused | Announced on the commit, no deployment created |
| Auto-deploy is paused for the agent’s link | Announced on the commit, no deployment created, and the push is never deployed later |
| The GitHub account this agent deploys through is not connected | No deployment created, and not announced |
| The tracked branch was deleted | No 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 push | Its check ends |
|---|---|
| Deployed and went live | success |
| Failed, or was rejected (a manifest that would not parse, a plan limit) | failure |
| Cancelled before it went live | cancelled |
Changed nothing under the agent’s root_dir | skipped |
| Superseded by a newer commit (see pushing while a deploy is running) | skipped |
| Could not be ordered against another push | skipped |
| Agent paused, being deleted, or archived while the push waited | skipped |
| Auto-deploy paused for the agent’s link, when the push arrived or while it waited | skipped |
| Agent unlinked while the push waited | skipped |
| Agent relinked to another repository or branch while the push waited | skipped |
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@mainEach 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.