vault-plugin-secrets-forgejo

A Vault dynamic-secret plugin that mints Forgejo personal access tokens via the Forgejo admin API.

Tokens are revoked automatically when their Vault lease expires or is explicitly revoked.

Build

just build       # plugin binary
just image       # OCI image: hashicorp/vault + plugin baked in
just test        # go test ./...
just vet         # go vet ./...
just lint        # golangci-lint run
just fmt         # nix fmt (treefmt: nixfmt + gofumpt)
just bump        # nix flake update + commit
just             # list all recipes

Creating a bot account

The plugin mints tokens for an existing Forgejo user; it does not create users. Provision the bot once via forgejo admin user create, then reference it from a Vault role.

kubectl -n forgejo exec -it forgejo-0 -- \
    forgejo admin user create \
        --username my-bot \
        --email my-bot@example.org \
        --random-password

The bot's password is only needed if you ever want to log in as the bot directly; Vault uses the configured admin credentials (with Sudo: my-bot) to mint tokens, so the bot password can otherwise be discarded.

Vault setup

Once the custom Vault image is deployed and Vault is unsealed:

# Compute the plugin's sha256 inside the running Vault pod
plugin_hash=$(kubectl -n vault exec vault-0 -- sha256sum /vault/plugins/vault-plugin-secrets-forgejo | awk '{print $1}')

# Register and enable
vault plugin register -sha256="$plugin_hash" secret vault-plugin-secrets-forgejo
vault secrets enable -path=forgejo vault-plugin-secrets-forgejo

# Configure the admin endpoint (admin creds typically live in Vault already)
vault write forgejo/config \
    admin_url=https://git.example.com \
    admin_username=forgejo_admin \
    admin_password=...

# Define a role
vault write forgejo/roles/my-bot \
    bot_username=my-bot \
    scopes=read:repository,write:repository,read:issue,write:issue \
    default_ttl=1h \
    max_ttl=168h

Usage

vault read forgejo/creds/my-bot
# Key         Value
# ---         -----
# lease_id    forgejo/creds/my-bot/abc...
# token       0123abcdef...
# token_id    42
# username    my-bot

vault lease revoke forgejo/creds/my-bot/abc...
# Token is deleted from Forgejo immediately.

The plugin issues POST /api/v1/users/<bot>/tokens with admin BasicAuth and a Sudo: <bot> header to mint, and the corresponding DELETE to revoke. The bot user must already exist on the Forgejo side; the plugin does not create users.

License

MIT.