Provider integrations

Provider integrations turn outside events and approved side effects into workflow receipts. They are not a reason to hand raw organization credentials to an agent process.

Integration Status

For the first run, keep the provider set narrow: one repository, one Slack channel, one worker, one policy. Expand after the team can see a complete run detail page with approvals, receipts, and audit entries.

Slack

Connect Slack from Settings -> Integrations -> Slack. Pick a default channel for workflow notifications or configure a workflow-specific channel.

Slack messages should be treated as summaries. The run detail in Viewport is the source of truth for approvals, receipts, artifacts, and audit.

For Slack-triggered routes, keep the first launch channel narrow and verify one source-thread completion before broadening to more channels.

GitHub

Install the Viewport GitHub App only on the repos the workflow may touch. For a first run, use a sandbox or team-owned repository.

Recommended first grant:

• read repository metadata/code for the selected repo;
• create a branch;
• open a pull request;
• comment on the pull request.

Do not start by allowing direct pushes to protected branches, merges, or repo admin operations.

First-Repo Walkthrough

Use one repository first. The goal is to prove checkout, bounded branch publish, PR creation, and receipt capture without broad org access.

1. Install the Viewport GitHub App on one sandbox or low-risk team repository.

2. Commit .viewport/policy.yaml and one route file in that repository.

3. Keep the policy branch boundary narrow:

   repos:
     - repo: acme/sandbox
       access: read-write
       credential: brokered
       branches:
         push_allowed: ["agent/**"]
         restricted: ["main", "release/**"]

4. Run vpd check . from the repository root.

5. Push the .viewport/ commit and confirm GitOps sync shows the new SHA.

6. Start the paired worker and trigger one small route.

7. Approve the plan gate in Viewport.

8. Confirm the worker publishes an agent/** branch.

9. Confirm GitHub shows a PR from that branch.

10. Confirm run detail shows the GitHub provider receipt with PR URL.

For a GitHub-triggered first proof, use a minimal route like:

route:
  name: github-pr-review
  team: platform
  trigger:
    integration: github
    events: ["pull_request.*"]
    conditions:
      repo: acme/sandbox
  policy:
    source: git
    repo: acme/sandbox
    ref: main
    path: .viewport/policy.yaml

For a Slack-triggered first proof that opens a GitHub PR, the Slack route can still use the same GitHub repo policy and branch boundary. The trigger provider does not change the GitHub side-effect evidence requirement.

GitHub Evidence Checklist

After the first GitHub-backed run, run detail should show:

• repository slug and synced Git SHA for the policy;
• brokered checkout or repo preparation receipt;
• branch name under the allowed pattern;
• implementation/test node result;
• GitHub PR number and URL;
• provider receipt id/status;
• credential or integration label, not a raw GitHub token;
• failure copy if checkout, branch publish, or PR creation failed.

GitHub itself should show:

• PR source branch matching the allowed pattern;
• target branch that is not directly pushed by the worker;
• Viewport-authored PR body or comment linking back to run evidence;
• no unexpected write to protected branches.

If GitHub has a PR but Viewport has no provider receipt, the run evidence is incomplete. If Viewport has a failed receipt and GitHub has no PR, use the receipt failure copy before changing app permissions.

Worker Credentials

Self-hosted workers may hold local model keys, package registry tokens, and repo checkout credentials. Keep them local unless a workflow explicitly requires a brokered provider action.

The worker can claim work and report evidence. Provider writes still require the server-issued workflow authority, approval state, and named provider grant.

Linear And Other Sources

Linear/Jira/webhook events should be introduced after the first Slack/GitHub proof. Before enabling live intake:

1. verify webhook signing;
2. dry-run route matching;
3. confirm the active team owns the workflow;
4. confirm denial behavior for unmatched or unauthorized events.

Proving A New Provider

A provider becomes live-proven for a workspace only when one small run shows:

1. the integration can authenticate without engineer intervention;
2. route or trigger delivery reaches Viewport;
3. the worker can claim and execute the governed run;
4. the side effect is approved or explicitly allowed by policy;
5. the external object URL or provider reference is stored as a receipt;
6. failure copy is understandable when the provider denies the action.

Record the run id, provider receipt id, external URL/permalink, and any scoped credential ref. Do not record raw access tokens.

Support Checklist

When an integration fails, collect:

• workspace id and team id;
• workflow id and run id;
• provider connection name;
• runner name;
• denial code or receipt id;
• sanitized vpd worker doctor --json.

Do not share raw provider tokens, worker private keys, pairing codes, bootstrap tokens, or lease tokens.