diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c788520bb0..56385a4986 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -99,7 +99,7 @@ /docs/projects/coordinating-multiple-projects/ @OctopusDeploy/team-support -# updates to the config as code section are reviewed by team-modern-deployments +# updates to the version control section are reviewed by team-modern-deployments /docs/projects/version-control/ @OctopusDeploy/team-devex diff --git a/src/pages/docs/administration/data/data-migration.md b/src/pages/docs/administration/data/data-migration.md index 6e70518b92..3a99f3cc39 100644 --- a/src/pages/docs/administration/data/data-migration.md +++ b/src/pages/docs/administration/data/data-migration.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-07-15 +modDate: 2025-05-13 title: Data Migration description: Octopus comes with a data migrator that can help with specific scenarios, such as exporting configuration for storage and audit and single-direction copying of projects from one Octopus Server to another. navOrder: 30 @@ -31,7 +31,7 @@ The data migration tools are only suitable for some scenarios. In most cases, th 1. To split a single Octopus Server into multiple separate Octopus Servers in a one-time operation, use the [Export/Import Projects feature](/docs/projects/export-import). 1. To sync projects with disparate environments, tenants, lifecycles, channels, variable values, or deployment process steps, see [syncing multiple instances](/docs/administration/sync-instances) 1. To consolidate multiple Octopus Servers into a single Octopus Server, use the [Export/Import Projects feature](/docs/projects/export-import). -1. To audit your project configuration, see [configuration as code](/docs/projects/version-control). +1. To audit your project configuration, see [version control](/docs/projects/version-control). 1. To split a single space into multiple spaces, see the [Export/Import Projects feature](/docs/projects/export-import). 1. To migrate data from older versions of Octopus see [upgrading old versions of Octopus](/docs/administration/upgrading/legacy). 1. For general disaster recovery, learn about [backup and restore for your Octopus Server](/docs/administration/data/backup-and-restore). diff --git a/src/pages/docs/administration/migrate-spaces-with-octoterra/index.md b/src/pages/docs/administration/migrate-spaces-with-octoterra/index.md index 01957ed632..5ada77694f 100644 --- a/src/pages/docs/administration/migrate-spaces-with-octoterra/index.md +++ b/src/pages/docs/administration/migrate-spaces-with-octoterra/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2099-01-01 -modDate: 2099-01-01 +modDate: 2025-05-13 title: Migrating spaces with Octoterra description: How to migrate spaces using the octoterra tool navOrder: 100 @@ -28,7 +28,7 @@ The [Import/Export tool](https://octopus.com/docs/projects/export-import) is bui Typically, you would choose the Import/Export tool to perform a migration. However, there are cases where the Import/Export tool is not suitable: -* You wish to migrate Config-as-Code (CaC) projects, as the Import/Export tool does not support CaC projects. +* You wish to migrate version control enabled projects, as the Import/Export tool does not support version control enabled projects. * You wish to recreate targets, as the Import/Export tool does not migrate targets. * You wish to "own" or modify the intermediate format used for the migration, as the Import/Export tool uses an undocumented JSON format. @@ -56,13 +56,13 @@ Octoterra will display an error like this when an unsupported step is encountere Action has the "Items" property, which indicates that it is from the new step framework. These steps are not supported and are not exported. ``` -### Config-as-Code (CaC) repositories +### Version control enabled projects -Octoterra converts CaC projects back to regular projects as part of the migration. The project can be converted back to CaC on the destination space once the migration is complete. +Octoterra converts version control enabled projects back to regular projects as part of the migration. The project can be converted back to version control on the destination space once the migration is complete. -However, be aware that Octopus does not support sharing project CaC configuration between two projects. You are prevented from doing so with multiple CaC projects on a single Octopus instance. While you are not prevented from configuring two projects against a shared CaC project configuration from multiple Octopus instances, there are cases where the CaC configuration references space specific resource IDs, such as step templates, which have unique (and incompatible) IDs across spaces and instances. This means you can not assume you can configure a new project in a new space or on a new instance against an existing project CaC configuration hosted in Git. +However, be aware that Octopus does not support sharing project configuration between two projects. You are prevented from doing so with multiple version control enabled projects on a single Octopus instance. While you are not prevented from configuring two projects against a shared version control enabled project configuration from multiple Octopus instances, there are cases where the configuration references space specific resource IDs, such as step templates, which have unique (and incompatible) IDs across spaces and instances. This means you can not assume you can configure a new project in a new space or on a new instance against an existing project configuration hosted in Git. -The recommended solution is to convert the projects in the destination space to a new directory or Git repository. This ensures that the new projects have valid CaC configuration. +The recommended solution is to convert the projects in the destination space to a new directory or Git repository. This ensures that the new projects have valid configuration. ### Other settings @@ -318,12 +318,12 @@ A number of sensitive values can not be migrated by Octoterra including: All these values must be manually reconfigured on the destination server. -### Convert projects back to CaC +### Convert projects back to version control -CaC projects are converted back to regular projects during the migration. These projects must be manually converted back to CaC on the destination server. +Version control enabled projects are converted back to regular projects during the migration. These projects must be manually converted back to version control on the destination server. :::div{.warning} -You can not assume that you can point the projects back to their original configuration stored in Git. Values like step template IDs are hard coded in CaC configuration but are different between servers. Octopus also does not support pointing two projects to the same directory in a Git repository, so the source and destination servers can not reference the same Git repository and directory at the same time. +You can not assume that you can point the projects back to their original configuration stored in Git. Values like step template IDs are hard coded in configuration but are different between servers. Octopus also does not support pointing two projects to the same directory in a Git repository, so the source and destination servers can not reference the same Git repository and directory at the same time. ::: ### Migrate packages from built-in feed diff --git a/src/pages/docs/administration/private-cloud-migration/index.md b/src/pages/docs/administration/private-cloud-migration/index.md index c7269ed01c..7ad84cf35b 100644 --- a/src/pages/docs/administration/private-cloud-migration/index.md +++ b/src/pages/docs/administration/private-cloud-migration/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Private cloud migration description: Guidelines for migrating an on-premises Octopus instance to private cloud hosting navOrder: 55 @@ -177,7 +177,7 @@ Choose an incremental migration when: An incremental migration may not suitable when: * You require the complete audit history to be present on the cloud instance, as the export/import feature does not migrate audit events. -* You have a large number of Config-as-Code enabled projects, as the export/import feature does not export these projects. +* You have a large number of version control enabled projects, as the export/import feature does not export these projects. * You do not wish to reregister listening tentacles, as the new cloud instance has new certificates and will not be able to establish a connection to existing listening tentacles. * You have a large number of project triggers, as the export/import feature does not export triggers. * You have a large number of users and teams in the internal Octopus database, as these will have to be manually recreated. diff --git a/src/pages/docs/administration/sync-instances/index.md b/src/pages/docs/administration/sync-instances/index.md index 5e1c0a8e41..ae0887b27f 100644 --- a/src/pages/docs/administration/sync-instances/index.md +++ b/src/pages/docs/administration/sync-instances/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-10-04 +modDate: 2025-05-13 title: Sync multiple instances description: How to keep two or more Octopus Deploy instances in sync. navOrder: 45 @@ -48,7 +48,7 @@ In talking to users, the primary reason for splitting an instance is due to perm - Release managers can modify the variables on a set of tenants assigned to them. All other tenants are read-only. ### Approval process -Another reason we hear about is needing an approval process for changes to the deployment process. Please see our [config as code feature](/docs/projects/version-control) as that integrates with git, which allows for branching and pull requests. +Another reason we hear about is needing an approval process for changes to the deployment process. Please see our [version control feature](/docs/projects/version-control) as that integrates with git, which allows for branching and pull requests. ### Performance improvement The final reason we hear about is to "speed up the deployment." Typically we hear this when Octopus is located in one data center and deployment targets are located in a data center in another country or continent. That can lead to long package acquisition from the built-in repository and latency. @@ -62,7 +62,7 @@ The final reason we hear about is to "speed up the deployment." Typically we he Do not split an instance and sync it for any of the following use cases. -- You want an approval process for any changes to your deployment process. Please see our [config as code feature](/docs/projects/version-control) as that integrates with git. +- You want an approval process for any changes to your deployment process. Please see our [version control feature](/docs/projects/version-control) as that integrates with git. - You want to move a project from the default space to another space on the same instance (or different instance). Please see our documentation on our [Export/Import Projects feature](/docs/projects/export-import). - You want to create a test instance to test out upgrades or try out new processes. Please see our guide on [creating a test instance](/docs/administration/upgrading/guide/creating-test-instance) - You want to upgrade the underlying VM hosting Octopus Deploy from Windows Server 2012 to Windows Server 2019. Please see our guide on [moving the Octopus Server](/docs/administration/managing-infrastructure/moving-your-octopus/move-the-server). @@ -90,9 +90,9 @@ The Migrator and Export/Import Project feature can be run multiple times for the The [Octopus CLI](/docs/octopus-rest-api/octopus-cli/) includes the [export](/docs/octopus-rest-api/octopus-cli/export/) and [import](/docs/octopus-rest-api/octopus-cli/import) commands. Those commands are deprecated and should not be used. -### Config as Code and Octopus Terraform Provider +### Version Control and Octopus Terraform Provider -Terraform uses Hashicorp Configuration Language or HCL. The [Config as Code feature](/docs/projects/version-control) uses Octopus Configuration Language (OCL) and that is based on HCL. HCL does not support complex logic. That means you'd need a unique set of files per instance. To sync instances using these features, you'd need to use a comparison tool such as Beyond Compare to move changes between instances manually. Anything manual is error-prone and will eventually fail. +Terraform uses Hashicorp Configuration Language or HCL. The [version control feature](/docs/projects/version-control) uses Octopus Configuration Language (OCL) and that is based on HCL. HCL does not support complex logic. That means you'd need a unique set of files per instance. To sync instances using these features, you'd need to use a comparison tool such as Beyond Compare to move changes between instances manually. Anything manual is error-prone and will eventually fail. You can write a tool to compare files between instances automatically and make the necessary modifications. You will run into the a lot of the same roadblocks as below as you'll need to consider dependencies, environment mis-matches, and more. diff --git a/src/pages/docs/best-practices/deployments/projects-and-project-groups.md b/src/pages/docs/best-practices/deployments/projects-and-project-groups.md index 815babca89..b7a51205e2 100644 --- a/src/pages/docs/best-practices/deployments/projects-and-project-groups.md +++ b/src/pages/docs/best-practices/deployments/projects-and-project-groups.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-10-04 +modDate: 2025-05-13 title: Projects and Project Groups Structure description: Guidelines and recommendations for configuring projects and project groups in Octopus Deploy. navOrder: 50 @@ -29,7 +29,7 @@ All the components in a single "solution" or built in the same configuration sho If you want to have a project per component, you need to ensure each component is decoupled from one another and can be deployed on a separate schedule. :::div{.hint} -Previous versions of this guide recommended having a project per component. Octopus Deploy now includes new features, including ITSM integration, Config as Code, and more options for variable run conditions. There is also a logistical overhead with a project per component. That recommendation was made in 2021. At that time, a project per component made sense. It is no longer applicable with the 2023 version of Octopus Deploy. +Previous versions of this guide recommended having a project per component. Octopus Deploy now includes new features, including ITSM integration, version control, and more options for variable run conditions. There is also a logistical overhead with a project per component. That recommendation was made in 2021. At that time, a project per component made sense. It is no longer applicable with the 2023 version of Octopus Deploy. ::: ## Anti-patterns to avoid diff --git a/src/pages/docs/deployments/custom-scripts/run-a-script-step.md b/src/pages/docs/deployments/custom-scripts/run-a-script-step.md index 83f5a52572..68f65f71fb 100644 --- a/src/pages/docs/deployments/custom-scripts/run-a-script-step.md +++ b/src/pages/docs/deployments/custom-scripts/run-a-script-step.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-08-27 +modDate: 2025-05-13 title: Run a script step description: Standalone scripts allow you to run scripts contained in a package, in a git repository, or ad-hoc scripts you've saved as part of the step. icon: fa-regular fa-file-code @@ -58,7 +58,7 @@ Using scripts from inside a package or a git repository are a great way to versi ::: :::div{.hint} -If you are storing your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), you can source files from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the files. +If you are storing your project configuration in a Git repository using the [version control feature](/docs/projects/version-control), you can source files from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the files. You can find more information about this feature in this [blog post on using Git resources directly in deployments](https://octopus.com/blog/git-resources-in-deployments). ::: diff --git a/src/pages/docs/deployments/patterns/deployment-process-as-code.md b/src/pages/docs/deployments/patterns/deployment-process-as-code.md index 05a17db5d7..acccc37621 100644 --- a/src/pages/docs/deployments/patterns/deployment-process-as-code.md +++ b/src/pages/docs/deployments/patterns/deployment-process-as-code.md @@ -1,15 +1,15 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Deployment process as code description: With Octopus you can manage your deployment process as code. This means you can define your deployment process, scripts, and variables in source code. You can store this configuration in the same source control repository as your application source code, or somewhere else. This page describes the different options available in Octopus to store your deployment process as code. navOrder: 70 --- :::div{.hint} -**Looking for Configuration as Code?** -This section looks at storing your deployment process as code **without** using the [Configuration as Code](/docs/projects/version-control) feature. +**Looking for Version Control?** +This section looks at storing your deployment process as code **without** using the [Version Control](/docs/projects/version-control) feature. ::: With Octopus you can manage your deployment process as code. This means you can define your deployment process, scripts, and variables in source code. You can store this configuration in the same source control repository as your application source code, or somewhere else. @@ -66,7 +66,7 @@ Follow this process to move your Octopus project configuration to code: 1. Move your [deployment scripts to code](#scripts-as-code) and decide if you want to take this next step. 1. Convert your project configuration to code: learn about [configuring Octopus using code](#configure-octopus-using-code). -1. Test your project configuration as code, targeting a dummy project so your real project continues to work uninterrupted. +1. Test your project configuration, targeting a dummy project so your real project continues to work uninterrupted. 1. When you are happy with your testing, update your build pipeline to target the real project. 1. Train your people to make changes safely using **project as code**. @@ -82,15 +82,13 @@ The process flow of using **project as code** looks similar to what you already ### Configure Octopus using code {#configure-octopus-using-code} -Octopus has a comprehensive HTTP API and .NET SDK you can use to automate **everything** in Octopus. If you can do something through the user interface, you can automate it with code. You can create and update projects, variables, deployment processes, and more. A downside of this approach is how much work is involved: you need to write code that detects drift and applies deltas, or is idempotent. Today, this is our only fully-supported solution to define your Octopus configuration as code. +Octopus has a comprehensive HTTP API and .NET SDK you can use to automate **everything** in Octopus. If you can do something through the user interface, you can automate it with code. You can create and update projects, variables, deployment processes, and more. A downside of this approach is how much work is involved: you need to write code that detects drift and applies deltas, or is idempotent. There is an [open source Terraform provider for Octopus](https://github.com/OctopusDeploy/terraform-provider-octopusdeploy), which is built on top of the Octopus HTTP API. The Terraform provider for Octopus detects drift and applies deltas. We are using this Terraform provider ourselves for [Octopus Cloud](https://octopus.com/cloud) (our SaaS product), and we are actively contributing to the provider. It doesn't cover 100% of all Octopus features yet, and the structure of the Terraform resources are subject to change. We will be building first-class support for this into the Octopus ecosystem in the future. -If you want to do **Octopus configuration as code** today, we recommend using our .NET SDK which will always be supported. The Terraform provider will be a simpler, more declarative approach, that we will support in the future. - ### Consistency and repeatability using project as code -When managing your Octopus configuration as code, Octopus still makes sure your deployments are consistent and repeatable. Whenever you push a configuration change to your Octopus project via code, it's just like people using the user interface or API to make changes. When you create a release, Octopus takes a snapshot of the deployment process, variables, and packages making every deployment of that release consistent and repeatable, regardless of whether the project was configured by a person or by code. +When managing your Octopus configuration, Octopus still makes sure your deployments are consistent and repeatable. Whenever you push a configuration change to your Octopus project via code, it's just like people using the user interface or API to make changes. When you create a release, Octopus takes a snapshot of the deployment process, variables, and packages making every deployment of that release consistent and repeatable, regardless of whether the project was configured by a person or by code. This means you can push configuration changes to Octopus as code, and get the same consistent and repeatable experience you expect for your deployments. diff --git a/src/pages/docs/deployments/terraform/working-with-built-in-steps/index.md b/src/pages/docs/deployments/terraform/working-with-built-in-steps/index.md index 17201bda1f..35579a41f7 100644 --- a/src/pages/docs/deployments/terraform/working-with-built-in-steps/index.md +++ b/src/pages/docs/deployments/terraform/working-with-built-in-steps/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Terraform step configuration with Octopus navTitle: Terraform step configuration description: Configuring common Terraform options using the Octopus built in steps @@ -95,7 +95,7 @@ To configure Terraform steps to use a Git repository, select the `Git Repository #### Database projects -If you are storing your project configuration directly in Octopus (i.e. not in a Git repository using the [Configuration as code feature](/docs/projects/version-control)), you can source your files from a Git repository by entering the details of the repository directly on the step, including: +If you are storing your project configuration directly in Octopus (i.e. not in a Git repository using [version control](/docs/projects/version-control)), you can source your files from a Git repository by entering the details of the repository directly on the step, including: - URL - Credentials (either anonymous or selecting a Git credential from the Library) @@ -104,7 +104,7 @@ When creating a Release, you choose the tip of a branch for your files. The comm #### Version-controlled projects -If you are storing your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), in addition to the option above, you can source your files from the same Git repository as your deployment process by selecting **Project** as the Git repository source. When creating a Release using this option, the commit hash used for your deployment process will also be used to source the files. +If you are storing your project configuration in a Git repository using [version control](/docs/projects/version-control), in addition to the option above, you can source your files from the same Git repository as your deployment process by selecting **Project** as the Git repository source. When creating a Release using this option, the commit hash used for your deployment process will also be used to source the files. ### Variable replacements diff --git a/src/pages/docs/getting-started/index.mdx b/src/pages/docs/getting-started/index.mdx index c6632d7829..1d173d572c 100644 --- a/src/pages/docs/getting-started/index.mdx +++ b/src/pages/docs/getting-started/index.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-05-24 +modDate: 2025-05-13 title: Getting started with Octopus subtitle: An overview of Octopus Deploy concepts icon: fa-solid fa-octopus @@ -84,7 +84,7 @@ Octopus Deploy provides a range of built-in step templates that can be included Learn more about the [deployment process](/docs/projects/deployment-process/) and see some example [deployments](/docs/deployments). -The deployment process and many other parts of a project can be stored in a Git repository. Learn more about [Config as Code](/docs/projects/version-control). +The deployment process and many other parts of a project can be stored in a Git repository. Learn more about [version control](/docs/projects/version-control). ### Variables diff --git a/src/pages/docs/infrastructure/environments/index.mdx b/src/pages/docs/infrastructure/environments/index.mdx index bc417af21d..6baa820139 100644 --- a/src/pages/docs/infrastructure/environments/index.mdx +++ b/src/pages/docs/infrastructure/environments/index.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Environments description: Environments are how you group your deployment targets so you can promote your software through different phases, for instance, into Development, then Test, and finally into Production. navOrder: 20 @@ -66,7 +66,7 @@ This will let you search by: ## Removing environments -For projects using Config as Code, it's up to you to take care to avoid deleting any environments required by your deployments or runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. +For projects using version control, it's up to you to take care to avoid deleting any environments required by your deployments or runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. ## Learn more diff --git a/src/pages/docs/infrastructure/workers/worker-pools.md b/src/pages/docs/infrastructure/workers/worker-pools.md index 47208f77b2..5791481c55 100644 --- a/src/pages/docs/infrastructure/workers/worker-pools.md +++ b/src/pages/docs/infrastructure/workers/worker-pools.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Worker pools description: Worker pools are used to group workers and allow targeting steps at the pool of workers best equipped to execute the step. This page describes how to configure worker pools for a variety of scenarios. navOrder: 40 @@ -93,7 +93,7 @@ When a step is run on a worker, the following variables are available: ## Removing worker pools -For projects using Config as Code, it's up to you to take care to avoid deleting any worker pools required by your deployments or runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. +For projects using version control, it's up to you to take care to avoid deleting any worker pools required by your deployments or runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. ## Workers Q&A diff --git a/src/pages/docs/kubernetes/index.mdx b/src/pages/docs/kubernetes/index.mdx index 0c9cf28990..ed9cd639ed 100644 --- a/src/pages/docs/kubernetes/index.mdx +++ b/src/pages/docs/kubernetes/index.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-03-28 +modDate: 2025-05-13 title: Kubernetes deployments with Octopus navTitle: Overview navSection: Kubernetes @@ -74,7 +74,7 @@ When you’re ready to apply Octopus to a real scenario, we recommend that you: Learn more about deploying to multiple apps with Octopus, with these guides: - [Release triggers](/docs/projects/project-triggers/external-feed-triggers) and [channels](/docs/releases/channels) to automate deployments - [Step templates](/docs/projects/custom-step-templates) to create new pipelines with ease -- [Configuration as Code](/docs/projects/version-control) to manage deployment pipeline versions +- [Version control](/docs/projects/version-control) to manage deployment pipeline versions - [Users, roles, and teams](/docs/getting-started/best-practices/users-roles-and-teams) - Maintenance tasks with [runbooks](/docs/runbooks/) and [scripts](/docs/deployments/kubernetes/kubectl) diff --git a/src/pages/docs/kubernetes/steps/helm.md b/src/pages/docs/kubernetes/steps/helm.md index cfd212d5a4..9ed444adaa 100644 --- a/src/pages/docs/kubernetes/steps/helm.md +++ b/src/pages/docs/kubernetes/steps/helm.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-11-07 +modDate: 2025-05-13 title: Deploy a Helm chart description: Deploy a Helm chart to a Kubernetes cluster. navOrder: 30 @@ -65,7 +65,7 @@ To configure a Git Repository source, select the `Git Repository` option as your #### Database projects -If you are storing your project configuration directly in Octopus (i.e. not in a Git repository using the [Configuration as code feature](/docs/projects/version-control)), you can source your charts from a Git repository by entering the details of the repository, including: +If you are storing your project configuration directly in Octopus (i.e. not in a Git repository using the [version control feature](/docs/projects/version-control)), you can source your charts from a Git repository by entering the details of the repository, including: - URL - Credentials (either anonymous or selecting a Git credential from the Library) @@ -74,7 +74,7 @@ When creating a Release, you choose the tip of a branch for your Helm charts. Th #### Version-controlled projects -If you are storing your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), in addition to the option above, you can source your charts from the same Git repository as your deployment process by selecting **Project** as the Git repository source. When creating a Release using this option, the commit hash used for your deployment process will also be used to source the chart files. +If you are storing your project configuration in a Git repository using the [version control feature](/docs/projects/version-control), in addition to the option above, you can source your charts from the same Git repository as your deployment process by selecting **Project** as the Git repository source. When creating a Release using this option, the commit hash used for your deployment process will also be used to source the chart files. ## Helm upgrade step diff --git a/src/pages/docs/kubernetes/steps/kustomize.mdx b/src/pages/docs/kubernetes/steps/kustomize.mdx index d8c236c4cf..e6f6e6387e 100644 --- a/src/pages/docs/kubernetes/steps/kustomize.mdx +++ b/src/pages/docs/kubernetes/steps/kustomize.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-11-07 +modDate: 2025-05-13 title: Deploy with Kustomize description: Use Deploy with Kustomize to deploy resources to a Kubernetes cluster. navOrder: 40 @@ -95,5 +95,5 @@ The "`#{Octopus.Action.Package[nginx].PackageVersion}`" Octostache expression wi **2024.1:** - `Kustomize` was renamed to `Deploy with Kustomize`. -- If you store your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), you can source your Kustomize files from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the Kustomize files. You can learn more in [this blog post](https://octopus.com/blog/git-resources-in-deployments). +- If you store your project configuration in a Git repository using the [version control feature](/docs/projects/version-control), you can source your Kustomize files from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the Kustomize files. You can learn more in [this blog post](https://octopus.com/blog/git-resources-in-deployments). ::: \ No newline at end of file diff --git a/src/pages/docs/kubernetes/steps/yaml.md b/src/pages/docs/kubernetes/steps/yaml.md index 23929a4960..c2d520962a 100644 --- a/src/pages/docs/kubernetes/steps/yaml.md +++ b/src/pages/docs/kubernetes/steps/yaml.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-07-28 -modDate: 2024-11-07 +modDate: 2025-05-13 title: Deploy Kubernetes YAML description: Deploy Kubernetes YAML. navOrder: 20 @@ -65,7 +65,7 @@ To configure an inline YAML source, select the `Inline YAML` as your YAML Source ::: :::div{.warning} -This is **not** the recommended approach for advanced cases as it does not allow for version management unless you are using it in conjunction with [Config As Code](/docs/projects/version-control). +This is **not** the recommended approach for advanced cases as it does not allow for version management unless you are using it in conjunction with [version control](/docs/projects/version-control). ::: ## Referencing packages @@ -117,7 +117,7 @@ There are a few different ways to take advantage of this feature: **2024.1:** - `Deploy Raw Kubernetes YAML` was renamed to `Deploy Kubernetes YAML`. -- If you store your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), you can source your YAML from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the YAML files. You can learn more in [this blog post](https://octopus.com/blog/git-resources-in-deployments). +- If you store your project configuration in a Git repository using the [version control feature](/docs/projects/version-control), you can source your YAML from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the YAML files. You can learn more in [this blog post](https://octopus.com/blog/git-resources-in-deployments). **2023.3:** diff --git a/src/pages/docs/octopus-cloud/migrations.md b/src/pages/docs/octopus-cloud/migrations.md index efad1d8323..ea081a1ae8 100644 --- a/src/pages/docs/octopus-cloud/migrations.md +++ b/src/pages/docs/octopus-cloud/migrations.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Migrating to Octopus Cloud navOrder: 30 description: This guide outlines the benefits of Octopus Cloud, the effort involved in migrating, and step-by-step instructions to help you have a smooth transition. @@ -35,7 +35,7 @@ Before you start planning your migration, it’s worth setting some expectations | **Instance Size** | **Characteristics** | **Effort** | | ------------------------- | ---- | ----------- | -| Small and/or simple | | Migration typically takes 1-3 days with minimal manual configuration. | +| Small and/or simple | | Migration typically takes 1-3 days with minimal manual configuration. | | Medium | | Migration requires thorough planning, testing, and may take multiple weeks to migrate. | | Large or complex | | Migrations may take several weeks or months of preparation, testing, and execution. | @@ -257,7 +257,7 @@ In our experience, most people turn off their Octopus Server in about three to s ## Older versions - The **Export/Import Projects** feature is available from Octopus Deploy **2021.1** onwards. -- Prior to version **2025.2.5601**, Config-as-Code projects were not supported by the **Export/Import Projects** feature. +- Prior to version **2025.2.5601**, version control enabled projects were not supported by the **Export/Import Projects** feature. ## No longer offered or supported Please note that our existing [Migration API](https://octopus.com/docs/octopus-rest-api/migration-api) is **not supported** for migrations to cloud instances due to configuration differences between self-hosted and cloud installations. diff --git a/src/pages/docs/octopus-rest-api/cli/index.md b/src/pages/docs/octopus-rest-api/cli/index.md index 030fe7c04d..4a263da48a 100644 --- a/src/pages/docs/octopus-rest-api/cli/index.md +++ b/src/pages/docs/octopus-rest-api/cli/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: CLI description: The all-new Octopus CLI navOrder: 100 @@ -111,7 +111,7 @@ The Octopus CLI is built and maintained by the Octopus Deploy team, but it is al - **[octopus project branch list](/docs/octopus-rest-api/cli/octopus-project-branch-list)**: List project branches. - **[octopus project clone](/docs/octopus-rest-api/cli/octopus-project-clone)**: Clone a project. - **[octopus project connect](/docs/octopus-rest-api/cli/octopus-project-connect)**: Connect a tenant to a project. -- **[octopus project convert](/docs/octopus-rest-api/cli/octopus-project-convert)**: Convert a project to use Config As Code. +- **[octopus project convert](/docs/octopus-rest-api/cli/octopus-project-convert)**: Convert a project to use version control. - **[octopus project create](/docs/octopus-rest-api/cli/octopus-project-create)**: Create a project. - **[octopus project delete](/docs/octopus-rest-api/cli/octopus-project-delete)**: Delete a project. - **[octopus project disable](/docs/octopus-rest-api/cli/octopus-project-disable)**: Disable a project. diff --git a/src/pages/docs/octopus-rest-api/cli/octopus-project-convert.mdx b/src/pages/docs/octopus-rest-api/cli/octopus-project-convert.mdx index 388de25f19..f3c1043447 100644 --- a/src/pages/docs/octopus-rest-api/cli/octopus-project-convert.mdx +++ b/src/pages/docs/octopus-rest-api/cli/octopus-project-convert.mdx @@ -1,14 +1,14 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-05-07 +modDate: 2025-05-13 title: octopus project convert -description: Convert a project to use Config As Code +description: Convert a project to use version control navOrder: 89 --- import SamplesInstance from 'src/shared-content/samples/samples-instance.include.md'; -Convert a project to use Config As Code in Octopus Deploy +Convert a project to use version control in Octopus Deploy ``` Usage: diff --git a/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md b/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md index 18d37a68f4..9b2f718eb2 100644 --- a/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md +++ b/src/pages/docs/octopus-rest-api/octopus-cli/create-release.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-12-16 +modDate: 2025-05-13 title: Create release description: Using the Octopus CLI to create releases. navOrder: 100 @@ -203,7 +203,7 @@ octo create-release --project HelloWorld --version 1.0.3 --server https://your-o ## Version controlled projects -For projects that use the [Config as Code feature](/docs/projects/version-control) (they are version controlled), you can create a release pointing at a git reference, e.g. a branch name or tag. This example creates a release using the branch name of `main`: +For projects that use the [version control feature](/docs/projects/version-control), you can create a release pointing at a git reference, e.g. a branch name or tag. This example creates a release using the branch name of `main`: ```bash octo create-release --project HelloWorld --version 1.0.3 --server https://your-octopus-url --apiKey API-YOUR-KEY --gitRef main diff --git a/src/pages/docs/platform-engineering/forking-git-repos.md b/src/pages/docs/platform-engineering/forking-git-repos.md index e8670f717d..0cf4ea450a 100644 --- a/src/pages/docs/platform-engineering/forking-git-repos.md +++ b/src/pages/docs/platform-engineering/forking-git-repos.md @@ -1,15 +1,15 @@ --- layout: src/layouts/Default.astro pubDate: 2023-11-09 -modDate: 2023-11-09 +modDate: 2025-05-13 title: Forking Git repositories -description: Learn how to fork repositories when deploying a copy of CaC projects +description: Learn how to fork repositories when deploying a copy of version control enabled projects navOrder: 7 --- -[Serializing and deploying CaC enabled projects](https://www.youtube.com/watch?v=VGgR4PuWvOQ) +[Serializing and deploying version control enabled projects](https://www.youtube.com/watch?v=VGgR4PuWvOQ) -Octopus does not support two Config-as-Code (CaC) enabled projects pointing to the same Git repository. This means you must fork the Git repository hosting the upstream project and then point the downstream project to the new fork. +Octopus does not support two version control enabled projects pointing to the same Git repository. This means you must fork the Git repository hosting the upstream project and then point the downstream project to the new fork. The `GitHub - Fork Repo` step from the community step template library automates the process of forking repositories in GitHub. @@ -17,9 +17,9 @@ The `GitHub - Fork Repo` step from the community step template library automates Other Git platforms may have CLI tools that allow repositories to be forked. ::: -The typical process used to deploy an upstream CaC project serialized with octoterra is to run a step like `GitHub - Fork Repo` to fork the upstream Git repository before the `Octopus - Populate Octoterra Space` step. This ensures a new Git repository has been created for the downstream project. +The typical process used to deploy an upstream version control enabled project serialized with octoterra is to run a step like `GitHub - Fork Repo` to fork the upstream Git repository before the `Octopus - Populate Octoterra Space` step. This ensures a new Git repository has been created for the downstream project. -A CaC enabled project exported by octoterra exposes the CaC Git url as a Terraform variable. The variable is based on the name of the upstream project and ends with the `_git_url` suffix e.g. `project_frontend_webapp_git_url`. +A version control enabled project exported by octoterra exposes the Git url as a Terraform variable. The variable is based on the name of the upstream project and ends with the `_git_url` suffix e.g. `project_frontend_webapp_git_url`. -The default value of this variable is the upstream project's CaC Git repository. This Terraform variable must be defined when running the `Octopus - Populate Octoterra Space` by adding it to the `Terraform Additional Apply Params` field e.g `-var=project_frontend_webapp_git_url=#{Octopus.Action[GitHub - Fork Repo].Output.NewRepo}`. +The default value of this variable is the upstream project's Git repository. This Terraform variable must be defined when running the `Octopus - Populate Octoterra Space` by adding it to the `Terraform Additional Apply Params` field e.g `-var=project_frontend_webapp_git_url=#{Octopus.Action[GitHub - Fork Repo].Output.NewRepo}`. diff --git a/src/pages/docs/platform-engineering/levels-of-responsibility.md b/src/pages/docs/platform-engineering/levels-of-responsibility.md index dd32579fb2..e93656e504 100644 --- a/src/pages/docs/platform-engineering/levels-of-responsibility.md +++ b/src/pages/docs/platform-engineering/levels-of-responsibility.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Managing Octopus with code description: This section describes the levels of responsibility that define how projects are managed over time. navOrder: 3 @@ -25,9 +25,9 @@ This is also called the eventual inconsistency model because the upstream and do ## Shared responsibility model -The shared responsibility model relies on Git based workflows to merge changes between forked Git repositories backing Config-as-Code (CaC) projects. +The shared responsibility model relies on Git based workflows to merge changes between forked Git repositories backing version control enabled projects. -Because the two CaC repos are forks of each other, they share the same Git history, and processes like Git merges can be used to synchronize changes between these repositories over time. +Because the two version control repos are forks of each other, they share the same Git history, and processes like Git merges can be used to synchronize changes between these repositories over time. This is also called the eventual consistency model because the upstream and downstream artifacts are expected to drift but have the option to incorporate any important changes. diff --git a/src/pages/docs/platform-engineering/listing-downstream-drift.md b/src/pages/docs/platform-engineering/listing-downstream-drift.md index 5dd13ab13c..7cbf4ebdd4 100644 --- a/src/pages/docs/platform-engineering/listing-downstream-drift.md +++ b/src/pages/docs/platform-engineering/listing-downstream-drift.md @@ -1,27 +1,27 @@ --- layout: src/layouts/Default.astro pubDate: 2023-11-09 -modDate: 2023-11-09 +modDate: 2025-05-13 title: Finding drift -description: Learn how to scan downstream CaC repos for drift +description: Learn how to scan downstream version control repos for drift navOrder: 8 --- -When upstream and downstream projects are [configured with CaC and backed by forked repositories](forking-git-repos) it becomes possible to track drift. +When upstream and downstream projects are [configured with version control and backed by forked repositories](forking-git-repos) it becomes possible to track drift. -The `Octopus - Find CaC Updates` steps detect drift by: +The `Octopus - Find Version Control Updates` steps detect drift by: 1. Scanning the workspaces in the Terraform state created when deploying downstream projects -2. Finding any CaC enabled projects +2. Finding any version control enabled projects 3. Cloning the downstream Git repo 4. Checking to see if there are changes to merge from the upstream repo into the downstream repo, and if any merges introduce conflicts -Each `Octopus - Find CaC Updates` step is configured with a specific Terraform backend. For example, the `Octopus - Find CaC Updates (S3 Backend)` step is configured to read Terraform state persisted in an S3 bucket. +Each `Octopus - Find Version Control Updates` step is configured with a specific Terraform backend. For example, the `Octopus - Find Version Control Updates (S3 Backend)` step is configured to read Terraform state persisted in an S3 bucket. -The `Octopus - Find CaC Updates` steps are typically defined in a runbook attached to the upstream project: +The `Octopus - Find Version Control Updates` steps are typically defined in a runbook attached to the upstream project: -1. Create a runbook called `__ Find CaC Updates` attached to the upstream project. -2. Add one of the `Octopus - Find CaC Updates` steps. +1. Create a runbook called `__ Find Version Control Updates` attached to the upstream project. +2. Add one of the `Octopus - Find Version Control Updates` steps. 1. Run the step on a worker with a recent version of Terraform installed or set the container image to a Docker image with Terraform installed like `octopuslabs/terraform-workertools`. 2. Set the `Git Username` field to the Git repository username. GitHub users with access tokens set this field to `x-access-token`. 3. Set the `Git Password` field to the Git repository password or access token. @@ -29,7 +29,7 @@ The `Octopus - Find CaC Updates` steps are typically defined in a runbook attach 5. Set the `Git Hostname` field to the Git repository host name e.g. `github.com`, `gitlab.com`, `bitbucket.com`. 6. Set the `Git Organization` field to the Git repository owner or organization. 7. Set the `Git Template Repo` field to the Git repository hosting the upstream project. - 8. Each `Octopus - Find CaC Updates` step then defines additional fields related to the specific Terraform backend. For example, the `Octopus - Find CaC Updates (S3 Backend)` step has fields for AWS credentials, region, bucket, and key. + 8. Each `Octopus - Find Version Control Updates` step then defines additional fields related to the specific Terraform backend. For example, the `Octopus - Find Version Control Updates (S3 Backend)` step has fields for AWS credentials, region, bucket, and key. Executing the runbook will display a list of downstream projects and indicate if they are: diff --git a/src/pages/docs/platform-engineering/managing-project-resources.md b/src/pages/docs/platform-engineering/managing-project-resources.md index 2ad8abb55a..8e2d5498c8 100644 --- a/src/pages/docs/platform-engineering/managing-project-resources.md +++ b/src/pages/docs/platform-engineering/managing-project-resources.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Managing project resources description: This section documents how to manage project level resources as code. navOrder: 5 @@ -24,11 +24,11 @@ Managed, or downstream, spaces (i.e. spaces with centrally managed resources) ar There are two ways to manage project level resources: * Define database backed projects, complete with all deployment steps, with Terraform -* Define the configuration of a [Config-as-code](/docs/projects/version-control) (CaC) project with Terraform, while deferring the configuration of CaC managed settings like the deployment process, non-secret variables, and some project settings to configuration stored in Git +* Define the configuration of a [version control](/docs/projects/version-control) enabled project with Terraform, while deferring the configuration of managed settings like the deployment process, non-secret variables, and some project settings to configuration stored in Git Defining database backed projects in Terraform is useful for [centralized responsibility](levels-of-responsibility) projects where the customer has little or no ability to modify the project, or [customer responsibility](levels-of-responsibility) projects where projects are not centrally updated after they are created. -Defining CaC projects is useful for [shared responsibility](levels-of-responsibility) projects where deployment processes can be modified by customers and the platform team, with differences reconciled with Git merges. +Defining version control enabled projects is useful for [shared responsibility](levels-of-responsibility) projects where deployment processes can be modified by customers and the platform team, with differences reconciled with Git merges. Project level resources can be defined in a Terraform module in two ways: @@ -189,7 +189,7 @@ The following steps create a project in an existing space with the Terraform mod 4. Set the `Octopus Server URL` field to the URL of the Octopus server to create the new project in. The default value of `#{Octopus.Web.ServerUri}` references the URL of the current Octopus instance. 5. Set the `Octopus API Key` field to the [API key](/docs/octopus-rest-api/how-to-create-an-api-key) used when accessing the instance defined in the `Octopus Server URL` field. 6. Set the `Octopus Space ID` field to the ID of an existing space where the project will be created. - 7. Set the `Terraform Additional Apply Params` field to a list of additional arguments to pass to the `terraform apply` command. This field is typically used to define the value of secrets such as secret variables e.g. `-var=eks_octopub_frontend_my_secret_1=TheSecretValue`. It is also useful to override the Git repository for a CaC enabled project, as [projects can not share Git repositories](/docs/projects/version-control/config-as-code-reference) e.g. `-var=project_frontend_webapp_git_url=http://github.com/username/project`. + 7. Set the `Terraform Additional Apply Params` field to a list of additional arguments to pass to the `terraform apply` command. This field is typically used to define the value of secrets such as secret variables e.g. `-var=eks_octopub_frontend_my_secret_1=TheSecretValue`. It is also useful to override the Git repository for a version control enabled project, as [projects can not share Git repositories](/docs/projects/version-control/version-control-reference) e.g. `-var=project_frontend_webapp_git_url=http://github.com/username/project`. 8. Set the `Terraform Additional Init Params` field to a list of additional arguments to pass to the `terraform init` command. Leave this field blank unless you have a specific reason to pass an argument to Terraform. 9. Each `Octopus - Populate Octoterra Space` step exposes values relating to their specific Terraform backend that must be configured. For example, the `Octopus - Populate Octoterra Space (S3 Backend)` step exposes fields to configure the S3 bucket, key, and region where the Terraform state is saved. Other steps have similar fields. diff --git a/src/pages/docs/platform-engineering/managing-runbook-resources.md b/src/pages/docs/platform-engineering/managing-runbook-resources.md index 94aaec8449..6cbe5ba4d7 100644 --- a/src/pages/docs/platform-engineering/managing-runbook-resources.md +++ b/src/pages/docs/platform-engineering/managing-runbook-resources.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-11-09 -modDate: 2023-11-09 +modDate: 2025-05-13 title: Managing runbook resources description: This section documents how to manage runbooks as code. navOrder: 6 @@ -16,7 +16,7 @@ However, it can be useful to treat runbooks as an independently deployable artif Runbooks can be defined as a Terraform module and applied to an existing project, effectively "deploying" the runbook into the project. :::div{.hint} -Runbooks are not managed by Config-as-code. +Runbooks are not managed with version control. ::: Runbooks can be defined in a Terraform module in two ways: diff --git a/src/pages/docs/platform-engineering/managing-space-resources.md b/src/pages/docs/platform-engineering/managing-space-resources.md index 297aeb0003..4c77589355 100644 --- a/src/pages/docs/platform-engineering/managing-space-resources.md +++ b/src/pages/docs/platform-engineering/managing-space-resources.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-11-30 +modDate: 2025-05-13 title: Managing space resources description: This section documents how to manage space level resources as code. navOrder: 4 @@ -24,7 +24,7 @@ Managed, or downstream, spaces (i.e. spaces with centrally managed resources) ar Space level resources are best managed with the [Octopus Terraform provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs). :::div{.hint} -[Config-as-code](/docs/projects/version-control) only supports persisting a subset of project settings in a Git repository, and can not be used to define space level resources. +[Version control](/docs/projects/version-control) only supports persisting a subset of project settings in a Git repository, and can not be used to define space level resources. ::: Space level resources can be defined in a Terraform module in two ways: diff --git a/src/pages/docs/platform-engineering/merging-downstream.md b/src/pages/docs/platform-engineering/merging-downstream.md index 8a9c55c922..ad717a8123 100644 --- a/src/pages/docs/platform-engineering/merging-downstream.md +++ b/src/pages/docs/platform-engineering/merging-downstream.md @@ -1,28 +1,28 @@ --- layout: src/layouts/Default.astro pubDate: 2023-11-09 -modDate: 2023-11-09 +modDate: 2025-05-13 title: Merging repos description: Learn how to merge changes to downstream repos navOrder: 9 --- -When upstream and downstream projects are [configured with CaC and backed by forked repositories](forking-git-repos) it becomes possible to merge changes from upstream to downstream repositories. +When upstream and downstream projects are [configured with version control and backed by forked repositories](forking-git-repos) it becomes possible to merge changes from upstream to downstream repositories. -The `Octopus - Merge CaC Updates` steps merges changes by: +The `Octopus - Merge Version Control Updates` steps merges changes by: 1. Scanning the workspaces in the Terraform state created when deploying downstream projects -2. Finding any CaC enabled projects +2. Finding any version control enabled projects 3. Cloning the downstream Git repository 4. Adding the upstream repo as a remote repository 5. Merging changes from the upstream repo to the downstream repository -Each `Octopus - Merge CaC Updates` step is configured with a specific Terraform backend. For example, the `Octopus - Merge CaC Updates (S3 Backend)` step is configured to read Terraform state persisted in an S3 bucket. +Each `Octopus - Merge Version Control Updates` step is configured with a specific Terraform backend. For example, the `Octopus - Merge Version Control Updates (S3 Backend)` step is configured to read Terraform state persisted in an S3 bucket. -The `Octopus - Merge CaC Updates` steps are typically defined in a runbook attached to the upstream project: +The `Octopus - Merge Version Control Updates` steps are typically defined in a runbook attached to the upstream project: -1. Create a runbook called `__ Merge CaC Updates` attached to the upstream project. -2. Add one of the `Octopus - Merge CaC Updates` steps. +1. Create a runbook called `__ Merge Version Control Updates` attached to the upstream project. +2. Add one of the `Octopus - Merge Version Control Updates` steps. 1. Run the step on a worker with a recent version of Terraform installed or set the container image to a Docker image with Terraform installed like `octopuslabs/terraform-workertools`. 2. Set the `Octopus Spaces` field to a newline-separated list of downstream space names containing projects to update. Leave the field blank to process all downstream spaces. The default value of `#{Octopus.Deployment.Tenant.Name}` assumes the step is run against a tenant and the tenant name matches the space name. 3. Set the `Octopus Projects` field to a newline-separated list of downstream project names to process. Leave the field blank to process all downstream projects. @@ -32,6 +32,6 @@ The `Octopus - Merge CaC Updates` steps are typically defined in a runbook attac 7. Set the `Git Hostname` field to the Git repository host name e.g. `github.com`, `gitlab.com`, `bitbucket.com`. 8. Set the `Git Organization` field to the Git repository owner or organization. 9. Set the `Git Template Repo` field to the Git repository hosting the upstream project. - 10. Each `Octopus - Merge CaC Updates` step then defines additional fields related to the specific Terraform backend. For example, the `Octopus - Merge CaC Updates (S3 Backend)` step has fields for AWS credentials, region, bucket, and key. + 10. Each `Octopus - Merge Version Control Updates` step then defines additional fields related to the specific Terraform backend. For example, the `Octopus - Merge Version Control Updates (S3 Backend)` step has fields for AWS credentials, region, bucket, and key. Executing the runbook will merge upstream changes into downstream repositories or print instructions on manually resolving merge conflicts in the verbose logs. \ No newline at end of file diff --git a/src/pages/docs/platform-engineering/validating-cac-prs.md b/src/pages/docs/platform-engineering/validating-cac-prs.md index 894beb3c36..08a8555527 100644 --- a/src/pages/docs/platform-engineering/validating-cac-prs.md +++ b/src/pages/docs/platform-engineering/validating-cac-prs.md @@ -1,25 +1,25 @@ --- layout: src/layouts/Default.astro pubDate: 2023-11-09 -modDate: 2023-11-09 -title: Validating CaC PRs -description: Learn how to automatically validate pull requests in a CaC Git repository +modDate: 2025-05-13 +title: Validating Version Control PRs +description: Learn how to automatically validate pull requests in a Git repository navOrder: 10 --- One of the challenges when implementing the [shared responsibility (or eventual consistency) model](levels-of-responsibility) is the potential for complex conflicts to be introduced to the downstream repositories. Without any controls on what changes can be made to a downstream project, it may become impractical to continue to push changes downstream. -One way to constrain the changes introduced to downstream CaC Git repositories is to automatically validate changes during a pull request (PR). This allows the platform team to introduce minimum requirements that all downstream CaC projects must adhere to while also allowing internal customers to customize their projects. +One way to constrain the changes introduced to downstream Git repositories is to automatically validate changes during a pull request (PR). This allows the platform team to introduce minimum requirements that all downstream version control enabled projects must adhere to while also allowing internal customers to customize their projects. ## Parsing OCL -CaC projects persist their configuration in the [Octopus Configuration Language (OCL)](/docs/projects/version-control/ocl-file-format). This format is parsed by the [`@octopusdeploy/ocl`](https://github.com/OctopusDeploy/ocl.ts) JavaScript library. +Version control enabled projects persist their configuration in the [Octopus Configuration Language (OCL)](/docs/projects/version-control/ocl-file-format). This format is parsed by the [`@octopusdeploy/ocl`](https://github.com/OctopusDeploy/ocl.ts) JavaScript library. The `@octopusdeploy/ocl` library offers a low level parser that exposes individual OCL tokens. In addition, the library exposes a wrapper that allows the OCL data structure to be accessed via a read-only JavaScript object. This wrapped object can then be passed to any JavaScript library used to compare values or validate objects. ## Validating PRs with GitHub Actions -The workflow shown below is an example that combines the `@octopusdeploy/ocl` and `expect` libraries to verify that the merge result of a CaC Git repository meets certain minimum requirements: +The workflow shown below is an example that combines the `@octopusdeploy/ocl` and `expect` libraries to verify that the merge result of a Git repository meets certain minimum requirements: ```yaml on: pull_request_target @@ -43,7 +43,7 @@ jobs: const {expect} = require("expect"); /** - * This function performs the validation of the Octopus CaC OCL file + * This function performs the validation of the Octopus OCL file * @param ocl The OCL file to parse */ function checkPr(ocl) { @@ -116,7 +116,7 @@ The verification logic is defined in the function called `checkPr` whose paramet ```javascript /** - * This function performs the validation of the Octopus CaC OCL file + * This function performs the validation of the Octopus OCL file * @param ocl The OCL file to parse */ function checkPr(ocl) { @@ -187,7 +187,7 @@ The example below embeds a step OCL snippet as a string, parses the string, and }` /** - * This function performs the validation of the Octopus CaC OCL file + * This function performs the validation of the Octopus OCL file * @param ocl The OCL file to parse */ function checkPr(ocl) { @@ -237,7 +237,7 @@ This example uses the [`lodash`](https://lodash.com/) library to clone the wrapp }` /** - * This function performs the validation of the Octopus CaC OCL file + * This function performs the validation of the Octopus OCL file * @param ocl The OCL file to parse */ function checkPr(ocl) { diff --git a/src/pages/docs/platform-engineering/what-is-pe.md b/src/pages/docs/platform-engineering/what-is-pe.md index b0a788e48c..dfebcc9fb2 100644 --- a/src/pages/docs/platform-engineering/what-is-pe.md +++ b/src/pages/docs/platform-engineering/what-is-pe.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: What is platform engineering? description: A brief overview of what platform engineering is. navOrder: 1 @@ -21,4 +21,4 @@ While platform engineering is not limited to CI/CD pipelines, CI/CD platforms pr * They manage execution environments in which to run automated tasks * They already have access to existing DevOps systems -Octopus can function as an IDP through a combination of IaC (with the [Terraform provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs)), Git based workflows (with [Config-as-code](/docs/projects/version-control)), and specially designed step templates to deploy and track changes to deployment projects and runbooks. \ No newline at end of file +Octopus can function as an IDP through a combination of IaC (with the [Terraform provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs)), Git based workflows (with [version control](/docs/projects/version-control)), and specially designed step templates to deploy and track changes to deployment projects and runbooks. \ No newline at end of file diff --git a/src/pages/docs/projects/custom-step-templates.md b/src/pages/docs/projects/custom-step-templates.md index ec17611e10..42cc38d648 100644 --- a/src/pages/docs/projects/custom-step-templates.md +++ b/src/pages/docs/projects/custom-step-templates.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Custom step templates icon: fa-solid fa-shapes description: How to create reusable steps @@ -122,7 +122,7 @@ Be careful when changing names. Octopus commonly uses names as a convenient iden ## Removing step templates -For projects using Config as Code, it's up to you to take care to avoid deleting any step templates required by your deployments or runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. +For projects using version control, it's up to you to take care to avoid deleting any step templates required by your deployments or runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. ## Learn more diff --git a/src/pages/docs/projects/index.mdx b/src/pages/docs/projects/index.mdx index 20f9e9cecf..0b40bb1a5e 100644 --- a/src/pages/docs/projects/index.mdx +++ b/src/pages/docs/projects/index.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-05-24 +modDate: 2025-05-13 title: Projects subtitle: Projects gather together all the processes, releases, and runbooks for an application or service. icon: fa-solid fa-diagram-project @@ -51,7 +51,7 @@ Get started with the basics of [setting up a project](/docs/projects/setting-up- - [Tenants](/docs/projects/tenants) - [Project triggers](/docs/projects/project-triggers) - [Coordinating multiple projects](/docs/projects/coordinating-multiple-projects) -- [Configuration as Code](/docs/projects/version-control) +- [Version Control](/docs/projects/version-control) ## Steps - [Steps](/docs/projects/steps) diff --git a/src/pages/docs/projects/project-triggers/external-feed-triggers.md b/src/pages/docs/projects/project-triggers/external-feed-triggers.md index c1d7c98c62..5283ae70d5 100644 --- a/src/pages/docs/projects/project-triggers/external-feed-triggers.md +++ b/src/pages/docs/projects/project-triggers/external-feed-triggers.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-03-21 -modDate: 2024-08-28 +modDate: 2025-05-13 title: External feed triggers in Octopus navTitle: External feed triggers icon: fa-solid fa-arrow-up-right-from-square @@ -53,7 +53,7 @@ A preview of the [lifecycle](/docs/releases/lifecycles) used by the selected cha Any container images or Helm Charts referenced in your project's deployment process can be selected to trigger release creation. -Please note that for [configuration as code](/docs/projects/version-control/config-as-code-reference) projects, only container images and Helm Charts in the deployment process from the **default branch** are able to be referenced. Any changes to the deployment process in other branches will not be available for use in external feed triggers. +Please note that for [version control](/docs/projects/version-control/version-control-reference) enabled projects, only container images and Helm Charts in the deployment process from the **default branch** are able to be referenced. Any changes to the deployment process in other branches will not be available for use in external feed triggers. :::figure ![Package selection](/docs/projects/project-triggers/images/external-feed-trigger-packages.png) @@ -100,7 +100,7 @@ When you are using external feed triggers there are a few reasons why a release 7. If you have a **chain of package dependencies** with your external feed packages, make sure your trigger uses the package which will be **pushed to its repository last**. Otherwise some of the packages required for the release may be missing. -8. As [mentioned above](/docs/projects/project-triggers/external-feed-triggers#trigger-sources), for [configuration as code](/docs/projects/version-control/config-as-code-reference) projects, only container images and Helm Charts in the deployment process from the **default branch** are able to be referenced. Any changes to the deployment process in other branches will not be available for use in external feed triggers. +8. As [mentioned above](/docs/projects/project-triggers/external-feed-triggers#trigger-sources), for [version control](/docs/projects/version-control/version-control-reference) enabled projects, only container images and Helm Charts in the deployment process from the **default branch** are able to be referenced. Any changes to the deployment process in other branches will not be available for use in external feed triggers. ## Learn more diff --git a/src/pages/docs/projects/project-triggers/git-triggers.md b/src/pages/docs/projects/project-triggers/git-triggers.md index a9c0f444ff..4af5c1073d 100644 --- a/src/pages/docs/projects/project-triggers/git-triggers.md +++ b/src/pages/docs/projects/project-triggers/git-triggers.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-11-05 -modDate: 2024-11-05 +modDate: 2025-05-13 title: Git repository triggers description: Git repository triggers allow you to automatically create a new release when a new commit is pushed to a Git repository. navOrder: 16 @@ -32,7 +32,7 @@ A preview of the [lifecycle](/docs/releases/lifecycles) used by the selected cha Git repositories referenced in your project's deployment process can be selected to be monitored by the trigger to create releases. -Please note that for [configuration as code](/docs/projects/version-control/config-as-code-reference) projects, only steps that reference Git repositories in the deployment process from the **default branch** are able to be referenced. Any changes to the deployment process in other branches will not be available for use in git triggers. +Please note that for [version control](/docs/projects/version-control/version-control-reference) enabled projects, only steps that reference Git repositories in the deployment process from the **default branch** are able to be referenced. Any changes to the deployment process in other branches will not be available for use in git triggers. :::figure ![Repository selection](/docs/projects/project-triggers/images/git-triggers/git-triggers-repository-selection.png) diff --git a/src/pages/docs/projects/version-control/config-as-code-reference.mdx b/src/pages/docs/projects/version-control/config-as-code-reference.mdx index 4050d8260e..7855359568 100644 --- a/src/pages/docs/projects/version-control/config-as-code-reference.mdx +++ b/src/pages/docs/projects/version-control/config-as-code-reference.mdx @@ -1,338 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2024-09-16 -title: Configuration as Code reference -description: Details about the configuration as code feature. -navOrder: 20 -icon: fa-brands fa-git-alt +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/projects/version-control/version-control-reference +pubDate: 2025-05-09 +navSearch: false +navSitemap: false +navMenu: false --- -import VersionControlRepositoryUrlFormat from 'src/shared-content/version-control-repository-url-format.include.md'; - -The configuration as code feature enables you to save some project-level settings as files in a Git repository instead of SQL Server. The files are written in the OCL (Octopus Configuration Language) format. Storing resources as files lets you leverage version control features such as branching, pull requests, and reverting changes. In addition, you can save both your source code and how you deploy your code in the same Git repository. This page is a reference document of how the config-as-code feature works. - -## Octopus project level only - -The config-as-code feature will store Octopus Project resources in Git instead of SQL Server. - -### Project resources version controlled - -Currently, the Project level resources saved to Git are: - -- Deployment Process -- Deployment Settings - - Release Versioning - - Release Notes Template - - Deployment Targets Required - - Transient Deployment Targets - - Deployment Changes Template - - Default Failure Mode -- Runbook Process -- Runbook Settings - - Multi-tenancy Mode - - Run Retention Policy - - Connectivity Policy - - Default Failure Mode -- Variables (excluding Sensitive variables) - -:::div{.hint} -Sensitive variables are still stored in the database. Regardless of the current branch, you will always see the same set of sensitive variables. -::: - -### Project resources saved to SQL Server - -Currently, the Project level resources saved to SQL Server when version control is enabled are: - -- Channels -- Triggers -- Releases -- Deployments -- Sensitive Variables -- General Settings - - Project Name - - Enabled / Disabled - - Logo - - Description - - Project Group - -:::div{.hint} -Sensitive Variables are planned for future releases of config-as-code. -::: - -### Resources **not** version controlled by config-as-code - -The config-as-code feature manages project-level resources. However, it is worth explicitly mentioning some things that are **not included**: - -- Infrastructure - - Environments - - Deployment Targets - - Workers - - Worker Pools - - Machine Policies - - Machine Proxies - - Accounts -- Tenants -- Library - - Certificates - - External Feeds - - Lifecycles - - Packages - - Build Information - - Script Modules - - Step Templates - - Variable Sets -- Server Configuration - - Feature Flags - - License - - Node Settings (Task Cap and Server Uri) - - Issue Tracker Settings - - External Auth Provider Settings - - SMTP - - Spaces - - Teams (both membership and role assignment) - - Users - - User Roles - -Currently, there are no plans to include these resources in the config-as-code feature. Several of the resources above can be put into version control using the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs). - -:::div{.hint} -Resources managed by the Octopus Terraform Provider will have their state managed by Terraform. Resources managed by the Octopus config-as-code feature will have the state managed by Octopus Deploy. The two are not the same and shouldn't be treated as such. -::: - -## Git configuration options - -Project version control settings can be accessed by clicking on the **Settings ➜ Version Control** link on the project navigation menu. - -### Git repository - -The _Git Repository_ field should contain the URL for the repository you wish the Octopus configuration to be persisted to. e.g. `https://github.com/OctopusSamples/OctoFX.git` - - - -The repository must be initialized (i.e. contain at least one branch) prior to saving. Octopus will convert the existing items in the project to OCL (Octopus Configuration Language) and save it to that repository when you click save. If the repository isn't initialized, that will fail. - -### Authentication - -The config-as-code feature is designed to work with _any_ Git repository. When configuring a project to be version-controlled, you can optionally provide credentials for authentication. - -:::div{.hint} -Do not use credentials from a personal account. Select a shared or service account. When Octopus Deploy saves to your Git repo, you will typically see the message `[User Name] authored and [Service Account] committed on [Date].` -::: - -For the Password field, we recommend using a personal access token. We also recommend that you follow the principle of least privilege when selecting scopes or permissions to grant this personal access token. - -Git providers allow you to create an access token in different ways. The recommended _scope_ for each provider is listed in brackets. - -- [GitHub - Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token); (Permission - `Contents - Read and Write`) -- [GitHub - Creating a personal access token (Classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic); (Scope - `repo`) -- [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate); (Scope - `vso.code_full`) -- [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html); (Scope - `write_repository`) -- [BitBucket Server](https://confluence.atlassian.com/bitbucketserver063/personal-access-tokens-972354166.html); (Permission - `Project admin`) -- [BitBucket Cloud - Use App Passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/); (Permission - `Repositories - Read & Write`) - -:::div{.hint} -Some VCS providers require that you use only a username and personal access token for authentication, not an email address (i.e. BitBucket). -::: - -#### BitBucket repository access tokens -BitBucket's repository access tokens allow you to create repository-specific access tokens. For these to work with your Git repositories in Octopus, you must set the username to `x-token-auth`, and the password to the token. - -:::figure -![Screenshot of Octopus Version Control Settings page with Authentication section expanded. Username/password auth method is selected, the Username input field is highlighted with a bold red box, and contains the value x-token-auth](/docs/projects/version-control/octopus-bitbucket-repository-access-tokens.png) -::: - -### File storage - -_Git File Storage Directory_ specifies the path within the repository where the Octopus configuration will be stored. The default directory is `.octopus`, but that can be changed. If only a single Octopus project will be stored in the repo, we recommend putting the configuration directly under the `.octopus` directory. - -:::div{.hint} -If multiple projects will be persisted to the repository, adding the project name to the path is the recommended convention, e.g. `./octopus/acme` -::: - -We recommend storing projects alongside the application code. While it is possible to store all your deployment projects in a single central repository with folders for each project, it will be challenging to manage as you add more projects. For example, if you have multiple component projects, one for Web UI, another for Web API, etc., but the source code is in one repository, then store all the component projects in that repository. If you move the application code later, you can also [move the deployment configuration](/docs/projects/version-control/moving-version-control) to keep it with the application. - -### Branch settings - -#### Default branch name - -The _Default Branch Name_ is the branch on which the Octopus configuration will be written. It is also the default branch that will be used in various situations, for example: - -- When users view the project's deployment process for the first time in the Octopus UI, this is the initially selected branch -- When creating releases, this will be the default branch selected -- When running Runbooks, variable values will be pulled from this branch - -For existing initialized repositories, the default branch must exist. If the repository is new and uninitialized, Octopus will create the default branch automatically. - -:::div{.hint} -When snapshotting a Runbook in a Git project that is not yet using config-as-code Runbooks, the variables will always be taken from the default branch. -::: - -#### Initial commit branch - -If the default branch is protected in your repository, select the *Is the default branch protected?* checkbox. This will allow you to use a different _Initial Commit Branch_. If this branch does not exist, Octopus will create the branch automatically. - -The Octopus configurations will be written to the initial commit branch instead of the default branch. You will need to merge the changes from this branch into the default branch outside of Octopus. - -#### Protected branches pattern - -You can also nominate protected branches for your Project. This will prevent users from making direct commits to the nominated branches from the Octopus UI and encourage them to create a new branch instead. To nominate protected branches, type in the name or a wildcard pattern in the Protected Branches Pattern field under Branch Settings. This will apply to all existing and future branches. - - - -## OCL files - -After successfully configuring a project to be version controlled, the specified Git repository will be populated with a set of Octopus Configuration Language (OCL) files. These files are created in the directory you define during setup. E.g. `./octopus/acme` - -Currently, Octopus creates 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. - -The _deployment_process.ocl_ file contains the configuration for your project's steps. Below is an example _deployment_process.ocl_ for a project containing a single _Deploy a Package_ step. - -```hcl -step "deploy-a-package" { - name = "Deploy a Package" - properties = { - Octopus.Action.TargetRoles = "web" - } - - action { - action_type = "Octopus.TentaclePackage" - properties = { - Octopus.Action.EnabledFeatures = ",Octopus.Features.ConfigurationTransforms,Octopus.Features.ConfigurationVariables" - Octopus.Action.Package.AdditionalXmlConfigurationTransforms = "Web.Release.config => Web.config" - Octopus.Action.Package.AutomaticallyRunConfigurationTransformationFiles = "True" - Octopus.Action.Package.AutomaticallyUpdateAppSettingsAndConnectionStrings = "True" - Octopus.Action.Package.DownloadOnTentacle = "False" - Octopus.Action.Package.FeedId = "octopus-server-built-in" - Octopus.Action.Package.PackageId = "webConfig" - } - worker_pool_variable = "" - - packages { - acquisition_location = "Server" - feed = "octopus-server-built-in" - package_id = "webConfig" - properties = { - SelectionMode = "immediate" - } - } - } -} -``` - -The _deployment_settings.ocl_ file contains the configuration for the deployment settings associated with the deployment process. If using the default deployment process settings, the .ocl will be mostly empty. - -```hcl -connectivity_policy { -} - -versioning_strategy { -} -``` - -However, configuring the settings via Octopus will populate the fields with their properties and values. - -```hcl -default_guided_failure_mode = "On" -deployment_changes_template = <<-EOT - #{each release in Octopus.Deployment.Changes} - **Release #{release.Version}** - - #{release.ReleaseNotes} - #{each workItem in release.WorkItems} - - [#{workItem.Id}](#{workItem.LinkUrl}) - #{workItem.Description} - #{/each} - #{/each} - EOT -release_notes_template = <<-EOT - #{each workItem in Octopus.Release.WorkItems} - - [#{workItem.Id}](#{workItem.LinkUrl}) - #{workItem.Description} - #{/each} - EOT - -connectivity_policy { - allow_deployments_to_no_targets = true - exclude_unhealthy_targets = true - skip_machine_behavior = "SkipUnavailableMachines" - target_roles = ["Web"] -} - -versioning_strategy { - - donor_package { - step = "deploy-a-package" - } -} -``` - -The _variables.ocl_ file contains all non-sensitive variables for the project. - -```hcl -variable "DatabaseName" { - value "AU-BNE-TST-001" { - environment = ["test"] - } - - value "AU-BNE-DEV-001" { - environment = ["development"] - } - - value "AU-BNE-001" { - environment = ["production"] - } -} - -variable "DeploymentPool" { - type = "WorkerPool" - - value "non-production-pool" {} - - value "production-pool" { - environment = ["production"] - } -} -``` - -:::div{.hint} -In Git projects, [Octopus will continue apply variable permissions based on scopes](/docs/security/users-and-teams/security-and-un-scoped-variables) when interacting through the API and Portal. As these variables are written to a single text file, any user with access to the repository will have full access to all variables (regardless of scoping). -::: - -## Slugs in OCL - -The following resources will be referenced via their slug: -- Account -- Channel -- Deployment Action -- Deployment Step -- Deployment Target -- Environment -- Feed -- Lifecycle -- Team -- Worker Pool - -All other resources will be referenced from OCL via their ID. We plan on growing this list to include more resources in the future as we introduce slugs into more places throughout Octopus. - -## Items of note - -When designing the config-as-code feature, we made several decisions to keep an appropriate balance of usability and functionality. There are a few limitations and items of note you should be aware of with config-as-code. - -- The Octopus Terraform Provider and OCL are not a 1:1 match. You cannot copy resources between the two and expect everything to work. We want to narrow the gap as much as possible, but as of right now, a gap exists. -- Octopus currently only supports connecting to Git repositories over HTTPS and not SSH. -- Shared resources (environments, external feeds, channels, etc.) are referenced by their slug from OCL. The API however will still use IDs. -- Shared resources referenced in OCL that no longer exist in Octopus Server will result in an error when loading through the portal or API. The provided error message should provide information indicating what reference is no longer valid and should be updated or removed before being loaded again. -- Shared resources must exist before loading an OCL file into Octopus Deploy. What that means is if you copy the OCL files from one Git repo to another, and point a new project at those files, then any shared resource must exist before creating that project. That only applies when projects are in different spaces or on different instances. If the resources do not exist, an error message will appear. -- Pointing multiple projects to the same folder in the same Git repo is unsupported. Please see our [unsupported config as code scenarios](/docs/projects/version-control/unsupported-config-as-code-scenarios) for more information. -- Converting a project to be version-controlled is a one-way process. At this time, you cannot convert back. - -## Older versions - -- Prior to version 2022.3.4517, Git projects would reference shared resources using their name in OCL. This had a side-effect causing API responses for Git projects to contain names instead of IDs. -From version 2022.3.4517 onwards, a handful of resources are referenced from OCL by their slug. IDs will be used in API responses instead of names. \ No newline at end of file diff --git a/src/pages/docs/projects/version-control/converting/index.mdx b/src/pages/docs/projects/version-control/converting/index.mdx index a110d02b23..4776b916b7 100644 --- a/src/pages/docs/projects/version-control/converting/index.mdx +++ b/src/pages/docs/projects/version-control/converting/index.mdx @@ -1,9 +1,9 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-09-16 +modDate: 2025-05-13 title: Converting projects to Git -description: Converting a project to leverage the configuration as a code feature. +description: Converting a project to leverage the version control feature. navOrder: 10 hideInThisSection: true icon: fa-brands fa-git-alt @@ -18,7 +18,7 @@ Git settings are configured per project and are accessed via the **Settings ➜ ## Creating a new version-controlled project -To get a feel for the config-as-code feature, you may want to create a new project that you can test before committing to permanently converting an existing project. This project's deployment process, deployment settings, runbook processes, and non-sensitive variables will be stored in a Git repository when configured. +To get a feel for the version control feature, you may want to create a new project that you can test before committing to permanently converting an existing project. This project's deployment process, deployment settings, runbook processes, and non-sensitive variables will be stored in a Git repository when configured. Click the **New Project** button and select **Use version control for this project.** @@ -30,7 +30,7 @@ Once you click the **Save** button, you'll be sent to the version control screen -Learn more about [Git credentials in Octopus Deploy](/docs/projects/version-control/config-as-code-reference). +Learn more about [Git credentials in Octopus Deploy](/docs/projects/version-control/version-control-reference). Next, add the directory you would like Octopus to store the project configuration. You can connect multiple projects to the same repository if they all use a different sub-directory (e.g. `.octopus/acme` and `.octopus/another-project`). @@ -63,7 +63,7 @@ If your repository has branch protection setup, see [Setting up in a repository Converting a project to use Git is a one-way change. Once you convert a project Git, 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. ::: -Using config-as-code, you can perform a one-way conversion of existing projects to leverage Git. +Using version control, you can perform a one-way conversion of existing projects to leverage Git. Select the project you would like to convert and click on the **Settings ➜ Version Control** link on the project navigation menu. Enter the connection information for your Git repository. You need to provide: @@ -72,7 +72,7 @@ Enter the connection information for your Git repository. You need to provide: - The directory you would like Octopus to store the deployment process in - The name of the default branch -Learn more about [Git credentials in Octopus Deploy](/docs/projects/version-control/config-as-code-reference). +Learn more about [Git credentials in Octopus Deploy](/docs/projects/version-control/version-control-reference). :::div{.hint} You can have multiple deployment processes in the same repository if they all use a different sub-directory. @@ -114,23 +114,23 @@ Optionally, you can also nominate protected branches for your Project. This will ![protected branches](/docs/projects/version-control/converting/configure-protected-branches.png) ::: -## Migrating to config-as-code runbooks on an existing Git project +## Migrating to version control enabled runbooks on an existing Git project -Projects which converted to Git before the introduction of config-as-code runbooks can be easily updated. +Projects which converted to Git before the introduction of version control for runbooks can be easily updated. -You can [migrate an existing version controlled project](/docs/runbooks/config-as-code-runbooks#cac-runbooks-on-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. +You can [migrate an existing version controlled project](/docs/runbooks/version-control-runbooks#version-control-for-runbooks-on-an-existing-version-controlled-project) to use version control enabled runbooks by clicking on the 'Store Runbooks in Git' banner at the top of the **Runbooks** page of your project. ## Migrating variables on an existing Git project -Since the initial public release of config-as-code, we've added support for additional project configuration in Git. You can now [migrate non-sensitive variables to Git](/docs/projects/version-control/converting/migrating-variables). +Since the initial public release of version control enabled projects, we've added support for additional project configuration in Git. You can now [migrate non-sensitive variables to Git](/docs/projects/version-control/converting/migrating-variables). ## Not everything is saved to version control -The Configuration as Code feature is per-project. Currently, the deployment process, runbook processes, settings, and non-sensitive variables are saved to version control. +The version control feature is per-project. Currently, the deployment process, runbook processes, settings, and non-sensitive variables are saved to 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). +Learn more about [what is stored in version control](/docs/projects/version-control/version-control-reference). ## Using a project with version control enabled diff --git a/src/pages/docs/projects/version-control/creating-and-deploying-releases-version-controlled-project.mdx b/src/pages/docs/projects/version-control/creating-and-deploying-releases-version-controlled-project.mdx index 5fe7683c53..000923c22f 100644 --- a/src/pages/docs/projects/version-control/creating-and-deploying-releases-version-controlled-project.mdx +++ b/src/pages/docs/projects/version-control/creating-and-deploying-releases-version-controlled-project.mdx @@ -1,15 +1,15 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-09-17 +modDate: 2025-05-13 title: Creating and deploying releases on a version-controlled project -description: What to expect when creating and deploying releases on a version-controlled project using the Configuration as Code feature in Octopus Deploy. +description: What to expect when creating and deploying releases on a version-controlled project using the version control feature in Octopus Deploy. navOrder: 40 icon: fa-brands fa-git-alt --- import BuildServerPluginVersionControlFields from 'src/shared-content/projects/version-control/build-server-plugin-version-control-fields.include.md'; -There are slight differences when creating and deploying a release with a version-controlled project using the Configuration as Code feature in Octopus Deploy. This page will walk through those differences. +There are slight differences when creating and deploying a release with a version-controlled project using the version control feature in Octopus Deploy. This page will walk through those differences. ## Creating a release diff --git a/src/pages/docs/projects/version-control/editing-a-project-with-version-control-enabled.md b/src/pages/docs/projects/version-control/editing-a-project-with-version-control-enabled.md index 49b8fc4fae..40979d8226 100644 --- a/src/pages/docs/projects/version-control/editing-a-project-with-version-control-enabled.md +++ b/src/pages/docs/projects/version-control/editing-a-project-with-version-control-enabled.md @@ -1,14 +1,14 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-09-17 +modDate: 2025-05-13 title: Editing a project with version control enabled -description: What to expect when using the Configuration as Code feature in Octopus Deploy +description: What to expect when using the version control feature in Octopus Deploy navOrder: 30 icon: fa-brands fa-git-alt --- -Once an Octopus Project is configured to be version-controlled, your experience making changes to a project will change. With the configuration as code feature, you can either edit the resources via the Octopus Deploy UI or your favorite file editing tool. This page will walk through what to expect. +Once an Octopus Project is configured to be version-controlled, your experience making changes to a project will change. With the version control feature, you can either edit the resources via the Octopus Deploy UI or your favorite file editing tool. This page will walk through what to expect. ## Editing via the Octopus UI diff --git a/src/pages/docs/projects/version-control/github/index.md b/src/pages/docs/projects/version-control/github/index.md index 9dda23331f..b4541598a6 100644 --- a/src/pages/docs/projects/version-control/github/index.md +++ b/src/pages/docs/projects/version-control/github/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-03-14 -modDate: 2024-09-17 +modDate: 2025-05-13 title: GitHub integration description: Octopus Deploy GitHub integration icon: fa-brands fa-github @@ -55,7 +55,7 @@ Octopus can only see repositories that are available to the app installation and To connect a repository, you must be an administrator of the repository on GitHub. If you're not an administrator (but can view the repository), you will still see the repository in the list, but will not be able to select it. ## Using GitHub App Connections -You can currently use GitHub App Connections to connect to Configuration as Code projects. This removes the need for using Personal Access Tokens to connect to GitHub repositories, and allows users to commit as their GitHub users (rather than using a shared account). +You can currently use GitHub App Connections to connect to version control enabled projects. This removes the need for using Personal Access Tokens to connect to GitHub repositories, and allows users to commit as their GitHub users (rather than using a shared account). ## More information on installing and authorizing the Octopus GitHub App You install the Octopus GitHub App on an account (organization or user) to give the repositories or other content within that account. Authorizing gives the Octopus GitHub App permission to act on your behalf in any account that has the app installed. diff --git a/src/pages/docs/projects/version-control/index.md b/src/pages/docs/projects/version-control/index.md index b0d19100fe..74eca34605 100644 --- a/src/pages/docs/projects/version-control/index.md +++ b/src/pages/docs/projects/version-control/index.md @@ -1,8 +1,8 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2024-09-17 -title: Configuration as Code +modDate: 2025-05-13 +title: Version Control description: Projects can be version-controlled as text in a Git repository icon: fa-brands fa-git-alt navOrder: 110 @@ -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, your _deployment process_, _runbook processes_, _deployment settings_, and _non-sensitive variables_ can be version-controlled. +The version control feature adds support for configuring Octopus projects to store project resources in a Git repository. For now, your _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. @@ -24,12 +24,12 @@ Of course, there is now a text representation of the process in the Git reposito 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. +Version control 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. ::: ### 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? +Our major goal for the early stages of this feature is to discover the ways people want version control to evolve. What scenarios would you like to see unlocked? What doesn't work the way you hoped? You can provide feedback through whichever of the following channels you feel most comfortable with: @@ -41,17 +41,17 @@ 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. +New version controlled projects will automatically have this enabled for both deployment and runbook processes. -You can [migrate an existing version controlled project](/docs/runbooks/config-as-code-runbooks#cac-runbooks-on-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. +You can [migrate an existing version controlled project](/docs/runbooks/version-control-runbooks#version-control-for-runbooks-on-an-existing-version-controlled-project) to use version control enabled 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 +## Version Control Reference Several resources previously stored in SQL Server will now be stored in git once a project is version-controlled. -Learn more about [Configuration as Code reference](/docs/projects/version-control/config-as-code-reference) +Learn more about [Version Control Reference](/docs/projects/version-control/version-control-reference) ## Making changes to a version-controlled project @@ -61,7 +61,7 @@ Learn more about [Editing a project with version control enabled](/docs/projects ## Migrating projects to support new features -Since the initial public release of config-as-code, we've added support for additional project configuration in Git. Learn more about [migrating variables to Git](/docs/projects/version-control/converting/migrating-variables) +Since the initial public release of version control enabled projects, we've added support for additional project configuration in Git. Learn more about [migrating variables to Git](/docs/projects/version-control/converting/migrating-variables) ## Creating and deploying releases @@ -71,6 +71,6 @@ Learn more about [creating and deploying releases in a version controlled projec ## Unsupported scenarios -The Configuration as Code feature is designed to give you the benefits of source control, branching, reverting, and pull requests while being able to use your tool of choice to manage your processes (and eventually) variables. While it has many benefits, there are some unsuitable use cases and scenarios. +The version control feature is designed to give you the benefits of source control, branching, reverting, and pull requests while being able to use your tool of choice to manage your processes (and eventually) variables. While it has many benefits, there are some unsuitable use cases and scenarios. -Learn more about [unsupported config-as-code scenarios](/docs/projects/version-control/unsupported-config-as-code-scenarios) \ No newline at end of file +Learn more about [unsupported version control scenarios](/docs/projects/version-control/unsupported-version-control-scenarios) \ No newline at end of file diff --git a/src/pages/docs/projects/version-control/moving-version-control.md b/src/pages/docs/projects/version-control/moving-version-control.md index 4841a6c801..c363af7be6 100644 --- a/src/pages/docs/projects/version-control/moving-version-control.md +++ b/src/pages/docs/projects/version-control/moving-version-control.md @@ -1,16 +1,16 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Moving version control description: Changing the location of your configuration repository. icon: fa-brands fa-git-alt navOrder: 60 --- -Version-control is configured per project and is accessed via the **Settings ➜ Version Control** link in the project navigation menu. This page will walk you through moving an existing config as code repository to a new location. +Version-control is configured per project and is accessed via the **Settings ➜ Version Control** link in the project navigation menu. This page will walk you through moving an existing repository to a new location. -## Moving configuration as code files +## Moving version control enabled files Switching on version control for your project is a one-way change. You can't move the project back into the Octopus database once it's in a repository. However, you are free to move the configuration to a new folder or repository. diff --git a/src/pages/docs/projects/version-control/ocl-file-format.md b/src/pages/docs/projects/version-control/ocl-file-format.md index dc1dc42445..e33e8ee306 100644 --- a/src/pages/docs/projects/version-control/ocl-file-format.md +++ b/src/pages/docs/projects/version-control/ocl-file-format.md @@ -1,8 +1,8 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 -title: OCL Syntax for Config as Code +modDate: 2025-05-13 +title: OCL Syntax for Version Control description: A description of Octopus Deploy's OCL file format. icon: fa-solid fa-code navOrder: 70 diff --git a/src/pages/docs/projects/version-control/unsupported-config-as-code-scenarios.md b/src/pages/docs/projects/version-control/unsupported-config-as-code-scenarios.md index 9cf2c9418a..bfe3b0befa 100644 --- a/src/pages/docs/projects/version-control/unsupported-config-as-code-scenarios.md +++ b/src/pages/docs/projects/version-control/unsupported-config-as-code-scenarios.md @@ -1,99 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2023-01-01 -modDate: 2025-02-18 -title: Unsupported Configuration as Code Scenarios -description: Unsupported scenarios for the Configuration as Code feature in Octopus Deploy. -icon: fa-brands fa-git-alt -navOrder: 50 +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/projects/version-control/unsupported-version-control-scenarios +pubDate: 2025-05-09 +navSearch: false +navSitemap: false +navMenu: false --- - -The Configuration as Code feature is designed to give you the benefits of source control, branching, reverting, and pull requests while being able to use your tool of choice to manage your processes and non-sensitive variables. While it has many benefits, there are some unsuitable use cases and scenarios. This document will describe each one as well as provide alternatives. - -## Core design decision - -The core design decision is each project in each space has a unique folder in a git repository. A git repository can store several projects across several spaces or store a single project in a single space. But, each project must have a unique folder in a git repository because of all the scaffolding data referenced by a project. - -That scaffolding data includes (but is not limited to): - -- Environments -- Tenant Tags -- Worker Pools -- Feeds -- Step Templates -- Channels / Lifecycles - -That data is not stored in source control because it is shared across multiple projects. - -:::div{.warning} -An error will occur when Octopus Deploy attempts to load a process from source control with one or more of those items missing. You'll be unable to create releases or access runbooks until those errors are resolved. -::: - -## Syncing multiple instances - -The configuration as code feature is not designed to allow two or more projects on different instances to point to the same folder. We've seen our users attempt to use Configuration as Code to keep the deployment processes in sync across multiple instances. That scenario is unsupported. - -While it may work initially, it will be harder and harder to manage over time. You will need to keep _all_ the scaffolding data in sync across multiple instances. That is [easier said than done](/docs/administration/sync-instances). Step templates will be the most difficult, as having the same step template on all instances, the version has to match. Otherwise, you'll have to worry about settings such as parameters, scripts, package versions, feeds, and more. - -:::div{.warning} -Configuration as Code currently supports storing the deployment process and non-sensitive variables for a project in the Git repo. It does not store or runbook processes or sensitive variables. -::: - -Typically, having two instances results from splitting an Octopus Deploy instance by environment (one instance has Dev/Test the other has Staging/Prod), by Tenant (one instance has test tenants, the other has customers), or both. Pointing multiple instances at the same folder will only work if they _are all exactly the same forever_. - -### Octopus Terraform Provider - -Use the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs) to keep multiple instances in sync. Use Terraform's [variable functionality](https://www.terraform.io/language/values/variables) to manage the differences between the instances. For example, have a variable for environment scoping. One instance populates the environment list with "Test" while the other populates it with **Staging** and **Production**. - -:::div{.warning} -You will still need a process to keep step templates in sync. -::: - -The downside to this approach is you'll be unable to use the Octopus Deploy UI to manage your deployment processes. In addition, you'll need to convert your existing deployment process into Terraform manually. The files generated by Configuration as Code has a similar syntax as the Terraform provider, but it is not a 1:1 match. - -### Separate folders for each instance - -Another alternative is each instance points to a unique folder in the same GitHub repo. For example, if you had a Developer instance and a Production instance. - -- .octopus/project-a/dev-instance -- .octopus/project-a/production-instance - -Use a file diff tool, Beyond Compare, Meld, WinMerge, or KDiff, to manually copy specific changes between the two directories. Any instance-specific configuration, such as environment scoping, worker pools, or feeds, would be excluded. - -:::div{.warning} -You will still need a process to keep step templates in sync. -::: - -The downside to this approach is it is a manual process and prone to error. - -## Project templating - -The configuration as code feature is not designed to allow two or more projects on the same space to point to the same folder. We've seen our users attempt to use Configuration as Code as project templating. This scenario is unsupported. - -While it may work for the first couple of projects, as all the necessary scaffolding data is there because the projects will be in the same space. However, projects will have subtle differences. Those differences include: - -- Packages to deploy -- Target roles -- Worker pools -- Tenant Tags -- Package Feeds - -You will find projects are constantly overwriting each other. - -One option is to have a single git repo for all your projects, with each project saved to a unique folder in the repository. You could then use a file comparison tool to copy changes between projects. That scenario will not scale well. Branch naming conventions would need to be strictly enforced if you configured 50 projects to save to the same git repo. The number of possible branches would exponentially grow with each added project. The chances of a person selecting the wrong branch will subsequently increase. And manually copying changes via a file comparison tool is error-prone and time-consuming. - -Having a branch per project will partially solve the problem of the subtle differences, but it will be very time-consuming to sync any "main" branch changes with the project branches. You will need to manually sync all the branches or create and maintain a process to handle the syncing. - -:::div{.warning} -Configuration as Code is an all-or-nothing feature. You'll be unable to say manage "some of my deployment process" using Configuration as Code. It is the entire deployment process or nothing. -::: - -### Octopus Terraform Provider - -Use the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs) to create a deployment process template. Use Terraform's [variable functionality](https://www.terraform.io/language/values/variables) to manage the different projects. For example, have a variable for target roles; one project has **OctoFX-WebApi** while another uses **RandomQuotes-WebApi**. - -One advantage to this approach is the flexibility to decide what resources are managed by the Terraform Provider and what resources are managed by users in the Octopus UI. The downside to this approach is you'll be unable to use the Octopus Deploy UI to manage your deployment processes. In addition, you'll need to convert your existing deployment process into Terraform manually. The files generated by Configuration as Code has a similar syntax as the Terraform provider, but it is not a 1:1 match. - -## Submodules - -Submodules are a convenient way to reference one repository from within a subdirectory of another repository. Octopus currently does not support the use of submodules for the storing of Configuration as Code files. This means that your configuration files must all be stored directly in the connected repository. diff --git a/src/pages/docs/projects/version-control/unsupported-version-control-scenarios.md b/src/pages/docs/projects/version-control/unsupported-version-control-scenarios.md new file mode 100644 index 0000000000..5b856b80c4 --- /dev/null +++ b/src/pages/docs/projects/version-control/unsupported-version-control-scenarios.md @@ -0,0 +1,99 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-01-01 +modDate: 2025-05-13 +title: Unsupported Version Control Scenarios +description: Unsupported scenarios for the Version Control feature in Octopus Deploy. +icon: fa-brands fa-git-alt +navOrder: 50 +--- + +The version control feature is designed to give you the benefits of source control, branching, reverting, and pull requests while being able to use your tool of choice to manage your processes and non-sensitive variables. While it has many benefits, there are some unsuitable use cases and scenarios. This document will describe each one as well as provide alternatives. + +## Core design decision + +The core design decision is each project in each space has a unique folder in a git repository. A git repository can store several projects across several spaces or store a single project in a single space. But, each project must have a unique folder in a git repository because of all the scaffolding data referenced by a project. + +That scaffolding data includes (but is not limited to): + +- Environments +- Tenant Tags +- Worker Pools +- Feeds +- Step Templates +- Channels / Lifecycles + +That data is not stored in source control because it is shared across multiple projects. + +:::div{.warning} +An error will occur when Octopus Deploy attempts to load a process from source control with one or more of those items missing. You'll be unable to create releases or access runbooks until those errors are resolved. +::: + +## Syncing multiple instances + +The version control feature is not designed to allow two or more projects on different instances to point to the same folder. We've seen our users attempt to use version control to keep the deployment processes in sync across multiple instances. That scenario is unsupported. + +While it may work initially, it will be harder and harder to manage over time. You will need to keep _all_ the scaffolding data in sync across multiple instances. That is [easier said than done](/docs/administration/sync-instances). Step templates will be the most difficult, as having the same step template on all instances, the version has to match. Otherwise, you'll have to worry about settings such as parameters, scripts, package versions, feeds, and more. + +:::div{.warning} +Version control currently supports storing the deployment process and non-sensitive variables for a project in the Git repo. It does not store or runbook processes or sensitive variables. +::: + +Typically, having two instances results from splitting an Octopus Deploy instance by environment (one instance has Dev/Test the other has Staging/Prod), by Tenant (one instance has test tenants, the other has customers), or both. Pointing multiple instances at the same folder will only work if they _are all exactly the same forever_. + +### Octopus Terraform Provider + +Use the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs) to keep multiple instances in sync. Use Terraform's [variable functionality](https://www.terraform.io/language/values/variables) to manage the differences between the instances. For example, have a variable for environment scoping. One instance populates the environment list with "Test" while the other populates it with **Staging** and **Production**. + +:::div{.warning} +You will still need a process to keep step templates in sync. +::: + +The downside to this approach is you'll be unable to use the Octopus Deploy UI to manage your deployment processes. In addition, you'll need to convert your existing deployment process into Terraform manually. The files generated by version control has a similar syntax as the Terraform provider, but it is not a 1:1 match. + +### Separate folders for each instance + +Another alternative is each instance points to a unique folder in the same GitHub repo. For example, if you had a Developer instance and a Production instance. + +- .octopus/project-a/dev-instance +- .octopus/project-a/production-instance + +Use a file diff tool, Beyond Compare, Meld, WinMerge, or KDiff, to manually copy specific changes between the two directories. Any instance-specific configuration, such as environment scoping, worker pools, or feeds, would be excluded. + +:::div{.warning} +You will still need a process to keep step templates in sync. +::: + +The downside to this approach is it is a manual process and prone to error. + +## Project templating + +The version control feature is not designed to allow two or more projects on the same space to point to the same folder. We've seen our users attempt to use version control as project templating. This scenario is unsupported. + +While it may work for the first couple of projects, as all the necessary scaffolding data is there because the projects will be in the same space. However, projects will have subtle differences. Those differences include: + +- Packages to deploy +- Target roles +- Worker pools +- Tenant Tags +- Package Feeds + +You will find projects are constantly overwriting each other. + +One option is to have a single git repo for all your projects, with each project saved to a unique folder in the repository. You could then use a file comparison tool to copy changes between projects. That scenario will not scale well. Branch naming conventions would need to be strictly enforced if you configured 50 projects to save to the same git repo. The number of possible branches would exponentially grow with each added project. The chances of a person selecting the wrong branch will subsequently increase. And manually copying changes via a file comparison tool is error-prone and time-consuming. + +Having a branch per project will partially solve the problem of the subtle differences, but it will be very time-consuming to sync any "main" branch changes with the project branches. You will need to manually sync all the branches or create and maintain a process to handle the syncing. + +:::div{.warning} +Version control is an all-or-nothing feature. You'll be unable to say manage "some of my deployment process" using version control. It is the entire deployment process or nothing. +::: + +### Octopus Terraform Provider + +Use the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs) to create a deployment process template. Use Terraform's [variable functionality](https://www.terraform.io/language/values/variables) to manage the different projects. For example, have a variable for target roles; one project has **OctoFX-WebApi** while another uses **RandomQuotes-WebApi**. + +One advantage to this approach is the flexibility to decide what resources are managed by the Terraform Provider and what resources are managed by users in the Octopus UI. The downside to this approach is you'll be unable to use the Octopus Deploy UI to manage your deployment processes. In addition, you'll need to convert your existing deployment process into Terraform manually. The files generated by version control has a similar syntax as the Terraform provider, but it is not a 1:1 match. + +## Submodules + +Submodules are a convenient way to reference one repository from within a subdirectory of another repository. Octopus currently does not support the use of submodules for the storing of version control enabled files. This means that your configuration files must all be stored directly in the connected repository. diff --git a/src/pages/docs/projects/version-control/version-control-reference.mdx b/src/pages/docs/projects/version-control/version-control-reference.mdx new file mode 100644 index 0000000000..cf4973f7c0 --- /dev/null +++ b/src/pages/docs/projects/version-control/version-control-reference.mdx @@ -0,0 +1,338 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2023-01-01 +modDate: 2025-05-13 +title: Version Control reference +description: Details about the version control feature. +navOrder: 20 +icon: fa-brands fa-git-alt +--- +import VersionControlRepositoryUrlFormat from 'src/shared-content/version-control-repository-url-format.include.md'; + +The version control feature enables you to save some project-level settings as files in a Git repository instead of SQL Server. The files are written in the OCL (Octopus Configuration Language) format. Storing resources as files lets you leverage version control features such as branching, pull requests, and reverting changes. In addition, you can save both your source code and how you deploy your code in the same Git repository. This page is a reference document of how the version control feature works. + +## Octopus project level only + +The version control feature will store Octopus Project resources in Git instead of SQL Server. + +### Project resources version controlled + +Currently, the Project level resources saved to Git are: + +- Deployment Process +- Deployment Settings + - Release Versioning + - Release Notes Template + - Deployment Targets Required + - Transient Deployment Targets + - Deployment Changes Template + - Default Failure Mode +- Runbook Process +- Runbook Settings + - Multi-tenancy Mode + - Run Retention Policy + - Connectivity Policy + - Default Failure Mode +- Variables (excluding Sensitive variables) + +:::div{.hint} +Sensitive variables are still stored in the database. Regardless of the current branch, you will always see the same set of sensitive variables. +::: + +### Project resources saved to SQL Server + +Currently, the Project level resources saved to SQL Server when version control is enabled are: + +- Channels +- Triggers +- Releases +- Deployments +- Sensitive Variables +- General Settings + - Project Name + - Enabled / Disabled + - Logo + - Description + - Project Group + +:::div{.hint} +Sensitive Variables are planned for future releases of version control. +::: + +### Resources **not** version controlled + +This feature manages project-level resources. However, it is worth explicitly mentioning some things that are **not included**: + +- Infrastructure + - Environments + - Deployment Targets + - Workers + - Worker Pools + - Machine Policies + - Machine Proxies + - Accounts +- Tenants +- Library + - Certificates + - External Feeds + - Lifecycles + - Packages + - Build Information + - Script Modules + - Step Templates + - Variable Sets +- Server Configuration + - Feature Flags + - License + - Node Settings (Task Cap and Server Uri) + - Issue Tracker Settings + - External Auth Provider Settings + - SMTP + - Spaces + - Teams (both membership and role assignment) + - Users + - User Roles + +Currently, there are no plans to include these resources in the version control feature. Several of the resources above can be put into version control using the [Octopus Terraform Provider](https://registry.terraform.io/providers/OctopusDeployLabs/octopusdeploy/latest/docs). + +:::div{.hint} +Resources managed by the Octopus Terraform Provider will have their state managed by Terraform. Resources managed by version control capabilities will have the state managed by Octopus Deploy. The two are not the same and shouldn't be treated as such. +::: + +## Git configuration options + +Project version control settings can be accessed by clicking on the **Settings ➜ Version Control** link on the project navigation menu. + +### Git repository + +The _Git Repository_ field should contain the URL for the repository you wish the Octopus configuration to be persisted to. e.g. `https://github.com/OctopusSamples/OctoFX.git` + + + +The repository must be initialized (i.e. contain at least one branch) prior to saving. Octopus will convert the existing items in the project to OCL (Octopus Configuration Language) and save it to that repository when you click save. If the repository isn't initialized, that will fail. + +### Authentication + +The version control feature is designed to work with _any_ Git repository. When configuring a project to be version-controlled, you can optionally provide credentials for authentication. + +:::div{.hint} +Do not use credentials from a personal account. Select a shared or service account. When Octopus Deploy saves to your Git repo, you will typically see the message `[User Name] authored and [Service Account] committed on [Date].` +::: + +For the Password field, we recommend using a personal access token. We also recommend that you follow the principle of least privilege when selecting scopes or permissions to grant this personal access token. + +Git providers allow you to create an access token in different ways. The recommended _scope_ for each provider is listed in brackets. + +- [GitHub - Creating a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token); (Permission - `Contents - Read and Write`) +- [GitHub - Creating a personal access token (Classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic); (Scope - `repo`) +- [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate); (Scope - `vso.code_full`) +- [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html); (Scope - `write_repository`) +- [BitBucket Server](https://confluence.atlassian.com/bitbucketserver063/personal-access-tokens-972354166.html); (Permission - `Project admin`) +- [BitBucket Cloud - Use App Passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/); (Permission - `Repositories - Read & Write`) + +:::div{.hint} +Some VCS providers require that you use only a username and personal access token for authentication, not an email address (i.e. BitBucket). +::: + +#### BitBucket repository access tokens +BitBucket's repository access tokens allow you to create repository-specific access tokens. For these to work with your Git repositories in Octopus, you must set the username to `x-token-auth`, and the password to the token. + +:::figure +![Screenshot of Octopus Version Control Settings page with Authentication section expanded. Username/password auth method is selected, the Username input field is highlighted with a bold red box, and contains the value x-token-auth](/docs/projects/version-control/octopus-bitbucket-repository-access-tokens.png) +::: + +### File storage + +_Git File Storage Directory_ specifies the path within the repository where the Octopus configuration will be stored. The default directory is `.octopus`, but that can be changed. If only a single Octopus project will be stored in the repo, we recommend putting the configuration directly under the `.octopus` directory. + +:::div{.hint} +If multiple projects will be persisted to the repository, adding the project name to the path is the recommended convention, e.g. `./octopus/acme` +::: + +We recommend storing projects alongside the application code. While it is possible to store all your deployment projects in a single central repository with folders for each project, it will be challenging to manage as you add more projects. For example, if you have multiple component projects, one for Web UI, another for Web API, etc., but the source code is in one repository, then store all the component projects in that repository. If you move the application code later, you can also [move the deployment configuration](/docs/projects/version-control/moving-version-control) to keep it with the application. + +### Branch settings + +#### Default branch name + +The _Default Branch Name_ is the branch on which the Octopus configuration will be written. It is also the default branch that will be used in various situations, for example: + +- When users view the project's deployment process for the first time in the Octopus UI, this is the initially selected branch +- When creating releases, this will be the default branch selected +- When running Runbooks, variable values will be pulled from this branch + +For existing initialized repositories, the default branch must exist. If the repository is new and uninitialized, Octopus will create the default branch automatically. + +:::div{.hint} +When snapshotting a Runbook in a Git project that is not yet using version control enabled Runbooks, the variables will always be taken from the default branch. +::: + +#### Initial commit branch + +If the default branch is protected in your repository, select the *Is the default branch protected?* checkbox. This will allow you to use a different _Initial Commit Branch_. If this branch does not exist, Octopus will create the branch automatically. + +The Octopus configurations will be written to the initial commit branch instead of the default branch. You will need to merge the changes from this branch into the default branch outside of Octopus. + +#### Protected branches pattern + +You can also nominate protected branches for your Project. This will prevent users from making direct commits to the nominated branches from the Octopus UI and encourage them to create a new branch instead. To nominate protected branches, type in the name or a wildcard pattern in the Protected Branches Pattern field under Branch Settings. This will apply to all existing and future branches. + + + +## OCL files + +After successfully configuring a project to be version controlled, the specified Git repository will be populated with a set of Octopus Configuration Language (OCL) files. These files are created in the directory you define during setup. E.g. `./octopus/acme` + +Currently, Octopus creates 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. + +The _deployment_process.ocl_ file contains the configuration for your project's steps. Below is an example _deployment_process.ocl_ for a project containing a single _Deploy a Package_ step. + +```hcl +step "deploy-a-package" { + name = "Deploy a Package" + properties = { + Octopus.Action.TargetRoles = "web" + } + + action { + action_type = "Octopus.TentaclePackage" + properties = { + Octopus.Action.EnabledFeatures = ",Octopus.Features.ConfigurationTransforms,Octopus.Features.ConfigurationVariables" + Octopus.Action.Package.AdditionalXmlConfigurationTransforms = "Web.Release.config => Web.config" + Octopus.Action.Package.AutomaticallyRunConfigurationTransformationFiles = "True" + Octopus.Action.Package.AutomaticallyUpdateAppSettingsAndConnectionStrings = "True" + Octopus.Action.Package.DownloadOnTentacle = "False" + Octopus.Action.Package.FeedId = "octopus-server-built-in" + Octopus.Action.Package.PackageId = "webConfig" + } + worker_pool_variable = "" + + packages { + acquisition_location = "Server" + feed = "octopus-server-built-in" + package_id = "webConfig" + properties = { + SelectionMode = "immediate" + } + } + } +} +``` + +The _deployment_settings.ocl_ file contains the configuration for the deployment settings associated with the deployment process. If using the default deployment process settings, the .ocl will be mostly empty. + +```hcl +connectivity_policy { +} + +versioning_strategy { +} +``` + +However, configuring the settings via Octopus will populate the fields with their properties and values. + +```hcl +default_guided_failure_mode = "On" +deployment_changes_template = <<-EOT + #{each release in Octopus.Deployment.Changes} + **Release #{release.Version}** + + #{release.ReleaseNotes} + #{each workItem in release.WorkItems} + - [#{workItem.Id}](#{workItem.LinkUrl}) - #{workItem.Description} + #{/each} + #{/each} + EOT +release_notes_template = <<-EOT + #{each workItem in Octopus.Release.WorkItems} + - [#{workItem.Id}](#{workItem.LinkUrl}) - #{workItem.Description} + #{/each} + EOT + +connectivity_policy { + allow_deployments_to_no_targets = true + exclude_unhealthy_targets = true + skip_machine_behavior = "SkipUnavailableMachines" + target_roles = ["Web"] +} + +versioning_strategy { + + donor_package { + step = "deploy-a-package" + } +} +``` + +The _variables.ocl_ file contains all non-sensitive variables for the project. + +```hcl +variable "DatabaseName" { + value "AU-BNE-TST-001" { + environment = ["test"] + } + + value "AU-BNE-DEV-001" { + environment = ["development"] + } + + value "AU-BNE-001" { + environment = ["production"] + } +} + +variable "DeploymentPool" { + type = "WorkerPool" + + value "non-production-pool" {} + + value "production-pool" { + environment = ["production"] + } +} +``` + +:::div{.hint} +In Git projects, [Octopus will continue apply variable permissions based on scopes](/docs/security/users-and-teams/security-and-un-scoped-variables) when interacting through the API and Portal. As these variables are written to a single text file, any user with access to the repository will have full access to all variables (regardless of scoping). +::: + +## Slugs in OCL + +The following resources will be referenced via their slug: +- Account +- Channel +- Deployment Action +- Deployment Step +- Deployment Target +- Environment +- Feed +- Lifecycle +- Team +- Worker Pool + +All other resources will be referenced from OCL via their ID. We plan on growing this list to include more resources in the future as we introduce slugs into more places throughout Octopus. + +## Items of note + +When designing the version control feature, we made several decisions to keep an appropriate balance of usability and functionality. There are a few limitations and items of note you should be aware of with version control. + +- The Octopus Terraform Provider and OCL are not a 1:1 match. You cannot copy resources between the two and expect everything to work. We want to narrow the gap as much as possible, but as of right now, a gap exists. +- Octopus currently only supports connecting to Git repositories over HTTPS and not SSH. +- Shared resources (environments, external feeds, channels, etc.) are referenced by their slug from OCL. The API however will still use IDs. +- Shared resources referenced in OCL that no longer exist in Octopus Server will result in an error when loading through the portal or API. The provided error message should provide information indicating what reference is no longer valid and should be updated or removed before being loaded again. +- Shared resources must exist before loading an OCL file into Octopus Deploy. What that means is if you copy the OCL files from one Git repo to another, and point a new project at those files, then any shared resource must exist before creating that project. That only applies when projects are in different spaces or on different instances. If the resources do not exist, an error message will appear. +- Pointing multiple projects to the same folder in the same Git repo is unsupported. Please see our [unsupported version control scenarios](/docs/projects/version-control/unsupported-version-control-scenarios) for more information. +- Converting a project to be version-controlled is a one-way process. At this time, you cannot convert back. + +## Older versions + +- Prior to version 2022.3.4517, Git projects would reference shared resources using their name in OCL. This had a side-effect causing API responses for Git projects to contain names instead of IDs. +From version 2022.3.4517 onwards, a handful of resources are referenced from OCL by their slug. IDs will be used in API responses instead of names. diff --git a/src/pages/docs/releases/channels/index.md b/src/pages/docs/releases/channels/index.md index 2ce246e98d..9bb023c1d7 100644 --- a/src/pages/docs/releases/channels/index.md +++ b/src/pages/docs/releases/channels/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Channels icon: fa-solid fa-arrows-split-up-and-left description: Channels allow you to dynamically change the deployment logic and lifecycle of a project based on the version being deployed. @@ -248,4 +248,4 @@ The image below shows an example dashboard with discrete channel release enabled ## Removing channels -For projects using Config as Code, it's up to you to take care to avoid deleting any channels required by your deployments. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. \ No newline at end of file +For projects using version control, it's up to you to take care to avoid deleting any channels required by your deployments. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. \ No newline at end of file diff --git a/src/pages/docs/releases/lifecycles/index.mdx b/src/pages/docs/releases/lifecycles/index.mdx index 73c4df2b21..600e6c260c 100644 --- a/src/pages/docs/releases/lifecycles/index.mdx +++ b/src/pages/docs/releases/lifecycles/index.mdx @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Lifecycles description: Lifecycles allow you to control the way releases are promoted between environments. icon: fa-solid fa-arrows-spin @@ -186,7 +186,7 @@ It typically consists of just one phase and one environment, also called Mainten ## Removing lifecycles -For projects using Config as Code, it's up to you to take care to avoid deleting any lifecycles required by your deployments. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. +For projects using version control, it's up to you to take care to avoid deleting any lifecycles required by your deployments. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. ## Recommendations \{#lifecycle-recommendations} diff --git a/src/pages/docs/runbooks/config-as-code-runbooks.md b/src/pages/docs/runbooks/config-as-code-runbooks.md index 695c93d0aa..450f4ed736 100644 --- a/src/pages/docs/runbooks/config-as-code-runbooks.md +++ b/src/pages/docs/runbooks/config-as-code-runbooks.md @@ -1,95 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2024-11-24 -modDate: 2025-02-18 -title: Config as Code runbooks -description: Details about using configuration as code with runbooks. -navOrder: 20 -icon: fa-brands fa-git-alt +layout: src/layouts/Redirect.astro +title: Redirect +redirect: https://octopus.com/docs/runbooks/version-control-runbooks +pubDate: 2025-05-13 +navSearch: false +navSitemap: false +navMenu: false --- - -:::div{.success} -Support for CaC Runbooks is rolling out to Octopus Cloud as of Q1 2025 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 configuration for your runbooks, as well as your deployment process, settings and variables, are stored as OCL files which you can edit in Octopus or directly in your IDE. - -Using CaC Runbooks is currently 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 that 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 each 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, it's important to 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 which 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](/docs/runbooks/runbook-permissions) to help you to manage permissions around editing and running runbooks: 'Runbook Consumer' and 'Runbook Producer'. - -#### Runbook Consumer: -- Non-CaC Runbooks - Runbook Consumers cannot edit runbooks and can only run published runbooks. -- CaC Runbooks - Runbook Consumers cannot edit runbooks and can only run runbooks from the latest commit on the default branch. - -#### Runbook Producer: -- Non-CaC Runbooks - Runbook Producers can edit and run both draft and published runbooks. -- CaC Runbooks - Runbook Producers can edit runbooks on any unprotected branches and can run runbooks from any commit on any branch. - -Assuming your default branch is protected, this means that your old 'published' runbooks are equivalent to the runbooks in the latest commit on your default branch, and your old 'draft' runbooks are equivalent to 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 top of 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](/docs/runbooks/scheduled-runbook-trigger) will always run CaC Runbooks from the latest commit on your default branch, just as non-CaC runbook triggers will only run published runbooks. - -## Custom automated scripts - -If you use automated scripts that run runbooks via the Octopus Server API and you convert your runbooks to Config As Code the URL for the runbook will change to include a branch reference (e.g. `refs/heads/main`) as a result you need to update your scripts to include the branch reference where the runbook is stored. - -- [PowerShell example](https://github.com/OctopusDeploy/OctopusDeploy-Api/blob/master/REST/PowerShell/Runbooks/RunConfigAsCodeRunbook.ps1) - -## Deleting required resources - -Once your Runbooks are version controlled, it's up to you to take care to avoid deleting any Octopus resources required by your Runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. - - diff --git a/src/pages/docs/runbooks/runbook-publishing/index.md b/src/pages/docs/runbooks/runbook-publishing/index.md index 3830a90cd5..74a253800c 100644 --- a/src/pages/docs/runbooks/runbook-publishing/index.md +++ b/src/pages/docs/runbooks/runbook-publishing/index.md @@ -1,14 +1,14 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Runbooks publishing description: Publishing makes a runbook available to scheduled triggers and consumers. 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. +Version control enabled runbooks use branches instead of publishing. If your project uses version control for runbooks, read about [managing runbooks permissions using branches](/docs/runbooks/version-control-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. diff --git a/src/pages/docs/runbooks/runbooks-vs-deployments/index.md b/src/pages/docs/runbooks/runbooks-vs-deployments/index.md index 78356feabe..86c10310ce 100644 --- a/src/pages/docs/runbooks/runbooks-vs-deployments/index.md +++ b/src/pages/docs/runbooks/runbooks-vs-deployments/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-10-04 +modDate: 2025-05-13 title: Runbooks vs Deployments description: Describing the differences between a deployment and a runbook. navOrder: 10 @@ -61,7 +61,7 @@ You can choose to: The retention policy is applied **per environment**. For example, if you had three environments, Development, Staging and Production and you set the retention policy limit to 10, that would keep a total of **30** runbook runs - 10 in *each* of Development, Staging and Production. -If you are using **config-as-code runbooks**, keep in mind that when a branch is deleted this includes any retention policies on that branch. The retention policy for any runbook runs made from that branch will then use the default time based retention policy (60 days). +If you are using **version control enabled runbooks**, keep in mind that when a branch is deleted this includes any retention policies on that branch. The retention policy for any runbook runs made from that branch will then use the default time based retention policy (60 days). :::div{.hint} In Octopus 2020.2 and earlier, the runbook retention policy could not be set. Instead, Octopus would keep the last 1000 runs. @@ -70,7 +70,7 @@ In Octopus 2020.2 and earlier, the runbook retention policy could not be set. In ## Snapshots versus Releases :::div{.success} -Config-as-code runbooks use commits instead of snapshots. If your project uses config-as-code runbooks, read about [snapshots vs commits](/docs/runbooks/config-as-code-runbooks#snapshots-vs-commits) instead. +Version control enabled runbooks use commits instead of snapshots. If your project uses version control for runbooks, read about [snapshots vs commits](/docs/runbooks/version-control-runbooks#snapshots-vs-commits) instead. ::: 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: diff --git a/src/pages/docs/runbooks/scheduled-runbook-trigger/index.md b/src/pages/docs/runbooks/scheduled-runbook-trigger/index.md index 98f8f6bdc1..e88097c3d5 100644 --- a/src/pages/docs/runbooks/scheduled-runbook-trigger/index.md +++ b/src/pages/docs/runbooks/scheduled-runbook-trigger/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-01-01 +modDate: 2025-05-13 title: Scheduled runbook triggers description: Scheduled runbook triggers allow you to define unattended behavior for your runbook that will cause an automatic runbook run to environments of your choosing. navOrder: 40 @@ -10,7 +10,7 @@ navOrder: 40 Scheduled runbook triggers allow you to define an unattended behavior for your [runbook](/docs/runbooks) that will cause an automatic runbook run to environments of your choosing. :::div{.hint} -Only published snapshots can be used to create a scheduled runbook trigger, draft snapshots cannot be used to create a scheduled trigger. For config-as-code runbooks, scheduled runbook triggers will always run the runbook from the latest commit on your default branch. +Only published snapshots can be used to create a scheduled runbook trigger, draft snapshots cannot be used to create a scheduled trigger. For version control enabled runbooks, scheduled runbook triggers will always run the runbook from the latest commit on your default branch. ::: ## Schedule diff --git a/src/pages/docs/runbooks/version-control-runbooks.md b/src/pages/docs/runbooks/version-control-runbooks.md new file mode 100644 index 0000000000..4fd1f86cd4 --- /dev/null +++ b/src/pages/docs/runbooks/version-control-runbooks.md @@ -0,0 +1,93 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2024-11-24 +modDate: 2025-05-13 +title: Version Control Enabled Runbooks +description: Details about using version control with runbooks. +navOrder: 20 +icon: fa-brands fa-git-alt +--- + +:::div{.success} +Support for version control enabled Runbooks is rolling out to Octopus Cloud as of Q1 2025 and will be available in Octopus Server in a future release. +::: + +Version control enabled 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 version control to store your Octopus deployment process, deployment settings and non-sensitive variables. Adding version control enabled Runbooks completes that picture. + +The configuration for your runbooks, as well as your deployment process, settings and variables, are stored as OCL files which you can edit in Octopus or directly in your IDE. + +Using version control for Runbooks is currently 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. + +## Version control for 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), version control for Runbooks will be automatically enabled on your project. + +## Version control for Runbooks on an existing version controlled project + +:::div{.info} +Converting a project to use version control enabled 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 that you know what to expect before converting important projects. +::: + +You can migrate an existing version controlled project to use version control for 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 version control is that it allows you to edit your runbooks over as many branches as you would like, creating as many copies of each runbook as you have branches. This means that we no longer need 'draft' runbooks. + +When you convert your project to use version control Runbooks, only published runbooks will be available in Octopus as version control 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, it's important to consider how version control for Runbooks uses branches to handle permissions. + +## Permissions by branch + +When converting your project to version control, 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 which 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](/docs/runbooks/runbook-permissions) to help you to manage permissions around editing and running runbooks: 'Runbook Consumer' and 'Runbook Producer'. + +#### Runbook Consumer: +- Non-version control Runbooks - Runbook Consumers cannot edit runbooks and can only run published runbooks. +- Version control Runbooks - Runbook Consumers cannot edit runbooks and can only run runbooks from the latest commit on the default branch. + +#### Runbook Producer: +- Non-version control Runbooks - Runbook Producers can edit and run both draft and published runbooks. +- Version control Runbooks - Runbook Producers can edit runbooks on any unprotected branches and can run runbooks from any commit on any branch. + +Assuming your default branch is protected, this means that your old 'published' runbooks are equivalent to the runbooks in the latest commit on your default branch, and your old 'draft' runbooks are equivalent to 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 version control enabled 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 version control enabled Runbook, simply enter a commit hash on the branch selector at the top of 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 version control alongside the rest of your runbook process. + +## Scheduled triggers + +[Runbook triggers](/docs/runbooks/scheduled-runbook-trigger) will always run version control enabled Runbooks from the latest commit on your default branch, just as non-version control runbook triggers will only run published runbooks. + +## Custom automated scripts + +If you use automated scripts that run runbooks via the Octopus Server API, and you convert your runbooks to version control, the URL for the runbook will change to include a branch reference (e.g. `refs/heads/main`) as a result you need to update your scripts to include the branch reference where the runbook is stored. + +- [PowerShell example](https://github.com/OctopusDeploy/OctopusDeploy-Api/blob/master/REST/PowerShell/Runbooks/RunConfigAsCodeRunbook.ps1) + +## Deleting required resources + +Once your Runbooks are version controlled, it's up to you to take care to avoid deleting any Octopus resources required by your Runbooks. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. diff --git a/src/pages/docs/tenants/tenant-tags.md b/src/pages/docs/tenants/tenant-tags.md index 6a72dea978..b565160a19 100644 --- a/src/pages/docs/tenants/tenant-tags.md +++ b/src/pages/docs/tenants/tenant-tags.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2025-02-18 +modDate: 2025-05-13 title: Tenant tags icon: fa-solid fa-tags description: Tenant Tags help you to classify your tenants with custom tags so you can tailor your tenanted deployments accordingly. @@ -62,7 +62,7 @@ This example of configuring a tenanted deployment target shows how the tenant fi If tenant tags are tied to specific tenants, included in project/runbook release [variable snapshots](/docs/releases#variable-snapshot) (via project/variable sets), or captured in published runbooks, you will not be able to delete the relevant tag(s) until these associations are removed (by removing these from the tenant, deleting the associated release(s), or deleting published runbook snapshot(s)). Alternatively, in the case of release variable snapshots and assuming you've removed the tenant tag(s) association in the underlying project/variable set, you can update the variable snapshot that is associated with the release(s) to remove this association. -For projects using Config as Code, there are fewer guardrails in place. It's up to you to take care to avoid deleting any tenant tags required by your deployments. See our [core design decisions](/docs/projects/version-control/unsupported-config-as-code-scenarios#core-design-decision) for more information. +For projects using version control, there are fewer guardrails in place. It's up to you to take care to avoid deleting any tenant tags required by your deployments. See our [core design decisions](/docs/projects/version-control/unsupported-version-control-scenarios#core-design-decision) for more information. ## Tag-based filters {#tag-based-filters} diff --git a/src/shared-content/concepts/create-projects.include.md b/src/shared-content/concepts/create-projects.include.md index faae4f09c6..400865e412 100644 --- a/src/shared-content/concepts/create-projects.include.md +++ b/src/shared-content/concepts/create-projects.include.md @@ -25,4 +25,4 @@ To configure the project to use version control: 1. Click **Test** to verify the connection. 1. Click **Save** to save the VCS information. -Learn more about [config as code](/docs/projects/version-control). +Learn more about [version control](/docs/projects/version-control). diff --git a/src/shared-content/scripts/find-variable-usage-scripts.include.md b/src/shared-content/scripts/find-variable-usage-scripts.include.md index e73eb627fa..c4498d7d8d 100644 --- a/src/shared-content/scripts/find-variable-usage-scripts.include.md +++ b/src/shared-content/scripts/find-variable-usage-scripts.include.md @@ -120,7 +120,7 @@ foreach ($project in $projects) { # Get project variables $projectVariableSet = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/variables/$($project.VariableSetId)" -Headers $header - # Get all GitRefs for CaC project + # Get all GitRefs for version control enabled project if ($project.IsVersionControlled) { $gitBranches = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/projects/$($project.Id)/git/branches" -Headers $header $gitTags = Invoke-RestMethod -Method Get -Uri "$octopusURL/api/$($space.Id)/projects/$($project.Id)/git/tags" -Headers $header @@ -174,7 +174,7 @@ foreach ($project in $projects) { # Search Deployment process if enabled if ($searchDeploymentProcesses -eq $True) { if ($project.IsVersionControlled) { - # For CaC Projects, loop through GitRefs + # For version control enabled projects, loop through GitRefs foreach ($gitRef in $gitRefs) { $escapedGitRef = [Uri]::EscapeDataString($gitRef) $processUrl = "$octopusURL/api/$($space.Id)/projects/$($project.Id)/$($escapedGitRef)/deploymentprocesses" @@ -200,7 +200,7 @@ foreach ($project in $projects) { # Loop through each runbook foreach ($runbook in $runbooks.Items) { - # For CaC Projects, loop through GitRefs + # For version control enabled projects, loop through GitRefs if ($project.IsVersionControlled) { foreach ($gitRef in $gitRefs) { $escapedGitRef = [Uri]::EscapeDataString($gitRef) diff --git a/src/shared-content/scripts/get-steps-using-package-scripts.include.md b/src/shared-content/scripts/get-steps-using-package-scripts.include.md index 088415888c..f4086ae355 100644 --- a/src/shared-content/scripts/get-steps-using-package-scripts.include.md +++ b/src/shared-content/scripts/get-steps-using-package-scripts.include.md @@ -22,9 +22,9 @@ foreach ($project in $projectList) { $deploymentProcessLink = $project.Links.DeploymentProcess - # Check if project is Config-as-Code + # Check if project is version control enabled if ($project.IsVersionControlled) { - # Get default Git branch for Config-as-Code project + # Get default Git branch for version control enabled project $defaultBranch = $project.PersistenceSettings.DefaultBranch $deploymentProcessLink = $deploymentProcessUri -Replace "{gitRef}", $defaultBranch } diff --git a/src/shared-content/scripts/get-steps-using-role-scripts.include.md b/src/shared-content/scripts/get-steps-using-role-scripts.include.md index 53b89c010e..f50d718c2b 100644 --- a/src/shared-content/scripts/get-steps-using-role-scripts.include.md +++ b/src/shared-content/scripts/get-steps-using-role-scripts.include.md @@ -22,9 +22,9 @@ foreach ($project in $projectList) { $deploymentProcessLink = $project.Links.DeploymentProcess - # Check if project is Config-as-Code + # Check if project is version control enabled if ($project.IsVersionControlled) { - # Get default Git branch for Config-as-Code project + # Get default Git branch for version control enabled project $defaultBranch = $project.PersistenceSettings.DefaultBranch $deploymentProcessLink = $deploymentProcessLink -Replace "{gitRef}", $defaultBranch } diff --git a/tests/bookmark.spec.ts b/tests/bookmark.spec.ts index 1e8c8bf766..05655ead0e 100644 --- a/tests/bookmark.spec.ts +++ b/tests/bookmark.spec.ts @@ -79,7 +79,7 @@ const bookmarks = [ '/docs/projects/steps/execution-containers-for-workers#which-image', '/docs/projects/variables/variable-filters#json-parsing', '/docs/projects/variables/variable-substitutions#extended-syntax', - '/docs/projects/version-control/config-as-code-reference#authentication', + '/docs/projects/version-control/version-control-reference#authentication', '/docs/releases/channels#manually-create-release', '/docs/releases/channels#version-rules', '/docs/releases/deployment-changes#templates',