Archie as a GitHub App #1817

Open
opened 2026-11-08 13:06:09 +00:00 by sam · 3 comments
Owner

A GitHub connection can authenticate as a GitHub App instead of a personal token. The connection's credential holds the app ID and private key; the GitHub forge extension mints short-lived installation tokens for its API calls and hands the daemon a per-repository git token for clone and push. Commits and comments show as the app's bot account.

Core stays forge-neutral: the forge contract gains one call that returns a git credential, its expiry and the bot's commit identity. A forge that does not implement it keeps using the stored token.

Registration (maintainer): create the app with Contents, Issues, Pull requests and Metadata permissions, subscribe to issues, issue_comment, pull_request, pull_request_review and push, set the webhook URL and secret to archie's forge webhook, generate a private key, install it on the repositories.

Known limit: commits pushed over git by an app are not shown as Verified by GitHub; only commits created through the API are. Tracked separately if wanted.

Done when a connection configured with an app credential clones, pushes and opens a PR as the app's bot.

A GitHub connection can authenticate as a GitHub App instead of a personal token. The connection's credential holds the app ID and private key; the GitHub forge extension mints short-lived installation tokens for its API calls and hands the daemon a per-repository git token for clone and push. Commits and comments show as the app's bot account. Core stays forge-neutral: the forge contract gains one call that returns a git credential, its expiry and the bot's commit identity. A forge that does not implement it keeps using the stored token. Registration (maintainer): create the app with Contents, Issues, Pull requests and Metadata permissions, subscribe to issues, issue_comment, pull_request, pull_request_review and push, set the webhook URL and secret to archie's forge webhook, generate a private key, install it on the repositories. Known limit: commits pushed over git by an app are not shown as Verified by GitHub; only commits created through the API are. Tracked separately if wanted. Done when a connection configured with an app credential clones, pushes and opens a PR as the app's bot.
Author
Owner

Implemented: core fa76f4c99 (forge GitCredential call; daemon uses the minted token and bot identity at clone and push), archipelago 8f13cfe (GitHub extension app mode). Store the connection credential as a JSON secret {"app_id": , "private_key": ""}. Not yet verified against a real app installation.

Implemented: core fa76f4c99 (forge GitCredential call; daemon uses the minted token and bot identity at clone and push), archipelago 8f13cfe (GitHub extension app mode). Store the connection credential as a JSON secret {"app_id": <id>, "private_key": "<PEM>"}. Not yet verified against a real app installation.
Author
Owner

Gap: the forge webhook receiver serves only the root file [forge] (one type, one secret), so a GitHub App's webhook cannot be received on an instance whose root forge is Gitea. Needs per-connection webhook intake (path per connection, secret from the connection) before the app's webhook can be enabled; until then GitHub work arrives by polling.

Gap: the forge webhook receiver serves only the root file [forge] (one type, one secret), so a GitHub App's webhook cannot be received on an instance whose root forge is Gitea. Needs per-connection webhook intake (path per connection, secret from the connection) before the app's webhook can be enabled; until then GitHub work arrives by polling.
Author
Owner

Correction to the webhook gap: no new intake is needed. Event capture already gives each source its own path and HMAC secret (X-Hub-Signature-256) set in the dashboard, and bindings map captures to workflows. The GitHub App's webhook URL should be a capture source. The file-configured forge webhook receiver in archied ([forge] intake = webhook|both, default poll) duplicates this.

Correction to the webhook gap: no new intake is needed. Event capture already gives each source its own path and HMAC secret (X-Hub-Signature-256) set in the dashboard, and bindings map captures to workflows. The GitHub App's webhook URL should be a capture source. The file-configured forge webhook receiver in archied ([forge] intake = webhook|both, default poll) duplicates this.
sam added the featuremedium labels 2026-11-14 14:45:42 +00:00
sam added the deferred label 2026-11-15 17:26:12 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#1817