Some enterprises require bespoke governance, either because they are not standardized on ServiceNow or because they use it in a unique, tailor-built way. Plural allows you to bridge that gap with a simple webhook-based protocol. Before implementing, it's worth briefly looking through the docs on PR governance to familiarize yourself with the model.

Defining a PrGovernance CRD

The webhook-based Governance CRD is relatively straightforward. Here's an example:

apiVersion: deployments.plural.sh/v1alpha1
kind: PrGovernance
metadata:
  name: webhook
spec:
  type: WEBHOOK
  connectionRef:
    name: governance # reference to the ScmConnection that is used for Pr approval
  configuration:
    webhook:
      url: https://governance-webhook.acme.com

From there, to tie it to a pull request, you'll need:

1. An SCM webhook for the repository pointing to Plural (this can be created in Self Service -> SCM Management in your Plural Console instance).
2. The Plural governance: webhook tag in your PR description, so that we identify it as requiring governance.

Webhook Controller Implementation

The webhook expects three REST-like APIs to be present:

• POST /v1/open - called when a PR is created
• POST /v1/confirm - called while a PR is open; allows auto-approval if it returns 200
• POST /v1/close - called once a PR is merged or closed, allowing your implementation to clean up any needed resources

Throughout the request flow, we will persist the results from prior calls as state, and provide a JSON-encoded request body in the following format:

{
    "state": any | null,
    "pr": {
        "id": string,
        "title": string,
        "body": string,
        "ref": string,
        "url": string,
        "status": "open" | "closed" | "merged",
        "labels": string[]
    }
}

The webhook controller will do the following once it is tied to a PR:

1. On PR open, call POST /v1/open
2. While the PR is open, periodically call POST /v1/confirm with the body from the prior call to /v1/open provided in the state field above.
3. If /v1/confirm returns 200, the pull request is approved.
4. Once the pull request is merged or closed, a call to POST /v1/close is made.

Here's a state diagram for the visually inclined as well: