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 usual sequence is connect once, then link each Aetherfy agent:

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

Connecting GitHub to Aetherfy

afy github connect installs the Aetherfy GitHub App. It takes no arguments and no flags.

afy github connect

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

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, then use afy github link for each agent.

Checking the Aetherfy GitHub connection status

afy github status shows the current state of the connection. It takes no arguments and no flags.

afy github status

It prints whether GitHub is connected, the installation ID, and the time the connection was made.

Disconnecting GitHub from Aetherfy

afy github disconnect removes the stored installation. It takes no arguments and no flags.

afy github disconnect

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

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.

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.

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.