Integration and API Spec

Integration and API Spec

Software Deployment Workflow

Used by Agent 1 (webhook trigger and CI check query) and Agent 2 (workflow dispatch trigger). A GitHub App is preferred over a PAT for production because it provides scoped installation tokens that expire and can be rotated without tying access to an individual user account.

// Inbound webhook payload (truncated)
{
  "action": "closed",
  "pull_request": {
    "merged": true,
    "merge_commit_sha": "<sha>",
    "base": { "ref": "main" },
    "head": { "ref": "feature/DEPLOY-42" },
    "user": { "login": "priya-nair" }
  },
  "repository": { "full_name": "yourcompany/app" }
}
// Output to Agent 1 context
{ commit_sha, pr_number, pr_author, repo_full_name, target_branch }

Used by Agent 1 (ticket creation) and Agent 3 (status update and timestamp write-back). The Jira project key and deployment issue type ID must be stored in the credential store. No hardcoded values in workflow node fields.

// Ticket creation request body (ADF description, truncated)
{
  "fields": {
    "project": { "key": "{{JIRA_PROJECT_KEY}}" },
    "summary": "Deploy: {{repo_name}} v{{version}} -> {{environment}}",
    "issuetype": { "id": "{{JIRA_ISSUE_TYPE_ID}}" },
    "labels": ["deployment", "automated"],
    "description": { "type": "doc", "version": 1, "content": [...] }
  }
}
// Output: jira_ticket_key (e.g. DEPLOY-142) passed to Agent 1 Slack message and Agent 3

Used by all three agents. Agent 1 sends an interactive Block Kit approval message. Agent 2 listens for the button callback on the interactivity request URL. Agent 3 posts the deployment result to the team channel. A single Slack App with a Bot Token serves all three agents.

// Inbound interactive callback payload (key fields)
{
  "type": "block_actions",
  "user": { "id": "U012AB3CD", "name": "marcus.reid" },
  "actions": [{
    "action_id": "deploy_approve",
    "value": "approve::DEPLOY-142::run-789"
  }],
  "message": { "ts": "1718000000.000100" }
}
// Output parsed by Agent 2
{ decision: "approve", jira_ticket_key: "DEPLOY-142", deploy_run_id: "run-789", approved_by: "marcus.reid", approved_at: <timestamp> }

Used by Agent 2 only. The Environment and Deploy Agent reads a structured config table from a known Confluence page to obtain environment variables for the target deployment environment. The page ID must be stored in the credential store. If config is not in a single structured table, a mapping exercise is required before build.

// API response (storage format excerpt)
<table><tr><th>variable_name</th><th>production_value</th><th>staging_value</th></tr>
<tr><td>DB_HOST</td><td>prod-db.internal</td><td>staging-db.internal</td></tr>
<tr><td>API_BASE_URL</td><td>https://api.yourcompany.com</td><td>https://api-staging.yourcompany.com</td></tr>
...
// Output to Agent 2 context (after parsing for target environment)
{ env_vars: { DB_HOST: "prod-db.internal", API_BASE_URL: "https://api.yourcompany.com", ... }, page_version: 47 }

Used by Agent 3 (Post-Deploy Monitor Agent). The agent polls Datadog monitor states on a 5-minute interval after deployment completion. Monitor IDs and threshold definitions must be agreed with the team and stored in the credential store before build.

// Monitor state poll response (key fields)
{
  "id": 12345678,
  "name": "API Error Rate Post-Deploy",
  "overall_state": "OK",
  "query": "avg(last_5m):sum:trace.web.request.errors{env:production} / sum:trace.web.request.hits{env:production} > 0.05"
}
// Agent 3 decision logic
if overall_state == "Alert" -> trigger PagerDuty, flag Jira ticket
if overall_state == "OK" at any poll -> mark deployment healthy, close Jira

Used by Agent 3 only. A PagerDuty incident is fired via the Events API v2 when Datadog health checks breach threshold. The integration key (routing key) is service-specific and must match the deployment monitoring service configured in PagerDuty.

// Events API v2 trigger payload
{
  "routing_key": "{{PAGERDUTY_ROUTING_KEY}}",
  "event_action": "trigger",
  "dedup_key": "deploy-DEPLOY-142-run-789",
  "payload": {
    "summary": "Post-deploy health check ALERT: API Error Rate exceeded threshold (env: production)",
    "severity": "critical",
    "source": "deployment-automation",
    "component": "deploy-pipeline",
    "custom_details": {
      "jira_ticket": "DEPLOY-142",
      "environment": "production",
      "commit_sha": "a1b2c3d",
      "datadog_monitor_id": "12345678"
    }
  }
}

// Credential store contents (reference names only — values are never stored in this document)

// GitHub
GITHUB_WEBHOOK_SECRET          // HMAC-SHA256 secret for inbound webhook validation
GITHUB_APP_PRIVATE_KEY         // PEM-encoded private key for GitHub App JWT signing
GITHUB_APP_ID                  // GitHub App numeric ID
GITHUB_APP_INSTALLATION_ID     // Installation ID for the target repository
GITHUB_DEPLOY_WORKFLOW_ID      // Numeric or filename ID of the deployment workflow
GITHUB_REPO_FULL_NAME          // e.g. yourcompany/app
GITHUB_TARGET_BRANCH           // e.g. main

// Jira
JIRA_BASE_URL                  // e.g. https://yourcompany.atlassian.net
JIRA_EMAIL                     // Atlassian account email for Basic Auth
JIRA_API_TOKEN                 // API token from id.atlassian.net
JIRA_PROJECT_KEY               // e.g. DEPLOY
JIRA_ISSUE_TYPE_ID             // Numeric ID for deployment ticket issue type
JIRA_TRANSITION_DONE_ID        // Numeric transition ID for Done/Deployed status
JIRA_TRANSITION_FAILED_ID      // Numeric transition ID for Failed status

// Slack
SLACK_BOT_TOKEN                // xoxb- token for the Slack App
SLACK_SIGNING_SECRET           // Used to validate interactive callback signatures
SLACK_IT_LEAD_USER_ID          // Slack user ID for the IT lead (e.g. U012AB3CD)
SLACK_DEPLOY_CHANNEL_ID        // Channel ID for deployment result posts

// Confluence
CONFLUENCE_BASE_URL            // e.g. https://yourcompany.atlassian.net/wiki
CONFLUENCE_EMAIL               // Same Atlassian account email as Jira (if shared)
CONFLUENCE_API_TOKEN           // API token (can be same as JIRA_API_TOKEN if same account)
CONFLUENCE_CONFIG_PAGE_ID      // Numeric page ID of the environment config page

// Datadog
DATADOG_API_KEY                // 32-character API key
DATADOG_APP_KEY                // Application key for monitor read access
DATADOG_SITE                   // e.g. datadoghq.com (US1) or datadoghq.eu (EU1)
DATADOG_MONITOR_IDS            // Comma-delimited list of monitor IDs to poll

// PagerDuty
PAGERDUTY_ROUTING_KEY          // 32-character Events API v2 integration routing key
PAGERDUTY_SERVICE_ID           // PagerDuty service ID for dedup key construction

// Orchestration
DEPLOY_STATE_STORE_TTL_HOURS   // How long deploy_run_id state records are retained (default: 48)