Policy YAML

Policy fields

Match rules

A policy applies when all specified criteria match. At least one criterion is required. Multiple criteria are combined with AND.

Inject

The inject object has two optional arrays: before and after. Steps in before run before the repo’s own steps. Steps in after run after. Both use the same step schema as .gittan.yaml steps.

inject:
  before:
    - name: security-scan
      use: trivy-scan
  after:
    - name: notify-deploy
      image: curlimages/curl:8.11.1
      run: curl -X POST $DEPLOY_WEBHOOK

If multiple policies match the same repo, all contribute steps. First occurrence of a step name wins — enforce policy steps are placed first and take precedence.

Modes

default

The policy provides fallback steps for repos that don’t define their own pipeline. If a repo has a .gittan.yaml with steps, the default policy’s steps are replaced by the repo’s own steps.

Use for: standard build and test pipelines that most repos should have out of the box.

enforce

The policy always contributes its steps, even when the repo has its own .gittan.yaml. Individual repos cannot override or skip enforce policy steps.

Use for: org-wide security scanning, compliance checks, mandatory review gates.

Resolution order

The final pipeline for a push is the union of steps from all matching policies, resolved in this order:

1. Enforce policies — always contribute when matched. These are org guardrails.
2. Platform policies — built-in scanning steps. secret-scan and dep-scan (CRITICAL) block the push; policy-scan is advisory.
3. Base steps — either the repo’s .gittan.yaml steps (if present), or matching default policy steps.

A .gittan.yaml that contains only metadata (depends, links, notify — no steps) does not count as an override. Default policy steps still apply.

Platform policies

Three built-in policies run on every matching push. Each has its own blocking behavior:

Team templates

Teams can define step templates that repos reference by name. Templates provide default values that repos can override per-step.

Examples

Enforce: mandatory security scanning

name: mandatory-security
description: Run secret and CVE scanning on all pushes
mode: enforce
match:
  files:
    - package.json
    - Dockerfile
inject:
  before:
    - name: secret-scan
      use: gitleaks-scan
    - name: dep-scan
      use: trivy-scan

This policy runs on every push to any repo containing a package.json or Dockerfile. Because the mode is enforce, repos cannot skip these steps — even with their own .gittan.yaml.

Default: standard Node.js build

name: node-standard
description: Default build and test for Node.js repos
mode: default
match:
  files:
    - package.json
inject:
  before:
    - name: install
      run: npm ci
    - name: lint
      run: npm run lint
      needs:
        - install
    - name: test
      run: npm test
      needs:
        - install
    - name: build
      run: npm run build
      needs:
        - lint
        - test

This policy provides a standard pipeline for Node.js repos that don’t define their own. Any repo that adds a .gittan.yaml with steps replaces these defaults entirely.

Team-scoped policy

name: api-team-review
description: Require review for API team repos
mode: enforce
match:
  team: api-team
inject:
  before:
    - name: review
      require: 2
      from: writers

Applies only to repos in the api-team. Requires two approvals before the push lands.