Slack integration

Slack is part of the launch path for early partners:

• start a workflow from a message, mention, slash command, or seeded equivalent;
• notify the team when a run needs attention or completes;
• reply in the source thread when a live Slack-triggered run has a source timestamp;
• link back to the Viewport run detail;
• record the Slack delivery as a receipt.

The Viewport run detail remains the source of truth for approvals, artifacts, provider actions, usage, and audit.

Set Up

1. Open Settings -> Integrations -> Slack.
2. Connect the workspace.
3. Pick the channel used for the first workflow.
4. Trigger a small test workflow before connecting production channels.

Use a channel where the operator can see the trigger and completion receipt during the first proof.

First-Route Walkthrough

Use one controlled channel first. Do not start with multiple support channels or private production channels.

1. Invite the Viewport Slack app or bot to the launch channel.
2. Create or sync one .viewport/routes/*.yaml route with integration: slack and the channel condition for that launch channel.
3. Keep .viewport/policy.yaml on the launch-safe path: plan gate, human approval, bounded branch publish, and Slack notification.
4. Run vpd check . before pushing the route.
5. Push .viewport/ and wait for GitOps sync to show the new SHA.
6. Start the paired worker with the app-generated command.
7. Post one real source message in the launch channel.
8. Approve the plan gate in Viewport.
9. Confirm the completion message appears in the source thread.
10. Open run detail and verify the Slack provider receipt.

Minimum launch route shape:

name: slack-support
route:
  integration: slack
  event: app_mention
  conditions:
    channel: C0123456789
    mentionsAny: ["viewport"]
target:
  policy: ../policy.yaml

Use the channel id, not the visible channel name. If the route starts from a fixture or replay without a source timestamp, a fallback channel post is acceptable for that fixture only. It does not prove live source-thread delivery.

What To Verify In Run Detail

After the first Slack-backed run, the run should show:

• source provider slack;
• source channel id and event timestamp;
• matched route file and Git SHA;
• plan gate and human approval;
• worker claim and cleanup receipt;
• Slack completion receipt with provider permalink;
• source thread timestamp when a source message existed;
• GitHub PR or provider proposal receipt if the workflow opened one.

If the Slack message appears but run detail has no provider receipt, treat that as incomplete proof. If run detail has a receipt but Slack has no visible message, follow Provider receipts are missing.

Message Quality

Slack messages should be readable summaries:

Viewport completed the support run.
GitHub PR -> PR #44
Audit packet -> Open audit packet
Run -> Open run

If you see literal \n in a message, that is a renderer bug. The provider payload should contain real line breaks before it reaches Slack.

Threads

When the workflow has a source Slack message, completion notifications should prefer the source thread when that target is available. Some fixture or seeded demo runs may post directly to the configured channel because there is no real source thread to reply to. Treat an unexpected channel post during a live Slack-triggered run as a regression and capture the run id plus Slack timestamp.

Do not generalize one route proof to every channel. Each launch route should be verified with its own source message, completion permalink, and run receipt.

Approvals

For the launch path, review and approval should happen in Viewport. Slack cards can route users to the run detail, but do not rely on Slack-only approval until the workspace has explicitly enabled and tested that behavior.

Troubleshooting

Do not paste Slack bot tokens into support notes.