Add runbooks to ITSM approval docs

src/pages/docs/approvals/index.md

@@ -20,7 +20,7 @@ Octopus Deploy includes ITSM integrations for ServiceNow and Jira Service Manage
 
 Our support focuses on:
 
-1. **Productive teams** - Automatically create change requests and associate them with Octopus deployments so you can work with the right stakeholders to ensure your changes are compliant and approved. Octopus can also prevent deployments from executing until all approvals are complete. 
+1. **Productive teams** - Automatically create change requests and associate them with Octopus deployments or runbook runs so you can work with the right stakeholders to ensure your changes are compliant and approved. Octopus can also prevent deployments and runbook runs from executing until all approvals are complete. 
 2. **Compliant DevOps** - Be sure that no one is deploying unapproved changes to production. Your audits become a smooth process as you can demonstrate your company's processes are being adhered to with system reports.
 
 ## ServiceNow change management without friction
@@ -29,18 +29,18 @@ Our support focuses on:
 ![ServiceNow deployment waiting for approval](/docs/approvals/servicenow-task-status-with-cr.png)
 :::
 
-This new integration links Octopus deployments to ServiceNow change requests and automatically creates pre-populated, normal change requests. You get improved traceability out-of-the-box, and you can prove to auditors that every controlled deployment has a change request. This ensures your CI/CD and release management processes are compliant with company policies and regulations.
+This new integration links Octopus deployments and runbook runs to ServiceNow change requests and automatically creates pre-populated, normal change requests. You get improved traceability out-of-the-box, and you can prove to auditors that every controlled deployment and runbook has a change request. This ensures your CI/CD and release management processes are compliant with company policies and regulations.
 What's included in our ServiceNow support?
 
 - Easy workflow configuration, so it's straightforward to integrate Octopus with ServiceNow.
-- Link a deployment to an existing change request to manually associate deployments with change requests.
-- Automatically create normal and emergency change requests at deployment time. Octopus pauses the deployment until the appropriate approvals are complete.
-- Let Octopus do the work for you by automating the transition between stages in the change request once created, leaving a deployment record in ServiceNow.
+- Link a deployment or runbook run to an existing change request to manually associate deployments with change requests.
+- Automatically create normal and emergency change requests at execution time. Octopus pauses the execution until the appropriate approvals are complete.
+- Let Octopus do the work for you by automating the transition between stages in the change request once created, leaving a deployment or runbook run record in ServiceNow.
 - Use change templates to auto-create standard change requests to reduce manual work and control what information is populated.
-- Ensure “Change Windows” are honored on existing change requests so deployments won't execute until the specified time window.
-- Add work notes to change requests with information about deployment start and finish time and whether it was successful or not.
+- Ensure “Change Windows” are honored on existing change requests so deployments or runbook runs won't execute until the specified time window.
+- Add work notes to change requests with information about deployment or runbook run start and finish time and whether it was successful or not.
 - Create change requests with pre-populated fields through variables.
-- View and export audit logs of controlled deployments for easy compliance and post-deployment reconciliation.
+- View and export audit logs of controlled deployments and runbook runs for easy compliance and post-execution reconciliation.
 
 Learn more about our [ServiceNow integration](/docs/approvals/servicenow).
 
@@ -58,14 +58,14 @@ To build on our ITSM change management support further, we are also pleased to a
 
 The Jira Service Management integration ensures that teams using this platform can access the benefits of creating change requests automatically in Octopus. It makes it easier to manage deployment pipelines at scale, reducing the complexity of change management. Integrating Octopus with Jira Service Management reduces the need for manually filling out change requests, making it faster and less prone to error. By using Octopus to create change requests automatically, you can create best practice change management easily. 
 
-This new integration links Octopus deployments to Jira Service Management change requests and automatically creates pre-populated “Request for change” change requests. You get improved traceability out-of-the-box, and you can prove to auditors that every controlled deployment has a change request. This ensures your CI/CD and release management processes are compliant with company policies and regulations.
+This new integration links Octopus deployments and runbook runs to Jira Service Management change requests and automatically creates pre-populated “Request for change” change requests. You get improved traceability out-of-the-box, and you can prove to auditors that every controlled deployment and runbook has a change request. This ensures your CI/CD and release management processes are compliant with company policies and regulations.
 
 What's included in our Jira Service Management support?
 
 - Easy workflow configuration, so it's straightforward to integrate Octopus with Jira Service Management
-- Link a deployment to an existing change request, to manually associate deployments with change requests
-- Automatically create "Request for change" requests at deployment time. Octopus pauses the deployment until the appropriate approvals are complete
-- View and export audit logs of controlled deployments for easy compliance and post-deployment reconciliation
+- Link a deployment or runbook run to an existing change request, to manually associate deployments and runbook runs with change requests
+- Automatically create "Request for change" requests at execution time. Octopus pauses the execution until the appropriate approvals are complete
+- View and export audit logs of controlled deployments and runbook runs for easy compliance and post-execution reconciliation
 
 If your team uses Jira Service Management change management, we'd love for you to try it and provide your feedback.
 

src/pages/docs/approvals/jira-service-management/index.md

@@ -20,12 +20,23 @@ Request** (aka issue).
 To enable this behavior, both the Octopus Project and Environment you are deploying to must be 
 configured and the JSM configuration is set up before deployments can be managed.
 
+### Deployments
+
 | Project | Environment | Outcome |
 |--|--|--|
 | Change controlled| Change controlled| Approval required for deployment |
 | **_Not_** Change controlled| Change controlled| No approval required |
 | Change controlled| **_Not_** Change controlled| No approval required |
 
+### Runbooks
+
+| Project | Environment | Runbook | Outcome |
+|--|--|--|--|
+| Change controlled | Change controlled | Enabled | Approval required |
+| Change controlled | Change controlled | **_Not_** Enabled | No approval required |
+| **_Not_** Change controlled | Change controlled | Enabled | No approval required |
+| Change controlled | **_Not_** Change controlled | Enabled | No approval required |
+
 ## Getting started
 
 The JSM integration requires Octopus **2022.3.12101** or later and an Octopus license with the
@@ -111,11 +122,11 @@ Integration**, click the **Customer Comments Enabled** checkbox show below then
 ![JSM Integration Enable Work Notes](/docs/approvals/jira-service-management/images/jsm-customer-comments-settings.png)
 :::
 
-## Configuring deployments
+## Configuring approvals
 
-To enforce a deployment to require an approved CR, the **Change Controlled** setting needs to be enabled in **both** the project and the environment it is being deployed to.
+### Setting up deployments for CR approval
 
-### Setting up projects for CR approval
+To enforce a deployment to require an approved CR, the **Change Controlled** setting needs to be enabled in **both** the project and the environment it is being deployed to.
 
 To enable a project to enforce a requirement for an approved CR:
 
@@ -128,9 +139,28 @@ To enable a project to enforce a requirement for an approved CR:
 ![JSM Integration Project settings](/docs/approvals/jira-service-management/images/jsm-project-settings.png)
 :::
 
+### Setting up runbooks for CR approval
+
+:::div{.warning}
+This feature is only available for version **2025.2.x** and later
+:::
+
+To enforce a runbook run to require an approved CR, the runbook needs to be included in the **Enabled Runbooks** setting and the **Change Controlled** setting also needs to be enabled in **both** the project and the environment the runbook is run in. 
+
+To enable a runbook to enforce a requirement for an approved CR:
+
+1. Navigate to the project and then **Settings ➜ ITSM Providers**.
+2. Check the **Jira Service Management Integration ➜ Change Controlled** setting.
+3. Select your JSM connection in the **Jira Service Management Connection** setting.
+4. Select the runbooks you want to require an approved CR in the **Enabled Runbooks** setting, and then press **SAVE**
+
+:::figure
+![JSM Integration Project settings](/docs/approvals/jira-service-management/images/jsm-runbooks-settings.png)
+:::
+
 ### Default behavior
 
-Deployments resulting in a CR creation will produce an issue with a Request Type of **Request a 
+Deployments and runbook runs resulting in a CR creation will produce an issue with a Request Type of **Request a 
 change**
 
 ### Supplying the CR number to a deployment
@@ -215,3 +245,7 @@ The following list assumes the linked change is in an **approved** state.
   the deployment to proceed. If the Issue is incorrect, you will need to cancel the deployment, 
   close the CR and try the deployment again.
 - Each project only supports a single JSM connection.
+
+## Older versions
+
+- Prior to version **2025.2.x** runbooks did not support JSM approvals.

src/pages/docs/approvals/servicenow/index.md

@@ -14,16 +14,27 @@ The ServiceNow Integration feature is available from Octopus **2022.3** onwards
 
 ## Overview
 
-The Octopus Deploy/ServiceNow integration allows you to block the execution of specifically configured deployments unless they have a corresponding approved ServiceNow **Change Request** (CR).
+The Octopus Deploy/ServiceNow integration allows you to block the execution of specifically configured deployments or runbooks unless they have a corresponding approved ServiceNow **Change Request** (CR).
 
-To enable this behavior, both the Octopus Project and Environment you are deploying to must be configured and the ServiceNow configuration is set up before deployments can be managed.
+To enable this behavior, both the Octopus Project and Environment you are deploying to, or running an enabled runbook in, must be configured and the ServiceNow configuration is set up before the execution can be managed.
+
+### Deployments
 
 | Project | Environment | Outcome |
 |--|--|--|
 | Change controlled| Change controlled| Approval required for deployment |
 | **_Not_** Change controlled| Change controlled| No approval required |
 | Change controlled| **_Not_** Change controlled| No approval required |
 
+### Runbooks
+
+| Project | Environment | Runbook | Outcome |
+|--|--|--|--|
+| Change controlled | Change controlled | Enabled | Approval required |
+| Change controlled | Change controlled | **_Not_** Enabled | No approval required |
+| **_Not_** Change controlled | Change controlled | Enabled | No approval required |
+| Change controlled | **_Not_** Change controlled | Enabled | No approval required |
+
 ## Getting started
 
 The ServiceNow integration requires Octopus **2022.3** or later and an Octopus enterprise subscription.
@@ -118,32 +129,51 @@ To enable this feature navigate to **Configuration ➜ Settings ➜ ServiceNow I
 ![ServiceNow Integration Enable Work Notes](/docs/approvals/servicenow/images/servicenow-worknotes-settings.png)
 :::
 
-## Configuring deployments
+## Configuring approvals
 
-To enforce a deployment to require an approved CR, the **Change Controlled** setting needs to be enabled in **both** the project and the environment it is being deployed to.
+### Setting up deployments for CR approval
 
-### Setting up projects for CR approval
+To enforce a deployment to require an approved CR, the **Change Controlled** setting needs to be enabled in **both** the project and the environment it is being deployed to.
 
 To enable a project to enforce a requirement for an approved CR:
 
 1. Navigate to the project and then **Settings ➜ ITSM Providers**.
-2. Check the **Change-controlled** setting.
-3. Select your ServiceNow connection in the **ServiceNow Connection** setting and click **SAVE**.
+2. Check the **ServiceNow Integration ➜ Change Controlled** setting.
+3. Select your ServiceNow connection in the **ServiceNow Connection** setting, and then press **SAVE**.
 
 :::figure
 ![ServiceNow Integration Project settings](/docs/approvals/servicenow/images/servicenow-cd-project-settings.png)
 :::
 
+### Setting up runbooks for CR approval
+
+:::div{.warning}
+This feature is only available for version **2025.2.x** and later
+:::
+
+To enforce a runbook run to require and approved CR, the **Change Controlled** settings needs to be enabled in **both** the project and the environment the runbooks is run in and additionally the runbook needs to be included in the **Enabled Runbooks** setting.
+
+To enable a runbook to enforce a requirement for an approved CR:
+
+1. Navigate to the project and then **Settings ➜ ITSM Providers**.
+2. Check the **ServiceNow Integration ➜ Change Controlled** setting.
+3. Select your ServiceNow connection in the **ServiceNow Connection** setting.
+4. Select the runbooks you want to require an approved CR in the **Enabled Runbooks** setting, and then press **SAVE**
+
+:::figure
+![ServiceNow Integration Runbooks settings](/docs/approvals/servicenow/images/servicenow-cd-runbooks-settings.png)
+:::
+
 ### Standard, Normal, and Emergency Changes
 
-By default, deployments resulting in CR creation will produce a `Normal` change (i.e. one 
+By default, deployments and runbooks runs resulting in CR creation will produce a `Normal` change (i.e. one 
 requiring explicit approval).
 
 Setting the **Standard Change Template Name** setting under **ITSM Providers** to the name of an 
 active, approved **Standard Change Template** (as found in the Standard Change Catalog) will instead 
-result in deployments of the project creating a `Standard` (i.e. low-risk, pre-approved) change.
+result in deployments and runbook runs of the project creating a `Standard` (i.e. low-risk, pre-approved) change.
 
-From **2024.2** you can create an `Emergency` change by selecting the Emergency Change setting on the deployment creation page.
+From **2024.2** you can create an `Emergency` change by selecting the Emergency Change setting on the deployment or runbook run creation page.
 :::figure
 ![ServiceNow Integration Project settings](/docs/approvals/servicenow/images/servicenow-emergency-change.png)
 :::
@@ -152,7 +182,7 @@ From **2024.2** you can create an `Emergency` change by selecting the Emergency
 
 If you add a variable to your project named `Octopus.ServiceNow.ChangeRequest.Number`, then a CR will not be created, and instead, the supplied CR number will be used during the approval check. This variable can also be [scoped](/docs/projects/variables/getting-started/#scoping-variables).
 
-From **2024.2** on this can be set under the `ServiceNow Change Request settings` section on the deployment creation page. Setting the CR number at the deployment level will override any predefined variable.
+From **2024.2** on this can be set under the `ServiceNow Change Request settings` section on the deployment or runbook run creation page. Setting the CR number at the deployment or runbook run level will override any predefined variable.
 
 ### Setting up environments for CR approval
 
@@ -288,3 +318,6 @@ The ServiceNow integration uses the following REST endpoints:
 |Approve Standard Change               | `PATCH`     | `/api/sn_chg_rest/change/{changeId}`            | Requires  project **Automatic Transition** configuration |
 |Add work notes                        | `PATCH`     | `/api/sn_chg_rest/change/{changeId}`            | Requires  **Work Notes Enabled** **ServiceNow** global configuration |
 
+## Older versions
+
+- Prior to version **2025.2.x** ServiceNow approvals for runbooks were not supported.