Forgejo Operations Reference

doc-forgejo-ops Doc

active infrastructure

Project

Forgejo Operations Reference

Operational knowledge for the self-hosted Forgejo instance at forgejo.tail5b443a.ts.net. Deployed via Helm chart (v16.2.0) in the forgejo k8s namespace. Managed by Terraform in pal-e-platform.

Accounts

User	Auth Method	Role	Notes
`forgejo_admin`	Local password	Site admin (not k8s admin panel — limited to API admin)	Password in `~/secrets/pal-e-services/forgejo.env` as `FORGEJO_ADMIN_PASSWORD`
`ldraney`	Keycloak SSO	Primary user, org owner	No local password. Cannot create API tokens via own credentials — must use `forgejo_admin` basic auth to manage tokens via API.

API Tokens

Token creation requires basic auth (username + password). Forgejo rejects token-auth for the /users/{user}/tokens endpoint. Use forgejo_admin basic auth to create/delete tokens for any user.

# Create token for ldraney
curl -X POST "https://forgejo.tail5b443a.ts.net/api/v1/users/ldraney/tokens" \
  -u "forgejo_admin:$FORGEJO_ADMIN_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name":"token-name","scopes":["all"]}'

# Delete token
curl -X DELETE "https://forgejo.tail5b443a.ts.net/api/v1/users/ldraney/tokens/{id}" \
  -u "forgejo_admin:$FORGEJO_ADMIN_PASSWORD"

Token Locations

Variable	User	File	Consumers
`FORGEJO_TOKEN`	ldraney	`~/secrets/pal-e-services/forgejo.env`	`~/.mcp.json` (forgejo-mcp), `~/.git-credentials`
`FORGEJO_ADMIN_TOKEN`	forgejo_admin	`~/secrets/pal-e-services/forgejo.env`	Platform scripts, CI curl commands
`FORGEJO_ADMIN_PASSWORD`	forgejo_admin	`~/secrets/pal-e-services/forgejo.env`, `~/secrets/pal-e-platform/secrets.env`	Token management API, Terraform monitoring module

After rotating tokens, update: (1) ~/secrets/pal-e-services/forgejo.env, (2) ~/.mcp.json FORGEJO_TOKEN value, (3) ~/.git-credentials. Restart Claude Code session to reload MCP.

Git Authentication

HTTPS + credential-store. SSH is not exposed (see below). All repos use https://forgejo.tail5b443a.ts.net/... URLs.

# Global config
git config --global credential.helper store

# Credentials file (~/.git-credentials, chmod 600)
https://ldraney:{FORGEJO_TOKEN}@forgejo.tail5b443a.ts.net

Never embed tokens in remote URLs. Prior to 2026-05-24, all 50+ repos had tokens baked into .git/config remote URLs. This was cleaned up — use credential-store exclusively.

SSH Access (Not Exposed)

Status: not available. Forgejo listens on port 22 internally via forgejo-ssh ClusterIP service, but SSH is not exposed outside the cluster.

Tailscale Funnel only supports HTTPS — cannot tunnel SSH
SSH_DOMAIN is configured as forgejo.tail5b443a.ts.net in Helm values
No NodePort or LoadBalancer for SSH exists

Options to expose SSH:

Tailscale Operator + TCP proxy: Tailscale can proxy raw TCP (not just HTTPS) via a ProxyGroup or Connector. Requires Tailscale operator config in Terraform.
NodePort: Expose forgejo-ssh as NodePort on a high port (e.g., 2222). Configure SSH_PORT in Helm values to match. Requires ~/.ssh/config entry for the custom port.
Subnet router: archbox already routes 10.43.0.0/16 (k8s service CIDR) to the tailnet. If the Forgejo SSH ClusterIP is in that range, SSH may already be reachable from Tailscale devices. Needs validation.

MCP Integration

forgejo-mcp server in ~/.mcp.json. Uses FORGEJO_TOKEN (ldraney) for API access. Source: ~/forgejo-mcp.

Related Repos

Repo	Platform	Role
forgejo-sdk	Forgejo	Python SDK for Forgejo API
forgejo-mcp	Forgejo	MCP server wrapping forgejo-sdk
pal-e-platform	Forgejo	Terraform modules for Forgejo deployment (Helm, ingress, monitoring)
secrets	Forgejo + GitHub	Credential storage (forgejo.env)

Incident History

2026-05-24: Token Cleanup & Rotation

Discovered all 50+ repos had Forgejo API tokens embedded in git remote URLs
Two tokens were exposed: FORGEJO_ADMIN_TOKEN (forgejo_admin) and FORGEJO_ADMIN_PASSWORD (used as basic auth in some URLs)
Switched all repos to SSH URLs, discovered SSH not exposed, switched back to HTTPS with credential-store
Rotated both FORGEJO_TOKEN (ldraney) and FORGEJO_ADMIN_TOKEN (forgejo_admin)
Deleted stale tokens: claude-code, claude-code-20260518, portfolio-api, sdk-test-token
zshrc-custom repo was accidentally pushed to GitHub (private) — remote switched to Forgejo