layered-soul/skills/forgejo-operations/references/api-token-setup.md

# Forgejo API Token Setup

## Creating a token

1. Go to `https://<forgejo-instance>/user/settings/applications`
2. "Generate New Token"
3. Token name: `hermes-<hostname>-agent`
4. Select scopes:
   - `write:repository` — create/merge PRs, push to repos
   - `write:organization` — adjust branch protection rules (optional)
5. Copy the token value — it's shown only once.

## Storing the token

```bash
# Append to Hermes .env (mode 0600)
echo 'FORGEJO_API_TOKEN=*** >> ~/.hermes/.env
chmod 600 ~/.hermes/.env
```

## Using in shell

```bash
# Load from env without printing the token
source ~/.hermes/.env 2>/dev/null

# Use in curl commands
curl -s -H "Authorization: token $FORGEJO_API_TOKEN" \
  "https://<forgejo>/api/v1/user"
```

## Pitfall: token truncation

When the token appears in a command string passed to a subshell, the Hermes
agent may redact the value mid-command, resulting in truncated tokens.
Always source from `.env` rather than pasting inline.

## Minimum scopes needed

| Operation                         | Required scope       |
| --------------------------------- | -------------------- |
| Create PR                         | `write:repository`   |
| Merge PR                          | `write:repository`   |
| List PRs                          | `read:repository`    |
| Adjust branch protection          | `write:organization` |
| Create repos under org            | `write:organization` |
| Admin (create users, manage keys) | `write:admin`        |