Forgejo setup

Codaban connects to a self-hosted Forgejo (or Gitea) instance with an access token you create there. You paste it once, in the control panel. Codaban verifies it, registers its own webhook on your organisation, and lists the repositories it can see. There is no app to install and, normally, nothing to copy back. It is a one-time setup step rather than a click. The section below explains why, and it’s worth the two minutes: the same reason decides what Codaban looks like on your pull requests. GitHub works differently — an App you install. See GitHub setup.

​

Why a bot account and a token

On GitHub, Codaban is a GitHub App. An App is a first-class identity: it has its own name and avatar, it is installed on an account, it is granted specific repositories, and it authenticates as itself. codaban[bot] writes the reviews. Forgejo and Gitea have no equivalent. There is no app registry, no install flow, no per-repository grant, and — the part that actually decides the design — no app identity. Every API call is made by a user. So the question isn’t “how do we install Codaban”, it’s “who is Codaban on your instance”, and the only possible answer is: a user account you create for it. That is why the setup asks for a token rather than a button:

• The bot account is Codaban’s face. Its name and avatar appear on every review, every comment, every commit status. Call it codaban, give it an avatar, and reviews read as coming from a reviewer rather than from you.
• Its access is its permissions. Codaban sees exactly the repositories that account can see. Adding or removing it from a team is how you widen or narrow scope — there is no separate “app permissions” screen to get out of sync.
• The token is a credential, not an identity. Encrypted at rest, never shown again, replaceable.

​

Take an avatar

Save one and upload it to the bot account’s profile.

What about OAuth2?

Forgejo can act as an OAuth2 provider, and a “Connect with Forgejo” button would look more like GitHub. It would not help here, for two reasons:

1. An OAuth2 token acts as the human who authorized it. Reviews would be posted under your name, not Codaban’s. The identity problem comes back immediately, and the usual workaround is… a dedicated bot account.
2. It doesn’t remove a setup step. There is no global app registry, so somebody has to register an OAuth2 application on each instance first — the paste moves from a token to a client id and secret.

So OAuth2 is, at best, a later convenience for instances with many users. It is not the missing piece, and Codaban does not use it today.

​

Create the token

Create the bot account first if you haven’t. Any Forgejo user account will do. Name it codaban and give it an avatar, since that is what your team will see on every review. Then sign in as that account and go to: Settings → Applications → Generate new token Give the bot account write access to every repository you want reviewed — add it to a team, or as a collaborator. Codaban can only see what the token can see.

​

Connect it

Control panel → Integrations → Connect a self-hosted Forgejo or Gitea. The panel links straight to the token page on the instance URL you type, so the step above is one click from there. On submit, Codaban: You land back on Integrations with the instance shown as a connected account and its repositories waiting under Add repositories.

​

If Codaban can’t create the webhook

A token without organisation rights can’t register the hook. Codaban says so and hands you the webhook URL and a one-time secret instead. Add it manually: Organisation → Settings → Webhooks → Add webhook → Forgejo

​

Disconnecting

Integrations → Disconnect removes the instance and its repositories from Codaban, and deletes the webhook it created. A webhook you added by hand is Codaban’s to not delete — the panel tells you to remove it yourself. Until you do, deliveries simply bounce.

​

Rotating the token

Connect the same owner again with a new token — as the person who connected it. Someone else re-connecting your instance would be a takeover, so Codaban refuses it. If the instance should change hands, disconnect it first. Codaban rotates the webhook secret, deletes the webhook the previous token registered, and creates a fresh one. The old hook could not survive the rotation anyway — its secret is no longer valid — so leaving it would mean a dead entry firing 401s forever. If the old hook can’t be deleted, the panel says so and names the one thing left for you to do: remove it in Forgejo.

​

Multiple instances and who owns what

An instance is connected by a person, and stays visible on their Integrations page. Its repositories can be pulled into any workspace they own or administer — one instance can feed several workspaces, and one workspace can hold repositories from several instances. The token never leaves the server and is never shown again after you paste it.