Outbound integrations

Overview

Integrations connect Vigilo to the rest of your tool chain — chat (Slack, Microsoft Teams), issue trackers (Jira, Linear), incident response (PagerDuty), source control (GitHub), and a growing catalogue of others.

Where to find them. Integrations live under Settings → Infrastructure → Integrations (/ws/{slug}/settings/integrations). The old top-level Integrations entry in the main sidebar has been retired — it was a workspace-configuration surface, not a day-to-day destination, so it lives next to Cloud accounts under Settings now. Existing deep links to /ws/{slug}/integrations still work; they redirect to the Settings location automatically.

Each integration is configured per workspace, stores its credentials encrypted via the platform CMEK, and supports both outbound notifications ("a change moved to scheduled, post in #changes") and where supported, bidirectional sync ("PagerDuty incident.resolved → close the linked INC in Vigilo").

This article covers the supported integrations, the shared configuration model, the security story, and the bidirectional sync surfaces. For outbound webhooks more broadly see Webhooks.

Why it exists

Operators live in chat and ticketing, not in a single web app. If Vigilo cannot push the right notification to the right Slack channel and accept "I'll take it" reaction-acks back, it becomes another tab that nobody opens. Each integration codifies one well-known relationship between Vigilo and a target system so the connection is configured once by an admin and used everywhere by every member.

Key concepts

Integration model

Each integration is backed by an IntegrationConfig row (workspace, kind, display_name, config JSONB, is_active, created_at). kind is the well-known enum:

slack — bot token, default channel, signing secret.
jira — base URL, project key, basic-auth or OAuth credentials.
linear — workspace ID, OAuth token, default team.
pagerduty — integration key (Events V2), service ID, escalation policy.
github — installation ID, repo allowlist, webhook secret.
teams — incoming-webhook URL or bot credentials.

Where the integration supports both push and pull, the same row stores both sets of credentials.

Signing secrets — encryption

Every signing secret, OAuth token, basic-auth password, and bot token is stored encrypted at rest via the platform CMEK (Customer-Managed Encryption Key) descriptor (F2). The plaintext value never reaches the database — encryption happens in the app layer at write time, decryption in the API layer at use time. The UI shows the secret as •••• after save, with a Rotate button to issue a new value.

CMEK descriptors are per-tenant; rotating the descriptor re-encrypts all secrets in the workspace via a backgrounded Celery task that surfaces progress under Settings → Security → CMEK.

Bidirectional sync

Most integrations are outbound-only (Vigilo posts a webhook). Three integrations support bidirectional sync:

Jira (WB.6)

Outbound — every change status transition posts to the Jira issue (if linked), keeping the Jira status mirror in sync.
Inbound — Jira's issue_updated webhook lands on /ws/{slug}/integrations/jira/webhook/ (HMAC-verified against the stored signing secret), and the matching change request's status is mirrored back. The mirror is governed by a status-map under Settings → Integrations → Jira → Status map.

PagerDuty (WB.7)

Outbound — opening an incident with severity >= sev2 triggers a PagerDuty event via the V2 Events API.
Inbound — PagerDuty's incident.resolved webhook lands on /ws/{slug}/integrations/pagerduty/webhook/, and the linked Vigilo incident is auto-closed with the PagerDuty resolution notes appended to the timeline. Auto-close is governed by Workspace.settings.pagerduty_auto_close (default true).

Linear (WB.8)

Outbound — change requests linked to a Linear cycle ID post status updates to the cycle's Linear issue.
Inbound — Linear's webhook ingests cycle completion events and triggers a Vigilo "cycle complete" runbook, including an option to import the cycle's issues as Vigilo tasks.

Slack — channel-per-incident (WA.16)

When an incident is opened, the Slack integration (if configured with the channels:manage scope) automatically creates a dedicated channel named inc-{number}-{slug} (e.g. inc-104-auth-502s), invites the on-call group and the incident commander, and posts a structured opening message with deep links back to the Vigilo incident.

The channel becomes the incident's chat archive. On incident close, the channel is renamed inc-{number}-{slug}-closed, the topic updated to the resolution, and the channel optionally archived after a grace period.

Slack reaction-ack (WD.7)

A first responder can acknowledge an incident from Slack by reacting to the opening message with the eyes emoji (:eyes:). The Vigilo Slack bot subscribes to reaction_added events on the incident-channel, maps the reacting user to a WorkspaceMembership (via slack_user_id → UserProfile link), and writes the ack to the incident timeline as IncidentTimelineEvent(kind='acknowledged', actor=user). No more "click the link in Slack, log into the web app, then click Acknowledge."

GitHub

The GitHub integration links a Vigilo change to one or more PRs. Outbound: PR merge fires the change's complete() transition (when configured). Inbound: GitHub webhook delivers pull_request.closed to /ws/{slug}/integrations/github/webhook/, and the linked change's completed_at is set.

Microsoft Teams

Teams integration is push-only today via incoming webhook URL. The same outbound notification surface as Slack — change events, incident events, approvals — is posted to the configured channel. Reaction-ack and channel-per-incident are Slack-only (Teams API limitations).

Common workflows

Connect Slack

Settings → Integrations → Slack → Connect. The flow launches Slack's OAuth.
Approve the scopes (chat:write, channels:manage, reactions:read, commands).
Pick a default channel for non-incident posts (e.g. #changes).
Save. Slack messages start flowing immediately.

Connect PagerDuty

Settings → Integrations → PagerDuty → Connect, paste your Events V2 integration key.
Pick the default service ID and escalation policy.
Save. The first sev-2+ incident triggers a PagerDuty event.

Configure Jira bidirectional sync

Settings → Integrations → Jira → Connect, supply base URL and credentials.
Status map — map Vigilo statuses (draft/review/scheduled/in_progress/completed) to Jira statuses (To Do/In Review/Ready/In Progress/Done).
Set the Jira webhook URL in Jira's automation settings to https://{your-host}/ws/{slug}/integrations/jira/webhook/ with the signing secret from the Vigilo config row.
Save. Bidirectional sync is live.

Rotate a signing secret

Open the integration config, click Rotate secret.
The new secret is shown once; copy it to the target system. Old secret remains valid for a 24-hour overlap window.
After 24 hours, the old secret is purged from the encrypted blob.

Permissions

Owners can connect, disconnect, and rotate any integration.
Admins can connect and configure integrations; rotation requires owner.
Engineers / approvers / viewers can see which integrations are active but not their credentials.

Troubleshooting

Slack auto-channel not created — The bot user does not have channels:manage. Re-run the OAuth with the missing scope.

Jira inbound updates not applying — The webhook signature is failing. Check the Jira webhook log; the secret in the Vigilo config must match the secret in Jira's automation. Use the Test signature button.

PagerDuty resolution not closing the Vigilo incident — Either the incident is not linked (no pagerduty_incident_id on the Vigilo row) or Workspace.settings.pagerduty_auto_close is false. Check both.

Reaction-ack not registering — The reacting user has no slack_user_id mapped on their UserProfile. They must run /vigilo link in any channel where the Vigilo bot is present, or admins can map manually.

Linear cycle import duplicates tasks — The import dedupes by Linear issue ID. If you imported once already and re-import, only new issues are added. If you need a full re-import, delete the existing tasks first.

CMEK rotation stuck mid-progress — The backgrounded re-encryption may have failed on one secret. Check Flower for the re_encrypt_secrets task; the task is idempotent and can be retried.