diff --git a/src/pages/docs/projects/version-control/converting/index.md b/src/pages/docs/projects/version-control/converting/index.md index 6718a07a5b..3e6f22aae3 100644 --- a/src/pages/docs/projects/version-control/converting/index.md +++ b/src/pages/docs/projects/version-control/converting/index.md @@ -41,12 +41,15 @@ Finally, add your default branch name in Branch Settings and click **Configure** ![configuring version control](/docs/projects/version-control/converting/configure-version-control.png) ::: -Your project is now configured with Version Control. You can see this change reflected on the left navigation of the page, where you can change branches. You can also confirm this in your Git repository. The `.octopus` directory will now be created, and it should contain the following files: +Your project is now configured with Version Control. You can see this change reflected on the left navigation of the page, where you can change branches. You can also confirm this in your Git repository. The `.octopus` directory will now be created, and it should contain the following files and folders: - _deployment_process.ocl_ - _deployment_settings.ocl_ - _variables.ocl_ - _schema_version.ocl_ +- _runbooks/_ + +The runbooks/ directory will contain runbook-name.ocl files for any published runbooks. If your repository has branch protection setup, see [Setting up in a repository with protected branches](/docs/projects/version-control/converting/#setting-up-in-a-repository-with-protected-branches). @@ -78,12 +81,15 @@ Once you press the **Configure** button, a modal window will appear to confirm t ![configuring version control](/docs/projects/version-control/converting/configure-version-control.png) ::: -Your project is now configured with Version Control. You can see this change reflected on the left navigation of the page, where you can change branches. You can also confirm this in your Git repository. The `.octopus` directory will now be created, and it should contain the following files: +Your project is now configured with Version Control. You can see this change reflected on the left navigation of the page, where you can change branches. You can also confirm this in your Git repository. The `.octopus` directory will now be created, and it should contain the following files and folders: - _deployment_process.ocl_ - _deployment_settings.ocl_ - _variables.ocl_ - _schema_version.ocl_ +- _runbooks/_ + +The runbooks/ directory will contain runbook-name.ocl files for any published runbooks. If your repository has branch protection setup, see [Setting up in a repository with protected branches](/docs/projects/version-control/converting/#setting-up-in-a-repository-with-protected-branches). @@ -105,6 +111,11 @@ Optionally, you can also nominate protected branches for your Project. This will ![protected branches](/docs/projects/version-control/converting/configure-protected-branches.png) ::: +## Migrating an existing Git project to use config-as-code runbooks + +Projects which converted to Git before the introduction of config-as-code runbooks can be easily updated. You can migrate an existing version controlled project to use config-as-code runbooks by clicking on the 'Store Runbooks in Git' banner at the top of the **Runbooks** page of your project. + +[See here for more information on converting a project to use config-as-code.](/docs/runbooks/config-as-code-runbooks) ## Migrating variables on an existing Git project @@ -112,9 +123,9 @@ Since the initial public release of config-as-code, we've added support for addi ## Not everything is saved to version control -The Configuration as Code feature is per-project. Currently, only the deployment process, settings, and non-sensitive variables are saved to version control. Eventually, it will also include runbooks. +The Configuration as Code feature is per-project. Currently, the deployment process, runbook processes, settings, and non-sensitive variables are saved to version control. -Even after Runbooks are added, a number of project-level and instance-level settings will not be stored in version control. +A number of project-level and instance-level settings will not be stored in version control. Learn more about [what is stored in version control](/docs/projects/version-control/config-as-code-reference). diff --git a/src/pages/docs/projects/version-control/index.md b/src/pages/docs/projects/version-control/index.md index b7ab5e96b8..ead86cb89e 100644 --- a/src/pages/docs/projects/version-control/index.md +++ b/src/pages/docs/projects/version-control/index.md @@ -11,7 +11,7 @@ hideInThisSection: true ## Introduction -The Configuration as Code (config-as-code) feature adds support for configuring Octopus projects to store project resources in a Git repository. For now, only the _deployment process_, _deployment settings_, and _non-sensitive variables_ can be version-controlled. +The Configuration as Code (config-as-code) feature adds support for configuring Octopus projects to store project resources in a Git repository. For now, the _deployment process_, _runbook processes_, _deployment settings_, and _non-sensitive variables_ can be version-controlled. The Octopus UI needed to remain fully functional for version-controlled projects, and it has. You can continue to use the UI exactly as you always have, but with an additional superpower: Git branches are now exposed in the UI, allowing editing of currently supported project configuration on any branch via the UI. If you type the name of a branch that doesn't exist in your repository, you'll see an option to create that branch. This option is available when committing changes too. @@ -21,18 +21,12 @@ The Octopus UI needed to remain fully functional for version-controlled projects Of course, there is now a text representation of the process in the Git repository, and if you prefer editing text, open your favorite editor and go for it. We refer to the text format as Octopus Configuration Language (OCL), and it is very much inspired by [HCL](https://github.com/hashicorp/hcl). -That means that where previously there was only a single current version of the deployment process, it is now possible to have many. When creating releases, the relevant branch can be selected. We have also added [branch system variables](/docs/projects/variables/system-variables/#release-branch-information) that can be used in your custom deployment scripts. +That means that where previously there was only a single current version of the deployment or runbook process, it is now possible to have many. When creating releases, the relevant branch can be selected. We have also added [branch system variables](/docs/projects/variables/system-variables/#release-branch-information) that can be used in your custom deployment scripts. :::div{.warning} Config-as-code only supports [git](https://git-scm.com/) repositories. Before using this feature, you should be familiar with [git concepts](https://git-scm.com/doc) such as distributed version control, pushing, pulling, branching, merging, and fetching. ::: -### What's next? - -We have some strong opinions on what's next. The latest release of config-as-code supports _deployment processes_, _deployment settings_, and _non-sensitive variables_. - -We have plans for future releases of config-as-code to support Runbooks. In addition, we'd like to evolve the OCL schema to make it friendlier for editing by hand. - ### We want your feedback Our major goal for the early stages of this feature is to discover the ways people want config-as-code to evolve. What scenarios would you like to see unlocked? What doesn't work the way you hoped? @@ -47,6 +41,8 @@ You can provide feedback through whichever of the following channels you feel mo Version-control is configured per project and is accessed via the **Settings ➜ Version Control** navigation menu item. +New version controlled projects will automatically have config-as-code for both deployment and runbook processes. You can migrate an existing version controlled project to use config as code runbooks by clicking on the 'Store Runbooks in Git' banner at the top of the **Runbooks** page of your project. + Learn more about [Configuring version control on a project](/docs/projects/version-control/converting). ## Config-as-code reference diff --git a/src/pages/docs/runbooks/config-as-code-runbooks.md b/src/pages/docs/runbooks/config-as-code-runbooks.md new file mode 100644 index 0000000000..0bfc0c8bf5 --- /dev/null +++ b/src/pages/docs/runbooks/config-as-code-runbooks.md @@ -0,0 +1,84 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2024-11-24 +modDate: 2024-11-24 +title: Config as Code runbooks +description: Details about using configuration as code with runbooks. +navOrder: 20 +icon: fa-brands fa-git-alt +--- + +:::div{.success} +Support for CaC Runbooks is rolling out to Octopus Cloud now and will be available in Octopus Server in a future release +::: + +Config as Code (or CaC) Runbooks stores your runbook process as code in your project repository. This means that you can now use version control to track changes to your runbook processes alongside changes to your project code. + +You may already be using CaC to store your Octopus deployment process, deployment settings and non-sensitive variables. Adding CaC Runbooks completes that picture. + +The config for your runbooks, as well as your deployments, settings and variables, is stored as OCL files which you can edit in Octopus or directly in your IDE. + +Using CaC Runbooks is optional. You can also choose to keep using Runbooks as you always have on your existing version controlled projects and on projects without version control. + +## CaC Runbooks on a new version controlled project + +If you're [creating a new version controlled project](/docs/projects/version-control/converting#creating-a-new-version-controlled-project) or [adding version control to an existing project](/docs/projects/version-control/converting#configuring-an-existing-project-to-use-git), CaC Runbooks will be automatically enabled on your project. + +## CaC Runbooks on an existing version controlled project + +:::div{.info} +Converting a project to use CaC Runbooks is a one-way change. Once you convert a project, you **cannot** convert it back. Please make sure you want to do this, and consider cloning your project to test how it works, so you know what to expect before converting important projects. +::: + +You can migrate an existing version controlled project to use CaC Runbooks by clicking on the 'Store Runbooks in Git' banner at the top of the **Runbooks** page of your project and following the prompts. + +Once that's done, you should see a branch selector at the top of the **Runbooks** page, and a new 'runbooks/' directory in your repository alongside your existing OCL files. (See the '.octopus/ directory' of your repository project repository.) + +## Drafts vs branches + +One of the exciting things about CaC is that it allows you to edit your runbooks over as many branches as you would like, creating as many copies of the runbook as you have branches. This means that we no longer need 'draft' runbooks. + +When you convert your project to use CaC Runbooks, only published runbooks will be available in Octopus as CaC Runbooks. + +Draft runbooks will still be converted to code. They can be found in the 'runbooks/migrated-drafts/' directory alongside the other runbooks OCL files in your 'runbooks/' directory. + +To access your draft runbooks in Octopus, you can simply move their OCL files up to the 'runbooks/' folder. + +But first let's consider how CaC Runbooks uses branches to handle permissions. + +## Permissions by branch + +When converting your project to CaC, you specify a 'default' branch to contain the approved versions of your OCL files. + +Other branches can be thought of as containing restricted versions of your runbooks. These may be unfinished runbooks or runbooks that you want to place extra permissions around. + +You also have the option to specify 'protected' branches. Protected branches cannot be changed from within Octopus. Consider marking any branch which you would normally follow a PR review process to update as protected, including your default branch. + +Octopus provides two built in roles to help you to manage permissions around editing and running runbooks: 'Runbook Consumer' and 'Runbook Producer'. + +#### Runbook Consumer: +- Non-CaC Runbooks - cannot edit runbooks and can only run published runbooks. +- CaC Runbooks - cannot edit runbooks and can only run runbooks from the latest commit on the default branch. + +#### Runbook Producer: +- Non-CaC Runbooks - can edit and run both draft and published runbooks. +- CaC Runbooks - can edit runbooks on any unprotected branches and can run runbooks from any commit on any branch. + +Assuming your default branch is protected, this effectively means that your old 'published' runbooks will become the runbooks in the latest commit on your default branch, and your old 'draft' runbooks will become the runbooks on any other commit on any branch. + +💡 If you are using Octopus's built in roles, keep these permissions in mind when moving your draft runbooks out of the 'migrated-drafts/' folder and consider storing these runbooks on a non-default branch. + +## Snapshots vs commits + +Another exciting thing about CaC Runbooks is that every revision to your runbook process, settings and variables is captured in your commit history. This means that you can now re-run any previous version of your runbook without the need for snapshots. + +To re-run a previous version of a CaC Runbook, simply enter a commit hash on the branch selector at the **Runbooks** page then run from that commit. If you are using the Octopus built in roles, this will require the Runbook Producer role. + +The information that was previously found on the **Snapshot** page is still available on the **Details** tab of each runbook run. + +💡 Rather than setting package versions in your runbook snapshots, you can now specify fixed package versions inside your runbook steps and store these in CaC alongside the rest of your runbook process. + +## Scheduled triggers + +Runbook triggers will always run CaC Runbooks from the latest commit on your default branch, just as non-CaC runbook triggers will only run published runbooks. + diff --git a/src/pages/docs/runbooks/runbook-publishing/index.md b/src/pages/docs/runbooks/runbook-publishing/index.md index 421ec828c6..3830a90cd5 100644 --- a/src/pages/docs/runbooks/runbook-publishing/index.md +++ b/src/pages/docs/runbooks/runbook-publishing/index.md @@ -7,6 +7,10 @@ description: Publishing makes a runbook available to scheduled triggers and cons navOrder: 30 --- +:::div{.success} +Config-as-code runbooks use branches instead of publishing. If your project uses config-as-code runbooks, read about [managing runbooks permissions using branches](/docs/runbooks/config-as-code-runbooks#permissions-by-branch) instead. +::: + Runbooks and deployments define their processes in exactly the same way. However, where a deployment has a [release](/docs/releases), a runbook has what is called a Snapshot. ## Snapshots diff --git a/src/pages/docs/runbooks/runbooks-vs-deployments/index.md b/src/pages/docs/runbooks/runbooks-vs-deployments/index.md index 0abc9037c0..6d4d6a84ea 100644 --- a/src/pages/docs/runbooks/runbooks-vs-deployments/index.md +++ b/src/pages/docs/runbooks/runbooks-vs-deployments/index.md @@ -66,6 +66,7 @@ In Octopus 2020.2 and earlier, the runbook retention policy could not be set. In ::: ## Snapshots versus Releases + Runbooks are similar to deployments in that they also take a copy of the process to be used with execution. For a runbook this is referred to as a [snapshot](/docs/runbooks/runbook-publishing/#snapshots) versus a [release](/docs/releases) for a deployment. Runbooks can have two different types of snapshots: - Draft