Skip to content

docs.md

Latest commit

 

History

History
141 lines (108 loc) · 3.86 KB

docs.md

File metadata and controls

141 lines (108 loc) · 3.86 KB
Raw
name secrets
description Declarative secret retrieval from multiple backends.
author konoss
tags
secrets
phase
vaultwarden
declarative
image ghcr.io/kontangooss/schmutz-plugin-secrets

secrets

Declarative secret retrieval plugin for Woodpecker CI. Define what secrets you need and which provider holds them — the plugin handles authentication and returns standard KEY=VALUE pairs regardless of the backend.

Supported providers:

  • phase — Phase Secrets Manager (HTTP API)
  • vaultwarden — Vaultwarden/Bitwarden (CLI)
  • env — Environment variable passthrough (for testing or pre-injected secrets)

Settings

Required

Setting Description
action The action to perform: fetch, list, validate
provider Secret backend: phase, vaultwarden, env
private_key Authentication key/token for the provider
objects Comma-separated list of secret keys to retrieve

Optional

Setting Default Description
provider_url — Provider API URL (required for vaultwarden)
app — App name (phase) or collection name (vaultwarden)
env Production Environment name (phase)
path / Secret path prefix (phase)
bw_email admin@example.com Login email (vaultwarden)
output_file .secrets.env Output file path
format env Output format
fail_on_missing true Fail if any requested secret is missing
skip_verify false Skip TLS verification
debug false Enable debug logging

Actions

fetch

Retrieves the requested secrets and writes them to the output file as KEY=VALUE pairs. Only the keys listed in objects are written — the provider may hold more secrets, but only the declared ones are extracted.

Outputs: SECRETS_FOUND, SECRETS_MISSING, SECRETS_FILE

list

Lists all available secret keys from the provider. Prints keys only, never values. Useful for discovery and debugging.

Outputs: SECRETS_AVAILABLE

validate

Checks that all requested secrets exist in the provider without writing them to disk. Returns exit code 1 if any are missing.

Outputs: VALIDATE_PASS, VALIDATE_FAIL

Pipeline Examples

Fetch secrets from Phase

steps:
  secrets:
    image: ghcr.io/kontangooss/schmutz-plugin-secrets
    settings:
      action: fetch
      provider: phase
      private_key:
        from_secret: phase_service_token
      objects: DB_PASSWORD,JWT_SECRET,ADMIN_PASSWORD
      app: master
      path: /myapp/

Fetch secrets from Vaultwarden

steps:
  secrets:
    image: ghcr.io/kontangooss/schmutz-plugin-secrets
    settings:
      action: fetch
      provider: vaultwarden
      private_key:
        from_secret: bw_master_password
      provider_url: http://vaultwarden.example.com:8080
      app: apps/myapp
      objects: DB_PASSWORD,API_KEY

Validate before deploy

steps:
  check-secrets:
    image: ghcr.io/kontangooss/schmutz-plugin-secrets
    settings:
      action: validate
      provider: phase
      private_key:
        from_secret: phase_service_token
      objects: DB_PASSWORD,JWT_SECRET,SMTP_PASSWORD
      app: master
      path: /myapp/

  deploy:
    image: alpine
    depends_on: [check-secrets]
    commands:
      - echo "All secrets verified, deploying..."

Use with env passthrough (testing)

steps:
  secrets:
    image: ghcr.io/kontangooss/schmutz-plugin-secrets
    settings:
      action: fetch
      provider: env
      private_key: unused
      objects: CI_COMMIT_SHA,CI_REPO_NAME

Outputs

All actions write outputs to:

  • .secrets.env — Fetched secrets as KEY=VALUE (chmod 600)
  • .env — Plugin metadata (SECRETS_FOUND, SECRETS_MISSING, etc.)

Downstream steps can source .secrets.env to use the retrieved secrets.