Connect a repository source
A repository source is a provider identity whose permissions define which repositories Helmhive can discover. Connecting one creates candidates; it never enrolls a repository.
Before you begin
Section titled “Before you begin”- Gitea: a bot account with an access token that can read the repositories you intend to enroll. Grant it write permission only on repositories that should later receive pull requests.
- GitHub: the Helmhive GitHub App must be configured by your operator. If it is not, the dialog says so.
Add the source
Section titled “Add the source”- Choose Add source.
- Pick a Provider: Gitea bot or GitHub App.
- For Gitea, enter a Source name, the Gitea URL, the Bot access token, and optionally a Required repository topic: a Gitea repository topic that a repository must carry to be discovered at all. Helmhive validates the token before storing an encrypted copy; it cannot be viewed again.
- For GitHub, choose Continue to GitHub. GitHub asks which account and repositories the App may access, then returns you to Helmhive, which verifies the installation and synchronizes it.
Synchronize and read the result
Section titled “Synchronize and read the result”Each source card shows a connection status (Connected, Not synchronized, Needs credentials, Needs attention, or Disabled) and the last sync run. Choose Synchronize whenever access changes at the provider. A successful run reports how many repositories are visible.
Under Repository candidates, each card shows the provider permission (for example write access) and the capabilities detected for that repository. These are the ceiling for what a
service enrolled from it may ever do:
| Capability | Gitea | GitHub App |
|---|---|---|
repository:read |
Always | Always |
repository:write and branch:create |
When the bot has push or admin permission | When the App has write access to contents |
pull_request:create |
With push or admin permission | Only when the App also has write access to pull requests |
These capabilities are a ceiling, not a grant. Discovery itself never writes. If you want Helmhive to open pull requests later, the source identity must be able to write to those repositories so the ceiling includes it, and a second, separately validated bot does the writing; see Enable pull-request delivery. One bot account with two tokens is acceptable as long as each token is validated for its own purpose.
Keep it healthy
Section titled “Keep it healthy”- Rotate token (Gitea) replaces the stored token after validating the new one. Remove credential stops synchronization until a replacement is validated.
- Disable stops discovery and synchronization from that source. Enrolled services and their history are kept, and the source can be enabled again.
- If a repository disappears from what the source can see, its candidate becomes Access lost and any service enrolled from it is disconnected: queued AI work and deployment authority for that service are cancelled, and the disconnection is audited.
Enroll a service from a visible candidate, or enable pull-request delivery for a separate bot.