82 lines
2.7 KiB
Markdown
82 lines
2.7 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```toml
|
||
|
|
# 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
|
||
|
|
|
||
|
|
1. **Required fields**: `id`, `formula`, `context`, and `secrets` must be present
|
||
|
|
2. **Formula validation**: The formula must exist in the `formulas/` directory
|
||
|
|
3. **Secret validation**: All secrets in the `secrets` array must be in the allowlist
|
||
|
|
4. **No unknown fields**: The TOML must not contain fields outside the schema
|
||
|
|
5. **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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./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
|