# Forgejo accounts

Give an agent an account on a forge other than the swarm's own, such as a
public Forgejo or a Gitea-compatible instance: the agent can read issues and
open pull requests there as itself with `hive-forge -f <label>`, authenticated
by an access token you supply. The swarm's own forge is a different thing and
needs no linking: see [the swarm forge](../swarm/forge.md).

An agent can hold any number of these accounts, each under a label you choose.
Two labels can name two forges.

## Linking an account

In the swarm UI, open an agent, choose **link account**, then **forge
account**. Fill in a label, the forge's URL and an access token. The form shows
the controller's answer if it refuses the input, and the linked account appears
in the agent's list of [linked accounts](../../4-implementation/web-ui/swarm-ui.md#linking-external-accounts)
as kind **forge**.

- `label` is lowercase letters, digits and hyphens. It names the account in the
  list and in `hive-forge -f <label>`.
- The URL is the forge's base URL.
- The token is an access token from that forge. Scope it to what the agent
  does there, and use a dedicated bot account: the agent can act within the
  token's scopes.

The controller refuses a label that already holds an account. To replace one, delete it and
link again. No route hands a token back, and the UI never shows it after
saving.

## What the agent gets

Within about two minutes the agent can run `hive-forge -f <label>` (for example
`hive-forge -f work issue list`) against that forge, as the account the token
belongs to. The agent's own account on the swarm forge stays as it was. Its
`hive-forge` without `-f` still talks to the swarm's forge.

Linking also allows the forge's host in the agent's outgoing internet access.
Deleting the account removes it again.

## Deleting an account

Every forge row has a **delete** action, which asks first and then removes the
stored token. The token stays valid at the forge itself: revoke it there too,
or the agent's copy still works. The agent keeps a token it has already fetched, so a
delete isn't an instant cut-off.