Trust Templates -- Treeship -- Treeship

A trust template is a pre-built .treeship/config.yaml for a specific workflow. It answers three questions: what triggers an attestation, what gets captured in each receipt, and how the chain gets structured.

treeship init --template github-contributor

From that point, Treeship runs silently. The right things get attested at the right moments.

Available templates

All seven templates ship inside the CLI binary. No network access required.

Template	What it does
`github-contributor`	Commit and test provenance for OSS contributors. Proves tests passed before commit and lockfile was untouched.
`ci-cd-pipeline`	Software delivery chain -- test, build, deploy -- with approval gates on deploys.
`research-agent`	Multi-step research with source provenance.
`mcp-agent`	One import change, every MCP tool call receipted via `@treeship/mcp`.
`claude-code-session`	Full audit trail of AI coding sessions.
`openclaw-agent`	OpenClaw workflow attestation.
`hermes-agent`	Hermes Agent autonomous workflow attestation.

Template commands

Command	What it does
`treeship templates`	List all available templates grouped by category
`treeship template preview <name>`	Preview what a template does without applying it
`treeship template apply <name>`	Apply a template to the current project
`treeship template validate <file>`	Validate a custom template YAML file
`treeship template save --name <name>`	Save the current config as a reusable template
`treeship init --template <name>`	Initialize a new project with a template

Preview before applying

treeship template preview ci-cd-pipeline

This prints the triggers, watched paths, capture settings, approval requirements, and Hub push behavior without writing any files.

Apply to an existing project

treeship template apply github-contributor

This writes .treeship/config.yaml in the current directory, converting the template into a project config.

Validate a custom template

treeship template validate my-template.yaml

Runs a series of checks: valid YAML, required fields present (name, description, session.actor), version >= 1, and successful conversion to a ProjectConfig.

Build your own

Answer four questions

What are the meaningful moments? Not what Treeship does, what happens in the workflow.
What proves each moment happened? Output digest, file changes, git state, approval.
Which moments need human approval? Deployments, payments, publications.
Does any moment need ZK TLS? Only if the verifier does not trust the agent AND the server response is legally significant.

Write the YAML

name: my-workflow
version: 1
description: >
  What this workflow does.
tags: [development]
audience: [developer]

session:
  actor: agent://my-agent
  auto_start: true
  auto_checkpoint: false
  auto_push: false

attest:
  commands:
    - pattern: "npm test*"
      label: test suite
      capture_output_digest: true
    - pattern: "git push*"
      label: code push
    - pattern: "kubectl apply*"
      label: deploy
      require_approval: true

  paths:
    - path: "src/**"
      on: write
      label: source change
      alert: false

capture:
  output_digest: true
  file_changes: true
  git_state: true
  lockfile_changes: false
  environment: false
  model_metadata: false

approvals:
  require_for:
    - label: deploy

hub:
  auto_push: true
  push_on: [session_close]
  endpoint: https://api.treeship.dev

onboarding: |
  Your workflow is configured.
  Run normally. Everything matching the rules gets attested.

Apply and test

# Apply from a file path
treeship init --template ./my-workflow.yaml

# Or validate first
treeship template validate my-workflow.yaml

# Test it
treeship wrap -- echo "test"
treeship verify last --full

Save from a live config

If you have been using Treeship, save your current config as a reusable template:

treeship template save --name my-workflow

This strips project-specific fields (ship ID, hub credentials, workspace ID) and writes a clean reusable YAML to ~/.treeship/templates/my-workflow.yaml.

Templates are plain YAML files. Share them however you want:

# Via git
git add .treeship/templates/my-template.yaml

# Via file path
treeship init --template ./template.yaml

YAML schema reference

The full template YAML schema accepted by the CLI:

Top-level fields

Field	Type	Required	Description
`name`	string	yes	Template slug (e.g., `my-workflow`)
`version`	integer	recommended	Schema version, should be >= 1
`description`	string	yes	What this template does
`tags`	string[]	no	Categorization tags (e.g., `[development, ci]`)
`audience`	string[]	no	Who this template is for (e.g., `[developer, devops]`)
`session`	object	yes	Session configuration
`attest`	object	yes	What triggers attestation
`capture`	object	no	What data to capture in each receipt
`approvals`	object	no	Which labels require human approval
`hub`	object	no	Hub push behavior
`onboarding`	string	no	Message shown after `treeship init --template`

session

Field	Type	Default	Description
`actor`	string	`agent://default`	Default actor URI for all artifacts
`auto_start`	bool	false	Start session when matching activity begins
`auto_checkpoint`	bool	false	Automatically create Merkle checkpoints
`auto_push`	bool	false	Push to Hub after session closes

attest.commands[]

Field	Type	Default	Description
`pattern`	string	required	Shell glob to match commands (e.g., `npm test*`)
`label`	string	required	Human-readable label for receipts
`require_approval`	bool	false	Block until `treeship approve`
`capture_output_digest`	bool	false	Hash stdout+stderr for this command

attest.paths[]

Field	Type	Default	Description
`path`	string	required	File glob to watch (e.g., `src/**`)
`on`	string	required	Trigger on: write, change, create, delete
`label`	string	none	Human-readable label for the attestation
`alert`	bool	false	Raise an alert when triggered

capture

Field	Type	Default	Description
`output_digest`	bool	false	Hash stdout+stderr
`file_changes`	bool	false	Track modified files with content hashes
`git_state`	bool	false	Git HEAD before/after each command
`lockfile_changes`	bool	false	Detect lockfile modifications
`environment`	bool	false	OS and runtime version fingerprint
`model_metadata`	bool	false	Capture AI model info (name, provider)

approvals

Field	Type	Description
`require_for`	object[]	List of `{ label: "..." }` entries matching command labels that need approval

hub

Field	Type	Default	Description
`auto_push`	bool	false	Push artifacts to Hub automatically
`push_on`	string[]	[]	When to push: `session_close`, `approval_required`, `git_push`
`endpoint`	string	none	Custom Hub endpoint URL

Templates configure what gets attested. They do not alter how your tools run or add dependencies to your project.

Trust Templates

On this page