vault-plugin-secrets-gitea

A Vault / OpenBao secrets engine that mints ephemeral, scoped Gitea access tokens on demand.

Why

Static Gitea bot users (teabot personalities, CI identities, ...) should never hold long-lived personal access tokens: a leaked token is valid until someone notices and deletes it, and Gitea tokens never expire on their own. This engine removes standing tokens entirely:

• You seed it once with a single Gitea site-admin credential.
• A role binds a target Gitea username to a set of token scopes and TTLs.
• Each read of creds/<role> mints a fresh token for that user, bound to a Vault lease, and deletes it from Gitea when the lease is revoked or expires.

Why an admin username + password, not an admin token

Gitea's token-management endpoints (POST/DELETE /api/v1/users/{username}/tokens) are guarded by reqBasicOrRevProxyAuth() — they reject token/bearer auth and accept only HTTP Basic Auth or reverse-proxy auth (go-gitea/gitea#21186). The same routes are also guarded by reqSelfOrAdmin(), so a site admin using Basic Auth may mint and delete tokens for any user by naming them in the path. That is the mechanism this engine relies on, which is why the seeded credential is an admin username + password, not a token.

The Vault lease is the only expiry

Gitea access tokens have no server-side TTL. The Vault lease is therefore the sole expiry mechanism: when the lease is revoked or reaches max_ttl, the engine issues DELETE /api/v1/users/{username}/tokens/{id} to remove the token. A delete that returns 404 (token already gone) is treated as success, so revocation is idempotent and Vault's retries converge.

Paths

Path	Description
config	Gitea URL + TLS settings + seeded admin admin_username/admin_password. Verifies the credentials are a site admin on write.
config/rotate-root	Rotate the seeded admin password in place (generates a new random password, changes it via the admin API, stores it).
roles/<name>	Mint policy: username, scopes, ttl, max_ttl, token_name_prefix.
roles	List roles.
creds/<role>	Read to mint a short-lived, lease-bound token for the role's user.

Scopes

scopes is validated against Gitea's scope set (see models/auth/access_token_scope.go): all, public-only, and the read: / write: forms of activitypub, admin, misc, notification, organization, package, issue, repository, user. write: implies read:.

Usage

vault secrets enable -path=gitea vault-plugin-secrets-gitea

# Seed with a Gitea site-admin username + password (Basic Auth).
vault write gitea/config \
  gitea_url=https://git.example.com \
  admin_username=bot-admin \
  admin_password='...' \
  ca_cert=@gitea-ca.pem

# Immediately rotate the seeded password so only Vault knows it.
vault write -f gitea/config/rotate-root

# A role that mints 1h tokens for the "teabot" user, scoped to repo + issues.
vault write gitea/roles/teabot username=teabot \
  scopes=read:repository,write:issue ttl=1h max_ttl=24h

# Mint one. The token is deleted from Gitea when the lease is revoked.
vault read gitea/creds/teabot

Root rotation requirements & limits

config/rotate-root changes the seeded admin's password via PATCH /api/v1/admin/users/{admin_username}. Honestly documented constraints:

• The admin must be a local Gitea user (external-auth users can't have their password changed this way). Gitea requires login_name on the edit call; the engine sends admin_login_name (default: admin_username) and admin_source_id (default 0, i.e. local).
• The admin account must not have TOTP/2FA enabled — Basic Auth with 2FA requires an OTP header the engine cannot supply.
• Rotation changes Gitea first, then persists to Vault. If the persist fails the engine rolls the password back. If both the persist and the rollback fail (extremely unlikely), the response says so — reset the admin password manually and re-seed config.

Development

make build      # build the plugin binary into ./dist
make test       # unit tests (race)
make e2e        # full lifecycle vs mock Gitea on Vault + OpenBao (Docker)
make rpm        # build Vault + OpenBao RPMs via nfpm

Releases are tag-driven (make patch|minor|major): a Woodpecker pipeline builds the Vault and OpenBao RPMs and uploads them to the internal artifactapi yum repo.

Deployment (out of scope for this repo; documented for the operator)

Live registration in the real cluster is done exactly like the sibling vault-plugin-secrets-rancher engine. The steps, in order:

1. Repos: the Gitea repo is provisioned via terraform-git (config/git.unkin.net/unkin/repository/vault-plugin-secrets-gitea.yaml) → PR → plan/apply. After the repo auto-inits, enable its Woodpecker webhook manually in the Woodpecker UI (new repos get no webhook automatically) so the required pre-commit/build/test checks run.
2. Release: tag v0.1.0 (make minor from v0.0.0). CI publishes rpm-internal/files/Packages/{vault,openbao}-plugin-secrets-gitea-<ver>-1.x86_64.rpm.
3. terraform-vault (mirrors the rancher wiring — merge in this order):
   • policies/gitea/admin.yaml — deployer catalog + engine grant.
   • config/plugins/vault-plugin-secrets-gitea.yaml — plugin catalog entry with the release sha256.
   • puppet-prod: add openbao-plugin-secrets-gitea (pinned to the exact version) to profiles::packages::include on the vault storage role.
   • gitea_secret_backend + gitea_secret_backend_role module instances and their config yamls (via the companion terraform-provider-giteavaultsecret).
4. Seed the admin credential in KV before the backend module applies, e.g. kv/service/vault/au/syd1/secret_backend/gitea/config with admin_username + admin_password for a purpose-built Gitea site-admin bot account (2FA disabled). Then run vault write -f gitea/config/rotate-root so the standing seed password is replaced by one only Vault holds.
5. Reload after a binary upgrade: vault write sys/plugins/reload/backend plugin=vault-plugin-secrets-gitea (the vault plugin reload -plugin=… CLI form is broken on this OpenBao). Bump the RPM version in puppet-prod and the catalog sha256 in terraform-vault together so the on-disk binary stays in lockstep with the catalog.