diff --git a/public/docs/img/releases/images/release-variable-snapshot-section.png b/public/docs/img/releases/images/release-variable-snapshot-section.png index 0a471c45f7..0f3cc8f6f4 100644 Binary files a/public/docs/img/releases/images/release-variable-snapshot-section.png and b/public/docs/img/releases/images/release-variable-snapshot-section.png differ diff --git a/public/docs/img/shared-content/projects/variables/images/review-variables-drawer.png b/public/docs/img/shared-content/projects/variables/images/review-variables-drawer.png new file mode 100644 index 0000000000..bbef52fc0f Binary files /dev/null and b/public/docs/img/shared-content/projects/variables/images/review-variables-drawer.png differ diff --git a/src/pages/docs/releases/creating-a-release.md b/src/pages/docs/releases/creating-a-release.md index d69153bc62..07118a613b 100644 --- a/src/pages/docs/releases/creating-a-release.md +++ b/src/pages/docs/releases/creating-a-release.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-04-29 -modDate: 2026-04-16 +modDate: 2026-08-21 title: Creating a release description: Learn how to create a release in Octopus Deploy navOrder: 2 @@ -99,7 +99,7 @@ This lets you see the variables as they existed when the release was created. ![The Octopus release screen with variable snapshots highlighted](/docs/img/releases/images/release-variable-snapshot-section.png) ::: -You can update the variables by clicking **UPDATE VARIABLES**. This can be useful when: +You can update the variables by clicking **Update All Variables**. This can be useful when: - The release has not been deployed yet, but the variables have changed since the release was created. - The release needs to be **redeployed** and the variables have changed since the release was created. @@ -107,6 +107,37 @@ You can update the variables by clicking **UPDATE VARIABLES**. This can be usefu After you've updated the variables, the release will use the updated variables when it is deployed. +**Update All Variables** replaces the whole snapshot, so every variable picks up its current value. If you only want some of the changes, use **Review Variables** instead to choose which variables to update. + +#### Review and update selected variables {#review-and-update-selected-variables} + +**Review Variables** lets you compare the release's variable snapshot against your project's current variables, then update only the variables you choose. The rest of the snapshot keeps the values it was created with, so you can take a single corrected variable into a release without pulling in unrelated changes made since. + +This is useful when a deployment failed because of one bad variable value, or when a colleague has changed variables you're not ready to adopt. + +**Before you begin** + +You'll need: + +- The **VariableView** or **LibraryVariableSetView** permission on the project, to see the button and the comparison. +- The **ReleaseEdit** permission on the project, to apply the update. +- A project that doesn't store its variables in Git. Selective updates aren't supported once a project's variables have been [migrated to Git](/docs/projects/version-control/converting/migrating-variables). + +To review and update selected variables: + +1. Using the project side menu, navigate to **Deployments ➜ Releases**. +1. Select the release you want to update. +1. Scroll to the **Variable Snapshot** section and click **Review Variables**. +1. Review the variables listed under **Changed**. Octopus selects all of them for you, so clear the check box next to any variable you want to leave as it is. +1. Click **Update**. +1. Check the summary of what you're about to change, then click **Confirm**. + +:::figure +![The Select variables to update drawer listing changed variables with check boxes, showing each variable's name, value, scope, and source](/docs/img/shared-content/projects/variables/images/review-variables-drawer.png) +::: + +The **Variable Snapshot** section shows the updated snapshot, and the release uses the updated variables the next time it's deployed. Variables you didn't select keep the values they had when the release was created. + #### Variable snapshot for Git projects The variable snapshot for Git projects is a combination of the variables on the selected branch and the sensitive variables stored in the database. diff --git a/src/pages/docs/runbooks/runbook-variables/index.mdx b/src/pages/docs/runbooks/runbook-variables/index.mdx index e7b945dec2..ca882e991d 100644 --- a/src/pages/docs/runbooks/runbook-variables/index.mdx +++ b/src/pages/docs/runbooks/runbook-variables/index.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2026-08-21 title: Runbook variables description: How to use variables in runbooks navOrder: 24 @@ -28,6 +28,37 @@ Variables can be scoped to specific runbooks, or to the deployment process, by n [Prompted variables](/docs/projects/variables/prompted-variables) can be defined for runbooks. By default, prompted variables will prompt for the value when deploying or when running a runbook. By [scoping prompted variables](#Variables-specific-to-a-runbook) to one or more processes, they can be restricted to only prompt when deploying or for specific runbooks. +## Review and update snapshot variables + +When you publish a runbook, Octopus takes a snapshot of the variables as they exist at that moment. If your project's variables change afterwards, the snapshot keeps the older values until you update it. + +**Review Variables** on the runbook snapshot page lets you compare the snapshot against your project's current variables and update only the variables you choose. The rest of the snapshot keeps the values it was created with, so you can correct a single variable without pulling in unrelated changes made since the snapshot was taken. + +**Before you begin** + +You'll need: + +- The **VariableView** or **LibraryVariableSetView** permission on the project, to see the button and the comparison. +- The **RunbookEdit** permission on the project, to apply the update. +- A project that doesn't store its variables in Git. Selective updates aren't supported once a project's variables have been [migrated to Git](/docs/projects/version-control/converting/migrating-variables). + +To review and update selected variables: + +1. Using the project side menu, navigate to **Operations ➜ Runbooks**. +1. Select the runbook, then select the snapshot you want to update. +1. Scroll to the **Variable Snapshot** section and click **Review Variables**. +1. Review the variables listed under **Changed**. Octopus selects all of them for you, so clear the check box next to any variable you want to leave as it is. +1. Click **Update**. +1. Check the summary of what you're about to change, then click **Confirm**. + +:::figure +![The Select variables to update drawer listing changed variables with check boxes, showing each variable's name, value, scope, and source](/docs/img/shared-content/projects/variables/images/review-variables-drawer.png) +::: + +The **Variable Snapshot** section shows the updated snapshot, and the runbook uses the updated variables the next time it runs. Variables you didn't select keep the values they had when the snapshot was created. + +To replace every variable in the snapshot instead of choosing individual variables, use **Update All Variables**. + ## Runbooks variables in Git projects When snapshotting a Runbook in a Git project, the variables will always be taken from the default branch. The Git reference and commit that was used to create the snapshot is shown on the Runbook snapshot page.