How martinbaillie/vault-plugin-secrets-github works
Project type and purpose
• This is a Vault “secrets engine” plugin written in Go, named vault-plugin-secrets-github.
• It extends HashiCorp Vault by mounting under a path (e.g. /github) and handling CRUD on config, permission-sets, tokens, revocation, metrics and info.
• It protects a GitHub App private key in Vault’s storage and performs the GitHub App installation authentication/token-minting flow on behalf of Vault clients.
a. Client (User / CI / Vault CLI / API consumer)
b. Vault Core Server
c. Vault Storage Backend (e.g. Consul, Raft, etc.)
d. Plugin Process (vault-plugin-secrets-github)
• Subcomponents:
• Config Manager (handles /config)
• PermissionSet Manager (handles /permissionset)
• Token Engine (handles /token)
• Revocation Handler (handles lease revocation)
• Metrics Exporter (/metrics)
• Internal Modules (reflecting code in github/*.go): path parsing, API client, JWT builder, GitHub HTTP client
e. External GitHub API
f. Observability System (e.g. Prometheus & Dashboard)
Relationships and data flows
1. Authentication flow
• Client → Vault Core: POST /v1/auth/... → Vault Core Auth Backends → Vault Core → Client OK
2. Token request flow
a. Client → Vault Core: POST /v1/github/token (or GET/PUT)
b. Vault Core → Plugin Process via Vault RPC protocol (gRPC over stdio)
c. Plugin → Vault Storage Backend via RPC: read config (app_id, prv_key, optional base_url, etc.)
d. Plugin → Plugin subcomponent: mint JWT using stored private key
e. Plugin → GitHub API: POST /app/installations/{id}/access_tokens with JWT
f. GitHub API → Plugin: returns installation token + metadata
g. Plugin → Vault Core: return token response, record lease, metrics, logs
h. Vault Core → Client: JSON payload with token, expire_time, repositories or filtered names
3. Revocation & lease lookup
• Client or Vault Core (sys/leases) → Plugin: revoke token via GitHub DELETE /installation/token
4. Metrics & Info
• Observability (Prometheus) → Vault Core (or directly the plugin if exposed) → scrape /metrics
• Client/Operators GET /v1/github/metrics or /v1/github/info
Architectural patterns and principles
• Plugin-based extension: Vault Core delegates certain secret paths to an external process over a defined RPC protocol.
• Secrets engine pattern: mount‐time isolation by path, lease management, policy enforcement.
• Configuration as data: plugin uses durable storage, no in-process files except private key stored in Vault.
• High cohesion: each module in github/*.go has one responsibility (config, client, paths, JWT, revocation).
Technologies and frameworks
• Go 1.22+ (modules go.mod, go.sum, package github/…)
• Vault plugin RPC protocol (gRPC over stdio)
• GitHub REST API v3 (JWT & installation token endpoints)
• Prometheus/OpenMetrics (/metrics)
• Nix + direnv for development environment
• goreleaser for cross-compilation
• Unit & integration tests (stubbed GitHub API, local Vault instance)
• Use clear labels: e.g. “Vault Core”, “vault-plugin-secrets-github”, “GitHub API”, “Consul/Raft Storage”, “Prometheus”.
• Client → Vault Core (/auth, /github/token)
• Vault Core → Plugin (gRPC RPC)
• Plugin → Storage (read config)
• Plugin → GitHub (HTTPS POST)
• GitHub → Plugin (token response)
• Plugin → Vault Core (return)
• Prometheus → Plugin (/metrics)
• Blue rectangles for Vault Core & Storage
• Green for Plugin and submodules
• Orange for external GitHub API
• Purple cloud for observability
• Cloud for external services