Automations, routes, and policies

An Automation is the customer-facing unit in Viewport. It is the complete path from trigger to route to policy to governed agent run.

Every automation has two core subsets:

• Routes decide which team owns an event.
• Policies decide what that team's agents may do.

The compiled workflow graph is an execution artifact. Most teams should build and review Automations, not start by editing nodes.

The Runtime Flow

provider event
  -> route match
  -> git-backed policy
  -> composed run
  -> paired vpd worker
  -> plan gate
  -> implementation
  -> provider receipts

The route is the subscription. The policy is the contract. The automation is the product surface that keeps both understandable.

Where Files Live

For early partners, use the ArgoCD-style hybrid layout:

acme/viewport-config/
  routes/
    backend-jira-to-pr.yaml
    backend-slack-support.yaml

acme/backend/
  .viewport/
    policy.yaml
    context/
      runbook.md

Routes usually live in a central config repo because routes claim shared event space. Policies live with the code they govern because application teams should review repo/context/gate changes through normal pull requests.

Small teams can keep routes and policy in one repo:

acme/sandbox/
  .viewport/
    policy.yaml
    routes/
      slack-support.yaml

Route Responsibilities

A route answers:

• Which integration sends the event?
• Which event types matter?
• Which conditions narrow ownership?
• Which policy should handle the event?
• Should overlaps be rejected or explicitly fan out?

Example:

route:
  name: backend-slack-support
  team: backend
  trigger:
    integration: slack
    events: ["app_mention"]
    conditions:
      channel: C1234567890
      mentionsAny:
        - viewport
  policy:
    source: git
    repo: acme/backend
    ref: main
    path: .viewport/policy.yaml
  priority: 30

Routes should be specific enough that two teams do not accidentally claim the same event. When multi-team ownership is intentional, use explicit fan-out instead of relying on ambiguous overlap.

Policy Responsibilities

A policy answers:

• Which repos can agents read or write?
• Which branches or paths are restricted?
• Which context should agents use?
• Which gates require humans?
• Which agent and notification target should run by default?

Example:

version: 1
repos:
  - repo: acme/backend
    access: read-write
    credential: brokered
    branches:
      push_allowed: ["agent/**"]
      restricted: ["main"]
context:
  sources:
    - name: backend-runbook
      path: .viewport/context/runbook.md
invoke:
  agent: claude-code
  role: Draft a plan, wait for review, then implement on an agent branch.
gates:
  - name: plan-review
    type: plan
    reviewers:
      tags: ["tech-lead"]
    timeout: 4h
    on_timeout: escalate

What The Worker Executes

The worker does not decide the workflow. Viewport composes a concrete run from the matched route and policy, then issues a claim to the worker.

For the launch path, the composed shape is:

context -> checkout -> plan agent -> human gate -> implementation agent
  -> publish branch -> open PR -> notify -> cleanup

Plan gates run before write work continues. Requesting changes sends the plan back through a plan-mode revision path. Implementation does not proceed until the gate is approved.

Customer Checklist

1. Connect GitHub and Slack/Jira/Linear.
2. Create a team and reviewer tags.
3. Open Automations in Viewport.
4. Define or generate .viewport/policy.yaml.
5. Commit a route pointing to that policy.
6. Check GitOps sync health in Viewport.
7. Pair a vpd worker.
8. Send a real event.
9. Approve the plan gate.
10. Verify the PR and run receipts.

See Self-serve first run for the full launch walkthrough.