afy github

The afy github command group in the Aetherfy CLI

afy github connects a GitHub account to Aetherfy and links repositories to agents so that a push deploys them.

All five subcommands exit 1 on failure, which makes this group safe to use in a script without inspecting the printed output.

The agent must already exist before you link it — afy github link 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.

The usual sequence is connect once, deploy each agent once, then link it:

afy github connect
afy deploy ./services/scraper
afy github link catalogue-scraper myorg/agents --branch main --root-dir services/scraper

Connecting GitHub to Aetherfy

afy github connect authorizes Aetherfy on GitHub. It takes no arguments and no flags.

afy github connect

The command opens a GitHub authorization URL in a browser. When it cannot open one, it prints the URL for you to visit manually.

Authorizing attaches every account the Aetherfy App is installed on that GitHub shows you: your own, and any organization whose installation you can reach — you do not have to be an owner or admin of it. If the App is installed nowhere yet, GitHub asks where to install it first.

Anyone who can connect an organization can deploy from every repository that organization granted to Aetherfy, including repositories they cannot read on GitHub. The installation is the unit of access. Grant the App only the repositories you intend to deploy — see connecting the Aetherfy GitHub App.

It then waits for you to finish on GitHub and reports the connection when it lands, so there is nothing to check afterwards. The link is valid for a limited time; the command tells you 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.

Run it again to add another account. It never replaces what you already have, so a personal account and an organization can both be connected at once.

One installation covers every repository you grant it access to during the GitHub install flow. You do not run afy github connect per repository — connect once per GitHub account, then use afy github link for each agent.

Checking the Aetherfy GitHub connection status

afy github status lists the GitHub accounts connected to your Aetherfy account. It takes no arguments and no flags.

afy github status

It prints one block per connected account: the account name and kind, its installation ID, when it was connected, and where to change which repositories Aetherfy can see on it. There can be more than one — a personal account and an organization, say — and each agent deploys through the account its repository belongs to.

afy github status answers about the account. For one agent’s link, run afy status <agent> — see what status shows about a link below.

Disconnecting GitHub from Aetherfy

afy github disconnect [account] removes connected GitHub accounts. It takes one optional positional argument — a GitHub account name as afy github status prints it — and no flags.

afy github disconnect acme-corp
afy github disconnect

To revoke Aetherfy’s access completely, also uninstall the Aetherfy GitHub App from your GitHub account or organization settings.

Listing the repositories Aetherfy can link

afy github repos lists the repositories your GitHub App installations can reach, across every connected account. It takes no arguments.

afy github repos

These are the only repositories afy github link accepts. Linking registers a webhook on the repository, so one no installation can reach cannot be linked, whoever owns it.

The output is grouped by account, and each account is the one an installation is on. They are organizations as often as people, and need not be your GitHub username — which is the half of owner/repo there is otherwise no way to look up. A mistyped owner, a mistyped repository and a repository the App was never granted all fail the same way, so afy github link prints this same list when it cannot find what you asked for.

An empty list means the App is connected and has been granted nothing. Widen its access from the URLs in afy github status.

Linking a repository to an Aetherfy agent

afy github link <agent> <repo> links a repository to an agent so that pushes deploy it. It takes exactly two positional arguments.

The <repo> argument is owner/repo or owner/repo@branch. When both an @branch suffix and --branch are given, --branch wins.

# Watch main at the repository root
afy github link catalogue-scraper myorg/agents
 
# Watch a branch, via the @suffix
afy github link catalogue-scraper myorg/agents@production
 
# Watch a branch and a subdirectory of a monorepo
afy github link catalogue-scraper myorg/agents \
  --branch production \
  --root-dir services/scraper

--root-dir is what makes a monorepo work on Aetherfy: it points at the folder holding this agent’s code and its aetherfy.yaml, so several agents can be linked to the same repository at different paths.

Linking registers a push webhook. Pushes to the configured branch trigger an Aetherfy deployment of the code at --root-dir.

What afy status shows about an agent’s link

afy status <agent> reads the link back. A linked agent prints the repository, the branch that is watched, the directory inside it — repository root when the link has none — and the webhook id; an unlinked agent prints none of this.

afy status catalogue-scraper

It also names the two states in which the link is still there and no push deploys anything. Aetherfy cannot report either one on GitHub: it announces a skipped push as a commit status, which needs the installation token a disconnect removes, and a deleted branch has no commit to attach one to at all.

Relinking fixes neither. With the account disconnected, afy github link fails for the same missing installation; with the branch gone, it succeeds and changes nothing.

afy status <agent> -o json carries the same state under a github key. The field names are listed in /cli/agents.

The Aetherfy webhook secret printed by link

afy github link prints the webhook secret once, at link time. Aetherfy does not store it in retrievable form and no command will show it again.

Nothing about auto-deploy depends on you keeping it. Aetherfy generated it, registered it on the repository hook and stores its own copy; GitHub signs each push delivery with it, and Aetherfy checks that signature before acting. Losing it costs nothing.

Because re-linking creates the replacement webhook first and only then removes the previous one, there is no window in which pushes to the repository go unnoticed by Aetherfy.

Unlinking a repository from an Aetherfy agent

afy github unlink <agent> removes the repository link. It takes exactly one positional argument and no flags.

afy github unlink catalogue-scraper

The command is idempotent — unlinking an agent that has no link succeeds. The GitHub webhook is deleted on a best-effort basis, so a webhook may survive on the GitHub side if the deletion call fails; Aetherfy will no longer act on it either way.

Removing the link stops auto-deploys for that agent. Manual afy deploy is unaffected — see /cli/deploy.

Choosing between Aetherfy auto-deploy and afy deploy —from-github

Aetherfy offers two paths from a GitHub repository to a running agent, and they suit different situations.