docs: ServiceNow integration design note (Bytebase-first)#20477
docs: ServiceNow integration design note (Bytebase-first)#20477d-bytebase wants to merge 3 commits into
Conversation
Design note for integrating Bytebase change approval & rollout with ServiceNow ITSM (CAB). Covers the Bytebase-first flow, enforcement prerequisites (catch-all approval rule, bb.taskRuns.create lockdown, per-env RolloutPolicy), the async rollout-creation race fix, failure/ reject paths, the polling model (who polls + scalability), security/ audit considerations, and the gaps (no generic outbound webhook, no external-ticket field). Includes an API-reference table for implementers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bc03261d19
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| - **Rejected →** `RejectIssue`. **Rework →** `RequestIssue`. Store the CHG ↔ issue mapping; link back via `CreateIssueComment` (include the **SN approver identity + CHG number** — see Security/Audit). | ||
| 4. **Approve back (API).** On CHG approval, call `ApproveIssue` as the service account. | ||
| 5. **Wait for the rollout to exist (race fix).** `ApproveIssue` creates the rollout **asynchronously** (it returns before stages/tasks exist). Do **not** call `BatchRunTasks` immediately. Either: | ||
| - poll `GetRollout` until `has_rollout == true` (simplest), **or** |
There was a problem hiding this comment.
has_rollout is a Plan field, while RolloutService.GetRollout returns a Rollout that has no such field; the implementation also returns NotFound while plan.Config.HasRollout is false. An orchestrator following this step cannot observe has_rollout from GetRollout and may spin or fail after approval. This should instead say to retry GetRollout until it stops returning NotFound, or poll GetPlan/ListPlans for has_rollout.
Useful? React with 👍 / 👎.
…ServiceNow) Document an optional design tradeoff to reduce the issue-created-to-CHG discovery latency: reuse the existing TEAMS webhook type (allowlist accepts *.powerplatform.com / *.logic.azure.com via suffix match) to push ISSUE_CREATED into a Power Automate flow that creates the CHG via its ServiceNow connector. Notes the reliability tradeoff (fire-and-forget, no retry) and recommends a slow reconciliation poll as a backstop. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Webhook and polling are complementary, not either/or: webhook push for low latency, reconciliation poll as the reliability backstop (Bytebase webhooks are fire-and-forget with no retry). Issue-name idempotency makes double-delivery safe. Same hybrid applies to status (PIPELINE_* webhook + follow poll). Adds a source/role comparison table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5a2cf64dce
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| | Source | Role | Strength | Weakness | | ||
| |--------|------|----------|----------| | ||
| | **Webhook push** | primary | near-instant; no scan cost | fire-and-forget, 3s timeout, **no retry** → a dropped event is lost | | ||
| | **Reconciliation poll** | backstop | self-heals; also catches the catch-all-rule bypass and issues created while the endpoint was down | minute-level latency (ServiceNow) | |
There was a problem hiding this comment.
With the poll defined in step 2 (approval_status == "PENDING"), this reconciliation path will not catch the catch-all-rule bypass: unmatched issues are converted to ApprovalStatus_SKIPPED when no approval template is applied (computeApprovalStatus), not PENDING. If operators rely on this backstop to alert on misconfiguration, bypassed changes can still be missed; document a separate SKIPPED/no-CHG reconciliation or remove this claim.
Useful? React with 👍 / 👎.
| 2. On issue creation Bytebase POSTs a MessageCard immediately (async, ~instant). The card carries the issue **link** (`.../projects/{project}/issues/{uid}`), title, status, and actor. | ||
| 3. The Power Automate flow parses the card, extracts the issue ref (optionally calls `GetIssue` for detail), and creates the CHG via its native **ServiceNow connector**, storing the issue ↔ CHG mapping. |
There was a problem hiding this comment.
For *.powerplatform.com/*.logic.azure.com URLs, the TEAMS receiver takes the postPowerAutomateMessage path, which sends an activity envelope containing an Adaptive Card; the MessageCard shape is only used by postMessage for legacy connector URLs. Following this wiring against a Power Automate HTTP trigger and parsing a MessageCard will miss the issue link/status fields, so the CHG creation flow should be documented against the adaptive-card payload instead.
Useful? React with 👍 / 👎.
1 participant
What
Adds a design note at
docs/design/servicenow-integration.mdfor integrating Bytebase's database-change approval and rollout with ServiceNow ITSM (CAB) approval, in a Bytebase-first model (user authors the change in the Bytebase UI; ServiceNow gates approval and drives the rollout via the public API).Why
Recurring customer ask: unify the approval process so a database change created in Bytebase is mirrored to a ServiceNow CHG, and rollout is controlled by ServiceNow once the CHG is approved. This note captures the technical workflow, the enforcement model, and the integration gaps so we can have a grounded conversation with customers and scope any product work.
Contents
bb.taskRuns.createlockdown to prevent UI bypass, per-environmentRolloutPolicy.automatic=false.ApproveIssuecreates the rollout asynchronously, so the orchestrator must wait onhas_rollout(or callCreateRolloutexplicitly, guarded for idempotency) beforeBatchRunTasks.RejectIssue,RequestIssue,BatchCancelTaskRuns,BatchSkipTasks.Notes
ListIssuesfiltering, rollout-creation timing).🤖 Generated with Claude Code