Agent af8b675b36

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

fix: feat: define vault action TOML schema for PR-based approval (#74 )

- Add vault/SCHEMA.md documenting the TOML schema for vault actions
- Add validate_vault_action() function to vault/vault-env.sh that:
  - Validates required fields (id, formula, context, secrets)
  - Validates secret names against allowlist
  - Rejects unknown fields
  - Validates formula exists in formulas/
- Create vault/validate.sh script for CLI validation
- Add example TOML files in vault/examples/:
  - webhook-call.toml: Example calling external webhook
  - promote.toml: Example promoting build/artifact
  - publish.toml: Example publishing to ClawHub

2026-03-31 20:58:51 +00:00

2.7 KiB

Raw Blame History

Vault Action TOML Schema

This document defines the schema for vault action TOML files used in the PR-based approval workflow (issue #74).

File Location

Vault actions are stored in vault/actions/<action-id>.toml on the ops repo.

Schema Definition

# Required
id = "publish-skill-20260331"
formula = "clawhub-publish"
context = "SKILL.md bumped to 0.3.0"

# Required secrets to inject
secrets = ["CLAWHUB_TOKEN"]

# Optional
model = "sonnet"
tools = ["clawhub"]
timeout_minutes = 30

Field Specifications

Required Fields

Field	Type	Description
`id`	string	Unique identifier for the vault action. Format: `<action-type>-<date>` (e.g., `publish-skill-20260331`)
`formula`	string	Formula name from `formulas/` directory that defines the operational task to execute
`context`	string	Human-readable explanation of why this action is needed. Used in PR description
`secrets`	array of strings	List of secret names to inject into the execution environment. Only these secrets are passed to the container

Optional Fields

Field	Type	Default	Description
`model`	string	`sonnet`	Override the default Claude model for this action
`tools`	array of strings	`[]`	MCP tools to enable during execution
`timeout_minutes`	integer	`60`	Maximum execution time in minutes

Secret Names

Secret names must be defined in .env.vault.enc on the ops repo. The vault validates that requested secrets exist in the allowlist before execution.

Common secret names:

CLAWHUB_TOKEN - Token for ClawHub skill publishing
GITHUB_TOKEN - GitHub API token for repository operations
DEPLOY_KEY - Infrastructure deployment key

Validation Rules

Required fields: id, formula, context, and secrets must be present
Formula validation: The formula must exist in the formulas/ directory
Secret validation: All secrets in the secrets array must be in the allowlist
No unknown fields: The TOML must not contain fields outside the schema
ID uniqueness: The id must be unique across all vault actions

Example Files

See vault/examples/ for complete examples:

webhook-call.toml - Example of calling an external webhook
promote.toml - Example of promoting a build/artifact
publish.toml - Example of publishing a skill to ClawHub

Usage

Validate a vault action file:

./vault/validate.sh vault/actions/<action-id>.toml

The validator will check:

All required fields are present
Secret names are in the allowlist
No unknown fields are present
Formula exists in the formulas directory

2.7 KiB Raw Blame History