diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-list.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-list.webp new file mode 100644 index 0000000000..fe94c61eba Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-list.webp differ diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-onboarding.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-onboarding.webp new file mode 100644 index 0000000000..9c6b045dd1 Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-onboarding.webp differ diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-parameters.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-parameters.webp new file mode 100644 index 0000000000..490fa3e72e Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-parameters.webp differ diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-process-editor.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-process-editor.webp new file mode 100644 index 0000000000..c1517d54e0 Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-process-editor.webp differ diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-process-overview.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-process-overview.webp new file mode 100644 index 0000000000..166e91bffd Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-process-overview.webp differ diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-usage.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-usage.webp new file mode 100644 index 0000000000..7a6e33108d Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-usage.webp differ diff --git a/public/docs/i/1000/platform-hub/project-templates/project-templates-variables.webp b/public/docs/i/1000/platform-hub/project-templates/project-templates-variables.webp new file mode 100644 index 0000000000..5a6ecbd738 Binary files /dev/null and b/public/docs/i/1000/platform-hub/project-templates/project-templates-variables.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-list.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-list.webp new file mode 100644 index 0000000000..6319895475 Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-list.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-onboarding.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-onboarding.webp new file mode 100644 index 0000000000..5cad19a915 Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-onboarding.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-parameters.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-parameters.webp new file mode 100644 index 0000000000..7b386dbf2f Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-parameters.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-process-editor.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-process-editor.webp new file mode 100644 index 0000000000..42d79cb73f Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-process-editor.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-process-overview.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-process-overview.webp new file mode 100644 index 0000000000..63834f29f5 Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-process-overview.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-usage.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-usage.webp new file mode 100644 index 0000000000..9744290b78 Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-usage.webp differ diff --git a/public/docs/i/2000/platform-hub/project-templates/project-templates-variables.webp b/public/docs/i/2000/platform-hub/project-templates/project-templates-variables.webp new file mode 100644 index 0000000000..8f99446ff1 Binary files /dev/null and b/public/docs/i/2000/platform-hub/project-templates/project-templates-variables.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-list.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-list.webp new file mode 100644 index 0000000000..6d4dd0b6ae Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-list.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-onboarding.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-onboarding.webp new file mode 100644 index 0000000000..47b45e9434 Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-onboarding.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-parameters.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-parameters.webp new file mode 100644 index 0000000000..22f4c0fc5a Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-parameters.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-process-editor.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-process-editor.webp new file mode 100644 index 0000000000..5c954a0ac4 Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-process-editor.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-process-overview.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-process-overview.webp new file mode 100644 index 0000000000..dc305eae7c Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-process-overview.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-usage.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-usage.webp new file mode 100644 index 0000000000..c2a41dd80a Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-usage.webp differ diff --git a/public/docs/i/600/platform-hub/project-templates/project-templates-variables.webp b/public/docs/i/600/platform-hub/project-templates/project-templates-variables.webp new file mode 100644 index 0000000000..0b13839004 Binary files /dev/null and b/public/docs/i/600/platform-hub/project-templates/project-templates-variables.webp differ diff --git a/public/docs/i/x/platform-hub/process-template-parameters.png b/public/docs/i/x/platform-hub/process-template-parameters.png index 8e6d08c913..7c0c3f1eed 100644 Binary files a/public/docs/i/x/platform-hub/process-template-parameters.png and b/public/docs/i/x/platform-hub/process-template-parameters.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-list.png b/public/docs/i/x/platform-hub/project-templates/project-templates-list.png new file mode 100644 index 0000000000..2b071f7874 Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-list.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-onboarding.png b/public/docs/i/x/platform-hub/project-templates/project-templates-onboarding.png new file mode 100644 index 0000000000..29f92f1284 Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-onboarding.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-parameters.png b/public/docs/i/x/platform-hub/project-templates/project-templates-parameters.png new file mode 100644 index 0000000000..d7125ca6aa Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-parameters.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-process-editor.png b/public/docs/i/x/platform-hub/project-templates/project-templates-process-editor.png new file mode 100644 index 0000000000..37d4f3b065 Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-process-editor.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-process-overview.png b/public/docs/i/x/platform-hub/project-templates/project-templates-process-overview.png new file mode 100644 index 0000000000..fea8677b23 Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-process-overview.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-usage.png b/public/docs/i/x/platform-hub/project-templates/project-templates-usage.png new file mode 100644 index 0000000000..7734f89add Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-usage.png differ diff --git a/public/docs/i/x/platform-hub/project-templates/project-templates-variables.png b/public/docs/i/x/platform-hub/project-templates/project-templates-variables.png new file mode 100644 index 0000000000..0dad5aa14e Binary files /dev/null and b/public/docs/i/x/platform-hub/project-templates/project-templates-variables.png differ diff --git a/public/docs/img/platform-hub/project-templates/project-templates-list.png b/public/docs/img/platform-hub/project-templates/project-templates-list.png new file mode 100644 index 0000000000..360ac08e99 Binary files /dev/null and b/public/docs/img/platform-hub/project-templates/project-templates-list.png differ diff --git a/public/docs/img/platform-hub/project-templates/project-templates-list.png.json b/public/docs/img/platform-hub/project-templates/project-templates-list.png.json new file mode 100644 index 0000000000..996e0f6029 --- /dev/null +++ b/public/docs/img/platform-hub/project-templates/project-templates-list.png.json @@ -0,0 +1 @@ +{"width":3414,"height":1958,"updated":"2026-03-09T23:21:06.499Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/project-templates/project-templates-onboarding.png b/public/docs/img/platform-hub/project-templates/project-templates-onboarding.png new file mode 100644 index 0000000000..eaa3da0c94 Binary files /dev/null and b/public/docs/img/platform-hub/project-templates/project-templates-onboarding.png differ diff --git a/public/docs/img/platform-hub/project-templates/project-templates-onboarding.png.json b/public/docs/img/platform-hub/project-templates/project-templates-onboarding.png.json new file mode 100644 index 0000000000..5d747596c7 --- /dev/null +++ b/public/docs/img/platform-hub/project-templates/project-templates-onboarding.png.json @@ -0,0 +1 @@ +{"width":3430,"height":1828,"updated":"2026-03-09T23:21:06.549Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/project-templates/project-templates-parameters.png b/public/docs/img/platform-hub/project-templates/project-templates-parameters.png new file mode 100644 index 0000000000..a3d3c3ddf7 Binary files /dev/null and b/public/docs/img/platform-hub/project-templates/project-templates-parameters.png differ diff --git a/public/docs/img/platform-hub/project-templates/project-templates-parameters.png.json b/public/docs/img/platform-hub/project-templates/project-templates-parameters.png.json new file mode 100644 index 0000000000..435f2a2829 --- /dev/null +++ b/public/docs/img/platform-hub/project-templates/project-templates-parameters.png.json @@ -0,0 +1 @@ +{"width":3438,"height":1930,"updated":"2026-03-09T23:21:06.650Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/project-templates/project-templates-process-editor.png b/public/docs/img/platform-hub/project-templates/project-templates-process-editor.png new file mode 100644 index 0000000000..e6d56545e2 Binary files /dev/null and b/public/docs/img/platform-hub/project-templates/project-templates-process-editor.png differ diff --git a/public/docs/img/platform-hub/project-templates/project-templates-process-editor.png.json b/public/docs/img/platform-hub/project-templates/project-templates-process-editor.png.json new file mode 100644 index 0000000000..45afa81b08 --- /dev/null +++ b/public/docs/img/platform-hub/project-templates/project-templates-process-editor.png.json @@ -0,0 +1 @@ +{"width":3428,"height":1982,"updated":"2026-03-09T23:35:20.646Z"} \ No newline at end of file diff --git a/public/docs/img/platform-hub/project-templates/project-templates-variables.png b/public/docs/img/platform-hub/project-templates/project-templates-variables.png new file mode 100644 index 0000000000..eaa8ed129e Binary files /dev/null and b/public/docs/img/platform-hub/project-templates/project-templates-variables.png differ diff --git a/public/docs/img/platform-hub/project-templates/project-templates-variables.png.json b/public/docs/img/platform-hub/project-templates/project-templates-variables.png.json new file mode 100644 index 0000000000..6adf684027 --- /dev/null +++ b/public/docs/img/platform-hub/project-templates/project-templates-variables.png.json @@ -0,0 +1 @@ +{"width":3446,"height":1972,"updated":"2026-03-09T23:21:06.848Z"} \ No newline at end of file diff --git a/src/pages/docs/platform-hub/index.md b/src/pages/docs/platform-hub/index.md index 1f7c508347..d101257a79 100644 --- a/src/pages/docs/platform-hub/index.md +++ b/src/pages/docs/platform-hub/index.md @@ -13,13 +13,14 @@ navOrder: 32 [Platform Hub](https://octopus.com/blog/introducing-platform-hub) is a new capability in Octopus that helps platform teams standardize how software is delivered across teams using connected templates and enforceable policies. Together, these features create a governance layer for software delivery, making it easier for platform teams to scale best practices, reduce drift, and deliver with confidence. -You can create and manage your process templates and policies from Platform Hub. +You can create and manage your templates and policies from Platform Hub. -- [Process templates](/docs/platform-hub/process-templates) are reusable sets of deployment steps that can be shared across multiple spaces in Octopus Deploy +- [Process templates](/docs/platform-hub/templates/process-templates) are reusable sets of deployment steps that can be shared across multiple spaces in Octopus Deploy +- [Project templates](/docs/platform-hub/templates/project-templates) are reusable project blueprints that teams use as a starting point for new projects. Teams supply the required parameter values but can't modify the deployment process. - [Policies](/docs/platform-hub/policies) in Octopus are designed to ensure compliance and governance by default, making enforcing pre- and post-deployment controls at scale easier. :::div{.hint} -To access Platform Hub users must have **PlatformHubEdit** and **PlatformHubView** permissions enabled. These permissions can only be assigned to system teams. +To access Platform Hub users must have **PlatformHubEdit** and **PlatformHubView** permissions enabled. These permissions can only be assigned to system teams. [System administrators](/docs/security/users-and-teams/default-permissions#DefaultPermissions-SystemAdministrator) and [system managers](/docs/security/users-and-teams/default-permissions#DefaultPermissions-SystemManager) have **PlatformHubEdit** and **PlatformHubView** permissions enabled by default. ::: @@ -33,7 +34,7 @@ To get started, configure your version control. This Git repository will be used for all features in Platform Hub. ::: -### Accounts in Platform Hub +## Accounts in Platform Hub You can create and manage accounts in Platform Hub that can be used inside process templates. @@ -51,10 +52,10 @@ To use these accounts inside a process template, you must create a parameter tha ![Accounts in Platform Hub](/docs/img/platform-hub/platform-hub-accounts.png) ::: -### Git Credentials in Platform Hub +## Git Credentials in Platform Hub You can create and manage Git credentials in Platform Hub by visiting the Git credentials area in the Platform Hub navigation menu. You can use Git credentials inside your process templates by selecting them from a dropdown in the step field that requires them. :::figure ![Platform Hub Git credentials area](/docs/img/platform-hub/platform-hub-git-credential.png) -::: \ No newline at end of file +::: diff --git a/src/pages/docs/platform-hub/process-templates/best-practices.md b/src/pages/docs/platform-hub/process-templates/best-practices.md index e68caee6a0..89f087aeb7 100644 --- a/src/pages/docs/platform-hub/process-templates/best-practices.md +++ b/src/pages/docs/platform-hub/process-templates/best-practices.md @@ -1,208 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2025-09-11 -modDate: 2025-09-11 -title: Process Templates best practices -subtitle: Best practices for creating process templates within Platform Hub -icon: fa-solid fa-lock -navTitle: Best Practices -navSection: Process Templates -description: Best practices for creating process templates within Platform Hub -navOrder: 160 +layout: src/layouts/Redirect.astro +redirect: /docs/platform-hub/templates/process-templates/best-practices +navMenu: false +navSearch: false +navSitemap: false +pubDate: 2026-03-05 +title: Process templates best practices (redirected) --- - -This document uses **Producer** and **Consumer** frequently. To avoid confusion, use these definitions: - -- **Producer** - the user who creates and manages process templates in Platform Hub. -- **Consumer** - the user who uses the process templates in their deployment or runbook processes. - -## Process templates administration - -### Establish a naming standard - -Use a [ Prefix ] - [ Template Name ] that is easy for everyone to understand the template's purpose. The [ Template Name ] should be succinct and informative. - -The [ Prefix ] should inform everyone where the template should be used. For example: - -- Deploy Process - [ Template Name ] for templates designed for deployments only. -- Runbook - [ Template Name ] for templates designed for runbooks only. -- Deploy and Runbook - [ Template Name ] for templates that can be used in deployments or runbooks. - -:::figure -![A list of process templates with the appropriate prefix and template name](/docs/img/platform-hub/process-templates/process-templates-overview-screen.png) -::: - -### Establish what the major/minor/patch/pre-release means to your company - -Process templates' versioning provides hints: - -- Major (breaking changes) -- Minor (non-breaking changes) -- Patch (bug fixes) -- Pre-Release - -There will be confusion unless you define what a breaking vs. non-breaking change means to you and your company. - -A starting point of a policy can be: - -- **Major** — The change requires the consumer to test it. The template changes how it fundamentally works, and it might delete existing parameters or add new ones. A consumer updating the template requires a PR in their project. -- **Minor** — The change generally doesn’t require the consumer to test it extensively, but it might have added or removed a parameter, which will require a PR by the consumer because it changes the deployment process. -- **Patch** No parameters were added or removed, and testing isn’t required (except by the consumer who reported the bug). The consumer doesn’t require a PR as the deployment process OCL doesn’t change. -- **Pre-Release** - Use for changes that aren’t ready for general use. - -### Leverage branch protection policies on the Platform Hub Git repository - -Template changes should occur in a branch and be reviewed via a PR. To test the changes, use the Pre-Release feature within the versioning functionality. - -## Building Templates - -### Opt for several smaller templates over "all-in-one" templates - -Creating a single process template containing all the steps required to deploy an application can be tempting. In practice, the "all-in-one" template falls apart at scale. - -#### Not all applications use the same components - -Consider this example: - -- Application #1 - Deploys a container to Kubernetes with a SQL Server Backend -- Application #2 - Deploys a container to Kubernetes that monitors a queue - -No matter what, you will create two templates. - -- Option #1 - Create a template for each application combination - - Kubernetes + SQL Server - - Kubernetes + Queue -- Option #2 - Create a template for each component - - Kubernetes - - SQL Server - -With option #2, you’ll have templates that can be mixed and matched with other application types. For example, the SQL Server template can be used for .NET apps running on Azure Web Apps, Linux, or Windows. - -#### Some applications require steps before or after templates - -Consider this deployment process: - -:::figure -![A deployment process using process templates with a step between two templates](/docs/img/platform-hub/process-templates/process-templates-requiring-steps-between-template-steps.png) -::: - -It uses three process templates, but they don’t all run back to back to back. Between the first process template, `Verify Build Artifacts`, and the second process template, `Deploy Databases`, a step to verify the infrastructure runs. Not all applications need that specific step to run between those templates. - -Having multiple process templates allows application teams to insert steps before or after specific actions are performed. - -#### A template for everybody is a template for nobody - -A large all-in-one template requires significant complexity to account for multiple use cases. We’ve seen all-in-one templates follow the same pattern: - -1. The template starts out simple. -2. More use cases are encountered and additional steps are added. Steps solely focused on business logic and creating output variables become the norm. -3. Conditional run conditions for multiple steps become the default. The template becomes very brittle as people need to “hold it just right” for everything to work. -4. Conditional steps start to fail randomly, or steps are skipped randomly because of a configuration change. -5. Consumers are forced to update the templates repeatedly to fix the ever-growing list of bugs. -6. Consumers start asking for the ability to cherry-pick steps when running the template. - -Eventually, the template becomes unusable, and users want a complete rewrite or ask how they can get out of using the templates. - -### Follow the single responsibility principle - -A template should have a single purpose. That doesn’t mean a single step, but a singular purpose that is easy for consumers to understand. Some examples include: - -- Template to create a database on a server -- Template to destroy that database -- Template to verify build artifacts -- Template to deploy and verify an application on a Kubernetes cluster -- Template to deploy a database change - -The template should include all the necessary steps to accomplish that task. Consider a template to deploy a database change. The company policy might be build a delta report and verify it before deploying. But DBAs don’t need to be bothered with every change, so only bother them when specific commands appear. For example, `Drop Database`. To accomplish that, the template would be: - -:::figure -![A process template that deploys databases with all the necessary steps to accomplish the task](/docs/img/platform-hub/process-templates/process-template-to-deploy-databases.png) -::: - -### Parameters - -Parameters should be the only way for information to be sent from consumers' deployment and runbook processes to process templates. - -- Templates should not explicitly rely on output variables from other process templates. Template B shouldn’t have a hard-coded output variable from template A. -- Templates should not hardcode the names of project variables or variable set variables. They must be sent in via parameters. -- Any external references for items outside of Platform Hub - secrets, feeds, worker pools, tags - must be sent in via parameters. - -### Templates must be self-contained - -A template should not expect other templates to be included in the deployment or runbook process. - -- Use parameters for all inputs. -- The consumer, not the producer, should determine the order of the templates in the process. The consumer has context regarding the order of component deployments. -- All steps needed to accomplish the template's task must be included. - -### Keep consumer decision-making to a minimum - -The consumer shouldn’t need to worry about: - -- The number of steps required to accomplish a task -- The steps that can be skipped based on a decision within the template (alerting a DBA if the Drop Database command is found) -- The specific logic of how a task is accomplished. - -A consumer should be able to say: - -> I want to deploy to Kubernetes and verify the deployment using this information: -> -> - The container URL -> - The Git repository of the manifest files -> - The path to manifest files in that repository -> - The target tag of the cluster to deploy to -> - The verification script to run - -It is the producer's job to figure out how to takes those parameters and deploy the container to Kubernetes. - -### Include notes for each step in the process template - -Notes help the consumer understand the intent behind each step. If a deployment fails, it is easier for them to self-service why the failure occurs if they have that context. Sometimes, a step name is all that is required to understand the intent. However, assuming everyone will understand the context based on the name alone is dangerous. It is better to include notes by default. - -:::figure -![Deploy process using process templates that leverage notes](/docs/img/platform-hub/process-templates/deploy-process-using-process-templates-with-notes.png) -::: - -## Producer-managed script steps in templates - -A process template has two options for the `Run a script` step. - -1. Consumer-managed script steps, such as running a verification step after a deployment. The producer will not know the necessary tests to run, so they will ask the consumer to provide the script for the tests. -2. Producer-managed script steps, such as creating a delta report from the provided database package and looking for dangerous commands. The script is created and managed by the producer to accomplish the goal of the template. - -This section refers to the latter, producer-managed script steps. - -### Store the script inline with the template - -Since the template is already in version control, referencing another git repo for the script is redundant. - -If multiple templates need to reference the same script, that indicates they are doing too much. They likely aren’t following the above best practices (single responsibility principle, self-contained, etc.). - -### Output variables intended for business decisions should only be used by the template - -It is common for a script step to make a set of decisions and create an output variable. For example, the first step in this template looks for dangerous commands in the migration scripts and sets an output variable when those commands are found. - -Those kinds of output variables should only be used by the template itself. - -:::figure -![A process template that makes a business decision in the first step and uses output variables in the next two steps](/docs/img/platform-hub/process-templates/process-template-to-deploy-databases.png) -::: - -### Output variables must be surfaced via logs when intended for outside steps to use - -When a template explicitly creates output variables to be used by other steps they must be logged for the consumer to know. For example, a template that retrieves values from a key vault and sets them as output variables. - -- When possible, allow the consumer to provide a list of output variables - for example, telling the key vault which secrets to retrieve. -- When that is not possible, log all the output variables created. -- If another process template will use those output variables, they should be sent in as parameters. There should never be a hard link between templates. - -### Log everything - -Octopus supports different levels of logs: - -- Write-Verbose - writes a verbose log (hidden by default) -- Write-Info - writes an info log (visible on task log screen by default) -- Write-Highlight - writes the information to the task summary screen -- Write-Error - writes an error message - -Use those log levels and write messages frequently. This aids in debugging when a deployment or runbook run fails. Logs are like an umbrella - better to have it and not need it than need it and not have it. diff --git a/src/pages/docs/platform-hub/process-templates/index.md b/src/pages/docs/platform-hub/process-templates/index.md index ebf6a2a3fc..d466bb77d9 100644 --- a/src/pages/docs/platform-hub/process-templates/index.md +++ b/src/pages/docs/platform-hub/process-templates/index.md @@ -1,222 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2025-09-23 -modDate: 2025-11-20 -title: Process templates -subtitle: An overview of Process Templates -icon: fa-solid fa-layer-group -navTitle: Overview -navSection: Process Templates -description: An overview of Process Templates -navOrder: 150 +layout: src/layouts/Redirect.astro +redirect: /docs/platform-hub/templates/process-templates +navMenu: false +navSearch: false +navSitemap: false +pubDate: 2026-03-05 +title: Process templates (redirected) --- -## Overview - -Process templates are reusable sets of deployment steps that can be shared across multiple spaces in Octopus Deploy. Instead of copying and pasting deployment processes across teams and applications, which often leads to configuration drift, unnecessary duplication, and operational debt, you create a single source of truth that any project can consume. By abstracting your best practices for deployments into Process Templates, you make it easy for teams to follow standards and accelerate delivery. - -To create or manage your process templates, navigate to Platform Hub. If you haven't set up your Git repository, you must do so first before creating a process template. Similarly, if you've already created templates or are joining an existing team, you'll see the existing templates on the template overview. - -:::figure -![The Process Templates Overview page where users create process templates](/docs/img/platform-hub/process-template-overview.png) -::: - -Before you can define the deployment process for your template, you must create the template first. - -1. Navigate to Process Templates in Platform Hub. -2. Give the process template a **NAME** and an optional **DESCRIPTION** -3. Create your process template. - -:::figure -![The experience after creating the template with a name and description](/docs/img/platform-hub/process-template-first-creation.png) -::: - -You've created your process template; now, define its deployment process. - -A deployment process is a set of steps the Octopus Server orchestrates to deploy your software. Each process template has a single deployment process. You can use Octopus's built-in steps to define this process for your process template. - -:::figure -![The add step experience for a process template](/docs/img/platform-hub/process-template-add-step.png) -::: - -Some steps look different inside a process template. They ask for a parameter rather than allowing you to define a value. These steps ask for a resource that Platform Hub cannot define, such as Worker Pools, and you must define them inside a project. These fields accept parameters so you can define the values the process template needs inside a project. - -:::figure -![The run a script step asks for a worker pool parameter instead of a worker pool](/docs/img/platform-hub/process-template-step-example.png) -::: - -:::div{.warning} -Our initial release of Process Templates does not include support for a few built-in steps. -::: - -Once you have set up a deployment process, you can use it in any space for a deployment or runbook. - -## Parameters - -Parameters help you easily manage and apply the correct values during a deployment or runbook run that uses a process template. Using parameters, you can use the same process template across your projects and tailor the inputs based on the projects needs. - -Process Templates can manage the following as parameters. - -- AWS Account -- Azure Account -- Certificate -- Channels -- Checkbox -- Container Feed -- Drop down -- Environments -- Generic OIDC Account -- Google Cloud Account -- Multi-line text box -- Sensitive/password box -- Single-line text box -- Target Tags -- Teams -- Tenant Tags -- Username Password Account -- Worker Pool -- A previous step name - -To create a parameter, you can navigate to the parameters tab on a process template and add a new parameter. - -:::figure -![The parameters section in a process template](/docs/img/platform-hub/process-template-parameters.png) -::: - -### Parameter values - -You can set an optional default value for these parameters: - -- Single-line text -- Multi-line text -- Dropdown -- Checkbox -- Sensitive/password box -- AWS Account -- Azure Account -- Generic OIDC Account -- Google Cloud Account -- Username Password Account - -You cannot set a default value for these parameters, they must be set inside a project: - -- Certificate -- Worker Pools -- Package -- Previous deployment step name -- Target Tags -- Teams -- Tenant Tags -- Environments -- Container Feed -- Channels - -### Sensitive parameter defaults - -:::div{.hint} -The ability to add default values for Sensitive/password box parameters is available from **Octopus 2026.1**. -::: - -Unlike the other parameters, sensitive default values are stored securely in the database with a unique GUID identifier. This identifier is used in the process template to reference the default sensitive value in the database. Because of this approach, sensitive default values are supported in CaC workflows. Scoping for Sensitive/password box parameters is not currently supported. - -You can set a default value for your sensitive parameter by navigating to the parameters tab of your process template and committing your changes. When the template is saved, sensitive default values are stored encrypted in the database with a unique identifier. In the OCL, the parameter block will look something like this: - -```hcl -parameter "Example Sensitive Parameter" { - display_settings = { - Octopus.ControlType = "Sensitive" - } - help_text = "An Example Sensitive Parameter" - label = "An Example Sensitive Parameter" - - value "10d00c16-c905-43fa-90cd-088e22b31751" {} -} -``` - -The GUID value in the OCL is a reference to the database-stored sensitive value. When the process template is used in a project or runbook, it will retrieve the sensitive value from the database. - -### Parameter scoping - -Only Account parameters will allow you to scope them by environments. You can choose to scope them by any environment across your Octopus instance. - -:::div{.hint} -When a process template is used inside a project, the project supplied values will take precedence over the process template provided ones for overlapping scopes. This includes unscoped project supplied values. For more information on how the precedence works, please visit the [troubleshooting page](/docs/platform-hub/process-templates/troubleshooting) -::: - -:::figure -![The account parameter allowing scoping to environments present across Octopus instance](/docs/img/platform-hub/process-templates-account-scoping.png) -::: - -## Saving a Process Template - -Once you've finished making changes to your process template you can commit them to save the changes to your Git repository. You can either **Commit** with a description or quick commit without one. - -:::figure -![The commit experience for a process template](/docs/img/platform-hub/process-templates-commit-experience.png) -::: - -## Publishing a Process Template - -Once you've made your changes, you will have to publish the template to reflect the changes you've made. You will have three options to choose from when publishing changes: - -- Major changes (breaking) -- Minor changes (non-breaking) -- Patch (bug fixes) - -You can also optionally publish a pre-release version, which can be used to test the template. - -:::div{.hint} -The first time you publish a template you can only publish a major or pre-release version -::: - -Selecting any option increments the version number following Semantic Versioning. For minor or patch updates, projects that accept these changes will automatically upgrade to the newly published version. - -:::figure -![Publish experience for a process template](/docs/img/platform-hub/process-templates-publishing.png) -::: - -### Pre-releases - -If you wish to test your changes before publishing a major, minor, or patch version, you can mark a template as a pre-release version. - -:::figure -![Marking a process template as pre-release](/docs/img/platform-hub/process-template-prerelease.png) -::: - -## Sharing a template - -You must share the process template before it can be consumed by any projects. Process templates can be shared with all current and future spaces, or a select few spaces. - -:::div{.hint} -Sharing settings can be updated anytime. -::: - -![Sharing experience for process templates](/docs/img/platform-hub/process-template-sharing.png) - -## A Hello world deployment process in a process template - -To define a simple deployment process in Octopus that executes a hello world script on the Octopus Server, complete the following steps: - -1. Navigate to **Platform Hub** -2. Add a process template -3. Name the template, for instance, "Hello World", and add an optional description. -4. Add a deployment step. -5. Choose the type of step you'd like to add to filter the available steps. -6. Find the **Run a Script** step and add it to your deployment process. -7. In the Process Editor, give the step a name, for instance "Run a Hello World script". -8. In the Execution Location section use the **Run on the worker pool parameter** option. -9. Create a Worker Pool parameter. -10. Add the Worker Pool parameter to the **Worker Pool** field. -11. Paste the following PowerShell script into the **Inline Source Code** editor: - - ```powershell - Write-Host "Hello, World!" - ``` - -12. Commit your template. -13. Publish and Share your template. -14. Visit a project, and its deployment process -15. Choose the process template you just published -16. Choose the Worker Pool in the parameters tab -17. Add any steps before or after the process template - -You can now deploy this process to say "Hello, World!". diff --git a/src/pages/docs/platform-hub/process-templates/troubleshooting.md b/src/pages/docs/platform-hub/process-templates/troubleshooting.md index b517ef29d7..a0e4f68af6 100644 --- a/src/pages/docs/platform-hub/process-templates/troubleshooting.md +++ b/src/pages/docs/platform-hub/process-templates/troubleshooting.md @@ -1,245 +1,9 @@ --- -layout: src/layouts/Default.astro -pubDate: 2025-09-23 -modDate: 2025-11-20 -title: Troubleshooting -subtitle: Known issues that you may run into -icon: fa-solid fa-layer-group -navTitle: Troubleshooting -navSection: Process Templates -description: Known issues and limitations for process templates -navOrder: 151 +layout: src/layouts/Redirect.astro +redirect: /docs/platform-hub/templates/process-templates/troubleshooting +navMenu: false +navSearch: false +navSitemap: false +pubDate: 2026-03-05 +title: Process templates troubleshooting (redirected) --- - -## Troubleshooting common issues - -You may run into a few issues when setting up your process templates. We've put together this page to help you diagnose and fix common issues. - -### Step support - -Process templates currently supports most Octopus steps. It currently doesn't support the following: - -1. Deploy a Bicep Template -2. AWS S3 Create Bucket -3. AWS ECS - -This document will be updated as additional step support is added. - -### Parameters and Variables - -If you are migrating an existing process to be used as a process template, you may run into a few issues when using parameters and variables in scripts. When copying a script from a step in a project into a process template step, you must convert project variables to use process template parameters. System variables will still work as normal. - -For example, consider this script that directly references project and system variables via `OctopusParameters`. - -``` -$packagePath = $OctopusParameters["Octopus.Action.Package[Trident.Database].ExtractedPath"] -$connectionString = $OctopusParameters["Project.Connection.String"] -$environmentName = $OctopusParameters["Octopus.Environment.Name"] -$reportPath = $OctopusParameters["Project.Database.Report.Path"] - -cd $packagePath -$appToRun = ".\Octopus.Trident.Database.DbUp" -$generatedReport = "$reportPath\UpgradeReport.html" - -& $appToRun --ConnectionString="$connectionString" --PreviewReportPath="$reportPath" - -New-OctopusArtifact -Path "$generatedReport" -Name "$environmentName.UpgradeReport.html" -``` - -The following variables should be updated to reference process templates parameters instead of project variables: - -1. `$packagePath` -2. `$connectionString` -3. `$reportPath` - -The `$environmentName` variable is fine, as system variables will continue to work as normal. The updated script will be: - -``` -$packagePath = $OctopusParameters["Octopus.Action.Package[Template.Database.Package].ExtractedPath"] -$connectionString = $OctopusParameters["Template.Database.ConnectionString"] -$environmentName = $OctopusParameters["Octopus.Environment.Name"] -$reportPath = $OctopusParameters["Template.Database.ChangeReportDirectory"] - -cd $packagePath -$appToRun = ".\Octopus.Trident.Database.DbUp" -$generatedReport = "$reportPath\UpgradeReport.html" - -& $appToRun --ConnectionString="$connectionString" --PreviewReportPath="$reportPath" - -New-OctopusArtifact -Path "$generatedReport" -Name "$environmentName.UpgradeReport.html" -``` - -### Parameter scoping - -Project supplied values for parameters will always take precedence over process template supplied ones. - -A couple scenarios that demonstrate the scoping precedence: - -
- -**1. Scoped value provided by the project and the process template.** - -| Origin | Name | Value | Scope | -|------------------|--------------|------------------|-------------| -| Process Template | AzureAccount | Account-123 | Development | -| Project | AzureAccount | Account-124 | Development | - -When deploying to the **Development** environment, **Account-124** would be used. - -
- -**2. Scoped value provided by the process template and an unscoped value provided by the project.** - -| Origin | Name | Value | Scope | -|------------------|--------------|------------------|-------------| -| Process Template | AzureAccount | Account-123 | Development | -| Project | AzureAccount | Account-124 | | - -When deploying to the **Development** environment, **Account-124** would be used. - -
- -**3. Scoped process template value and scoped project value for different environments.** - -| Origin | Name | Value | Scope | -|------------------|--------------|------------------|-------------| -| Process Template | AzureAccount | Account-123 | Development | -| Project | AzureAccount | Account-124 | Staging | - -- When deploying to the **Development** environment, **Account-123** would be used. -- When deploying to the **Staging** environment, **Account-124** would be used. - -
- -### Step specific issues - -- You cannot configure **Edit YAML** on the **Configure and apply Kubernetes resource** step. -- You cannot configure cloud target discovery on steps. You must use project variables when consuming a process template in a project instead. -- When referencing a file from a Git repo, for example, script, manifest, Kustomize, etc., you cannot pick the project Git repository as the source. You must supply the Git repository URL. The URL can be passed in via a parameter or hardcoded in the template itself. Hardcoding is not recommended. - -### Cloning process templates - -You cannot clone a process template in Platform Hub through the Octopus UI. The process for cloning a process template is: - -1. Clone the process template OCL file in the Platform Hub Git repository. -2. Change the name of the cloned OCL file to the desired name. -3. Change the name of the process template in the OCL file. -4. Commit and push the changes. -5. Refresh the process template list in the Octopus Deploy UI and find the newly created template. -6. Publish the template and configure the Spaces that have access to it. - -### Platform Hub account limitations - -The following account types are not supported: - -1. Token -2. SSH - -Platform Hub accounts cannot be used in the following situations: - -- Cannot be used by targets. -- Cannot be used in Cloud Target Discovery. - -### Public API - -Process templates can be created and managed through our [public API](/docs/octopus-rest-api). - -- Process templates are stored as code in the configured Git repository. The OCL files store all relevant information about the template - including the parameters, the steps, name, description and other settings. -- The published versions and Spaces configured are stored and managed via the database. - -:::div{.warning} -We do not currently support creating or managing process templates through the CLI or the Terraform provider. -::: - -See [CreateProcessTemplateUsageStep](https://github.com/OctopusDeploy/OctopusDeploy-Api/blob/master/Octopus.Client/Csharp/DeploymentProcesses/CreateProcessTemplateUsageStep.cs) for an example of how to configure a process template on a deployment process using [Octopus.Client](/docs/octopus-rest-api/octopus.client). - -### GitHub Connections - -The GitHub Connection is not supported in Platform Hub. Only usernames and PATs. - -### Losing access to an Octopus Enterprise license - -Process templates and all Platform Hub features are restricted to customers who have an Enterprise Tier license. When you no longer have an Enterprise license, process templates will work differently. - -#### What will continue to work - -- Existing deployments and runbook runs can be redeployed or rerun. -- New releases that have a process containing process templates can be created. -- New runbook runs that have a process containing process templates can be created. -- Auto-scheduled deployments or runbook runs will continue to work. - -#### What will not work anymore - -- Users will lose access to Platform Hub, including the ability to create and manage all Platform Hub features. -- Process templates cannot be modified inside a project. -- Process templates will no longer receive updates and automatically roll forward to a later version. -- Projects that contain process templates cannot be cloned until the process template is removed. - -### Output Variables - -To reference output variables from process template steps, add `.ProcessTemplate` to the standard output variable syntax. - -When referencing an output variable in a step **inside a process template**, use the format: - -``` -Octopus.ProcessTemplate.Action[StepName].Output.PropertyName -``` - -
- -When referencing an output variable in a step **outside a process template**, include the name of the process template usage step as it appears in the project. - -``` -Octopus.ProcessTemplate[ProcessTemplateUsageStepName].Action[StepName].Output.PropertyName -``` - -#### Example -Consider a process template named **Build and Create Web App** containing a step that runs a script and publishes an output variable `FilePath`: - -``` -name = "Build and Create Web App" -description = "" - -step "run-a-script" { - name = "Collect Details" - - action { - action_type = "Octopus.Script" - ... - } - ... -} -``` - -Reference the variable from another step **inside** the process template using: - -``` -Octopus.ProcessTemplate.Action[Collect Details].Output.FilePath -``` - -
- -When this process template is used in a project with a process template usage step named **Create Web App**: - -``` -process_template "run-a-process-template" { - name = "Create Web App" - process_template_slug = "build-and-create-web-app" - version_mask = "1.X" - - parameter "linux worker" { - value = "WorkerPools-1" - } - ... -} -``` - -Reference the variable from any other step in the process, which is **outside** the process template, using: - -``` -Octopus.ProcessTemplate[Create Web App].Action[Collect Details].Output.FilePath -``` - -:::div{.hint} -Use the name of the process template usage step from the project, not the name of the process template itself, when referencing output variables outside a process template. -::: \ No newline at end of file diff --git a/src/pages/docs/platform-hub/templates/index.md b/src/pages/docs/platform-hub/templates/index.md new file mode 100644 index 0000000000..1d008e6b3b --- /dev/null +++ b/src/pages/docs/platform-hub/templates/index.md @@ -0,0 +1,26 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-03-05 +modDate: 2026-03-06 +title: Templates +subtitle: Reusable templates for processes and projects in Platform Hub +icon: fa-solid fa-layer-group +navTitle: Overview +navSection: Templates +description: An overview of templates in Platform Hub +navOrder: 140 +--- + +## Overview + +Platform Hub provides two types of templates that help you standardize and share your deployment configuration across spaces. + +**[Process templates](/docs/platform-hub/templates/process-templates)** are reusable sets of deployment steps. Instead of copying and pasting deployment processes across projects, you define the steps once and share them. Teams can opt into using a process template within their deployment process, and can remove it if it no longer fits their needs. + +**[Project templates](/docs/platform-hub/templates/project-templates)** give platform engineering teams a way to define a golden path for how projects are structured. The deployment process is defined by the template and can't be modified in projects based on it. Through parameters exposed by the platform team, project teams can deploy using their own packages, accounts, worker pools, and target tags, while the underlying process stays consistent across every project based on the template. + +Both template types use [parameters](/docs/platform-hub/templates/parameters) to expose configurable inputs, letting you define what a project must supply while keeping the core template consistent across teams and spaces. + +## Prerequisites + +Before creating any template, you must configure a Git repository in [Platform Hub](/docs/platform-hub). This repository stores your templates as code (OCL files) and is the single source of truth for all template changes. diff --git a/src/pages/docs/platform-hub/templates/parameters.md b/src/pages/docs/platform-hub/templates/parameters.md new file mode 100644 index 0000000000..23a8ad82ef --- /dev/null +++ b/src/pages/docs/platform-hub/templates/parameters.md @@ -0,0 +1,83 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-03-05 +modDate: 2026-03-06 +title: Template parameters +subtitle: A reference for parameters in Platform Hub templates +icon: fa-solid fa-layer-group +navTitle: Parameters +navSection: Templates +description: A reference for parameters in Platform Hub templates +navOrder: 145 +--- + +## Overview + +Parameters make it easy to reuse the same template across projects while tailoring the inputs to each project's needs. Rather than hardcoding values that differ between teams or spaces, you expose them as parameters that each project supplies. + +For process templates, parameters are supplied at the process template usage step level and applied during deployment or runbook runs. For project templates, parameters are set when configuring the project and define the values the template requires, such as accounts, worker pools, and target tags. + +Templates can manage the following as parameters: + +- AWS Account +- Azure Account +- Certificate +- Channels +- Checkbox +- Container Feed +- Dropdown +- Environments +- Generic OIDC Account +- Google Cloud Account +- Multi-line text box +- Sensitive/password box +- Single-line text box +- Target Tags +- Teams +- Tenant Tags +- Username Password Account +- Worker Pool +- Package +- A previous step name + +To create a parameter, navigate to the **Parameters** tab on a template and add a new parameter. + +## Parameter values + +You can set an optional default value for these parameters: + +- Single-line text +- Multi-line text +- Dropdown +- Checkbox +- Sensitive/password box +- AWS Account +- Azure Account +- Generic OIDC Account +- Google Cloud Account +- Username Password Account + +You cannot set a default value for these parameters, they must be set inside a project: + +- Certificate +- Worker Pool +- Package +- A previous step name +- Target Tags +- Teams +- Tenant Tags +- Environments +- Container Feed +- Channels + +## Template-specific behavior + +Some parameter behavior differs between template types. + +:::div{.hint} +**Process templates** support sensitive parameter defaults and account parameter scoping. For more information, see [Process template parameters](/docs/platform-hub/templates/process-templates#parameters). +::: + +:::div{.hint} +**Project templates** do not support parameter scoping or sensitive parameter values in the Alpha release. For more information, see [Project template parameters](/docs/platform-hub/templates/project-templates#parameters). +::: diff --git a/src/pages/docs/platform-hub/templates/process-templates/best-practices.md b/src/pages/docs/platform-hub/templates/process-templates/best-practices.md new file mode 100644 index 0000000000..e68caee6a0 --- /dev/null +++ b/src/pages/docs/platform-hub/templates/process-templates/best-practices.md @@ -0,0 +1,208 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-09-11 +modDate: 2025-09-11 +title: Process Templates best practices +subtitle: Best practices for creating process templates within Platform Hub +icon: fa-solid fa-lock +navTitle: Best Practices +navSection: Process Templates +description: Best practices for creating process templates within Platform Hub +navOrder: 160 +--- + +This document uses **Producer** and **Consumer** frequently. To avoid confusion, use these definitions: + +- **Producer** - the user who creates and manages process templates in Platform Hub. +- **Consumer** - the user who uses the process templates in their deployment or runbook processes. + +## Process templates administration + +### Establish a naming standard + +Use a [ Prefix ] - [ Template Name ] that is easy for everyone to understand the template's purpose. The [ Template Name ] should be succinct and informative. + +The [ Prefix ] should inform everyone where the template should be used. For example: + +- Deploy Process - [ Template Name ] for templates designed for deployments only. +- Runbook - [ Template Name ] for templates designed for runbooks only. +- Deploy and Runbook - [ Template Name ] for templates that can be used in deployments or runbooks. + +:::figure +![A list of process templates with the appropriate prefix and template name](/docs/img/platform-hub/process-templates/process-templates-overview-screen.png) +::: + +### Establish what the major/minor/patch/pre-release means to your company + +Process templates' versioning provides hints: + +- Major (breaking changes) +- Minor (non-breaking changes) +- Patch (bug fixes) +- Pre-Release + +There will be confusion unless you define what a breaking vs. non-breaking change means to you and your company. + +A starting point of a policy can be: + +- **Major** — The change requires the consumer to test it. The template changes how it fundamentally works, and it might delete existing parameters or add new ones. A consumer updating the template requires a PR in their project. +- **Minor** — The change generally doesn’t require the consumer to test it extensively, but it might have added or removed a parameter, which will require a PR by the consumer because it changes the deployment process. +- **Patch** No parameters were added or removed, and testing isn’t required (except by the consumer who reported the bug). The consumer doesn’t require a PR as the deployment process OCL doesn’t change. +- **Pre-Release** - Use for changes that aren’t ready for general use. + +### Leverage branch protection policies on the Platform Hub Git repository + +Template changes should occur in a branch and be reviewed via a PR. To test the changes, use the Pre-Release feature within the versioning functionality. + +## Building Templates + +### Opt for several smaller templates over "all-in-one" templates + +Creating a single process template containing all the steps required to deploy an application can be tempting. In practice, the "all-in-one" template falls apart at scale. + +#### Not all applications use the same components + +Consider this example: + +- Application #1 - Deploys a container to Kubernetes with a SQL Server Backend +- Application #2 - Deploys a container to Kubernetes that monitors a queue + +No matter what, you will create two templates. + +- Option #1 - Create a template for each application combination + - Kubernetes + SQL Server + - Kubernetes + Queue +- Option #2 - Create a template for each component + - Kubernetes + - SQL Server + +With option #2, you’ll have templates that can be mixed and matched with other application types. For example, the SQL Server template can be used for .NET apps running on Azure Web Apps, Linux, or Windows. + +#### Some applications require steps before or after templates + +Consider this deployment process: + +:::figure +![A deployment process using process templates with a step between two templates](/docs/img/platform-hub/process-templates/process-templates-requiring-steps-between-template-steps.png) +::: + +It uses three process templates, but they don’t all run back to back to back. Between the first process template, `Verify Build Artifacts`, and the second process template, `Deploy Databases`, a step to verify the infrastructure runs. Not all applications need that specific step to run between those templates. + +Having multiple process templates allows application teams to insert steps before or after specific actions are performed. + +#### A template for everybody is a template for nobody + +A large all-in-one template requires significant complexity to account for multiple use cases. We’ve seen all-in-one templates follow the same pattern: + +1. The template starts out simple. +2. More use cases are encountered and additional steps are added. Steps solely focused on business logic and creating output variables become the norm. +3. Conditional run conditions for multiple steps become the default. The template becomes very brittle as people need to “hold it just right” for everything to work. +4. Conditional steps start to fail randomly, or steps are skipped randomly because of a configuration change. +5. Consumers are forced to update the templates repeatedly to fix the ever-growing list of bugs. +6. Consumers start asking for the ability to cherry-pick steps when running the template. + +Eventually, the template becomes unusable, and users want a complete rewrite or ask how they can get out of using the templates. + +### Follow the single responsibility principle + +A template should have a single purpose. That doesn’t mean a single step, but a singular purpose that is easy for consumers to understand. Some examples include: + +- Template to create a database on a server +- Template to destroy that database +- Template to verify build artifacts +- Template to deploy and verify an application on a Kubernetes cluster +- Template to deploy a database change + +The template should include all the necessary steps to accomplish that task. Consider a template to deploy a database change. The company policy might be build a delta report and verify it before deploying. But DBAs don’t need to be bothered with every change, so only bother them when specific commands appear. For example, `Drop Database`. To accomplish that, the template would be: + +:::figure +![A process template that deploys databases with all the necessary steps to accomplish the task](/docs/img/platform-hub/process-templates/process-template-to-deploy-databases.png) +::: + +### Parameters + +Parameters should be the only way for information to be sent from consumers' deployment and runbook processes to process templates. + +- Templates should not explicitly rely on output variables from other process templates. Template B shouldn’t have a hard-coded output variable from template A. +- Templates should not hardcode the names of project variables or variable set variables. They must be sent in via parameters. +- Any external references for items outside of Platform Hub - secrets, feeds, worker pools, tags - must be sent in via parameters. + +### Templates must be self-contained + +A template should not expect other templates to be included in the deployment or runbook process. + +- Use parameters for all inputs. +- The consumer, not the producer, should determine the order of the templates in the process. The consumer has context regarding the order of component deployments. +- All steps needed to accomplish the template's task must be included. + +### Keep consumer decision-making to a minimum + +The consumer shouldn’t need to worry about: + +- The number of steps required to accomplish a task +- The steps that can be skipped based on a decision within the template (alerting a DBA if the Drop Database command is found) +- The specific logic of how a task is accomplished. + +A consumer should be able to say: + +> I want to deploy to Kubernetes and verify the deployment using this information: +> +> - The container URL +> - The Git repository of the manifest files +> - The path to manifest files in that repository +> - The target tag of the cluster to deploy to +> - The verification script to run + +It is the producer's job to figure out how to takes those parameters and deploy the container to Kubernetes. + +### Include notes for each step in the process template + +Notes help the consumer understand the intent behind each step. If a deployment fails, it is easier for them to self-service why the failure occurs if they have that context. Sometimes, a step name is all that is required to understand the intent. However, assuming everyone will understand the context based on the name alone is dangerous. It is better to include notes by default. + +:::figure +![Deploy process using process templates that leverage notes](/docs/img/platform-hub/process-templates/deploy-process-using-process-templates-with-notes.png) +::: + +## Producer-managed script steps in templates + +A process template has two options for the `Run a script` step. + +1. Consumer-managed script steps, such as running a verification step after a deployment. The producer will not know the necessary tests to run, so they will ask the consumer to provide the script for the tests. +2. Producer-managed script steps, such as creating a delta report from the provided database package and looking for dangerous commands. The script is created and managed by the producer to accomplish the goal of the template. + +This section refers to the latter, producer-managed script steps. + +### Store the script inline with the template + +Since the template is already in version control, referencing another git repo for the script is redundant. + +If multiple templates need to reference the same script, that indicates they are doing too much. They likely aren’t following the above best practices (single responsibility principle, self-contained, etc.). + +### Output variables intended for business decisions should only be used by the template + +It is common for a script step to make a set of decisions and create an output variable. For example, the first step in this template looks for dangerous commands in the migration scripts and sets an output variable when those commands are found. + +Those kinds of output variables should only be used by the template itself. + +:::figure +![A process template that makes a business decision in the first step and uses output variables in the next two steps](/docs/img/platform-hub/process-templates/process-template-to-deploy-databases.png) +::: + +### Output variables must be surfaced via logs when intended for outside steps to use + +When a template explicitly creates output variables to be used by other steps they must be logged for the consumer to know. For example, a template that retrieves values from a key vault and sets them as output variables. + +- When possible, allow the consumer to provide a list of output variables - for example, telling the key vault which secrets to retrieve. +- When that is not possible, log all the output variables created. +- If another process template will use those output variables, they should be sent in as parameters. There should never be a hard link between templates. + +### Log everything + +Octopus supports different levels of logs: + +- Write-Verbose - writes a verbose log (hidden by default) +- Write-Info - writes an info log (visible on task log screen by default) +- Write-Highlight - writes the information to the task summary screen +- Write-Error - writes an error message + +Use those log levels and write messages frequently. This aids in debugging when a deployment or runbook run fails. Logs are like an umbrella - better to have it and not need it than need it and not have it. diff --git a/src/pages/docs/platform-hub/templates/process-templates/index.md b/src/pages/docs/platform-hub/templates/process-templates/index.md new file mode 100644 index 0000000000..08d7d1dd2c --- /dev/null +++ b/src/pages/docs/platform-hub/templates/process-templates/index.md @@ -0,0 +1,132 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-09-23 +modDate: 2026-03-05 +title: Process Templates +subtitle: An overview of Process Templates +icon: fa-solid fa-layer-group +navTitle: Overview +navSection: Process Templates +description: An overview of Process Templates +navOrder: 150 +--- +## Overview + +Process templates are reusable sets of deployment steps that can be shared across multiple spaces in Octopus Deploy. Instead of copying and pasting deployment processes across teams and applications, which often leads to configuration drift, unnecessary duplication, and operational debt, you create a single source of truth that any project can consume. By abstracting your best practices for deployments into Process Templates, you make it easy for teams to follow standards and accelerate delivery. + +To create or manage your process templates, navigate to Platform Hub. If you haven't set up your Git repository, you must do so first before creating a process template. Similarly, if you've already created templates or are joining an existing team, you'll see the existing templates on the template overview. + +:::figure +![The Process Templates Overview page where users create process templates](/docs/img/platform-hub/process-template-overview.png) +::: + +Before you can define the deployment process for your template, you must create the template first. + +1. Navigate to Process Templates in Platform Hub. +2. Give the process template a **Name** and an optional **Description**. +3. Create your process template. + +:::figure +![The experience after creating the template with a name and description](/docs/img/platform-hub/process-template-first-creation.png) +::: + +You've created your process template; now, define its deployment process. + +A deployment process is a set of steps the Octopus Server orchestrates to deploy your software. Each process template has a single deployment process. You can use Octopus's built-in steps to define this process for your process template. + +:::figure +![The add step experience for a process template](/docs/img/platform-hub/process-template-add-step.png) +::: + +Some steps look different inside a process template. They ask for a parameter rather than allowing you to define a value. These steps ask for a resource that Platform Hub cannot define, such as Worker Pools, and you must define them inside a project. These fields accept parameters so you can define the values the process template needs inside a project. + +:::figure +![The run a script step asks for a worker pool parameter instead of a worker pool](/docs/img/platform-hub/process-template-step-example.png) +::: + +:::div{.warning} +Our initial release of Process Templates does not include support for a few built-in steps. +::: + +Once you have set up a deployment process, you can use it in any space for a deployment or runbook. + +## Parameters + +Parameters help you easily manage and apply the correct values during a deployment or runbook run that uses a process template. Using parameters, you can use the same process template across your projects and tailor the inputs based on the project's needs. + +For a full reference of supported parameter types and default values, see [Template parameters](/docs/platform-hub/templates/parameters). + +To create a parameter, navigate to the **Parameters** tab on a process template and add a new parameter. + +:::figure +![The parameters section in a process template](/docs/img/platform-hub/process-template-parameters.png) +::: + +### Sensitive parameter defaults + +:::div{.hint} +The ability to add default values for Sensitive/password box parameters is available from **Octopus 2026.1**. +::: + +Unlike the other parameters, sensitive default values are stored securely in the database with a unique GUID identifier. This identifier is used in the process template to reference the default sensitive value in the database. Because of this approach, sensitive default values are supported in CaC workflows. Scoping for Sensitive/password box parameters is not currently supported. + +You can set a default value for a sensitive parameter by navigating to the parameters tab of your process template and committing your changes. When the template is saved, sensitive default values are stored encrypted in the database with a unique identifier. In the OCL, the parameter block will look something like this: + +```hcl +parameter "Example Sensitive Parameter" { + display_settings = { + Octopus.ControlType = "Sensitive" + } + help_text = "An Example Sensitive Parameter" + label = "An Example Sensitive Parameter" + + value "10d00c16-c905-43fa-90cd-088e22b31751" {} +} +``` + +The GUID value in the OCL is a reference to the database-stored sensitive value. When the process template is used in a project or runbook, it will retrieve the sensitive value from the database. + +### Parameter scoping + +Only Account parameters will allow you to scope them by environments. You can choose to scope them by any environment across your Octopus instance. + +:::div{.hint} +When a process template is used inside a project, the project supplied values will take precedence over the process template provided ones for overlapping scopes. This includes unscoped project supplied values. For more information on how the precedence works, please visit the [troubleshooting page](/docs/platform-hub/templates/process-templates/troubleshooting). +::: + +:::figure +![The account parameter allowing scoping to environments present across Octopus instance](/docs/img/platform-hub/process-templates-account-scoping.png) +::: + +## Saving, publishing, and sharing + +Once you've configured your process template, see [Publishing and sharing templates](/docs/platform-hub/templates/publishing-and-sharing) for how to commit, publish, and share it. + +## A Hello world deployment process in a process template + +To define a simple deployment process in Octopus that executes a hello world script on the Octopus Server, complete the following steps: + +1. Navigate to **Platform Hub** +2. Add a process template +3. Name the template, for instance, "Hello World", and add an optional description. +4. Add a deployment step. +5. Choose the type of step you'd like to add to filter the available steps. +6. Find the **Run a Script** step and add it to your deployment process. +7. In the Process Editor, give the step a name, for instance "Run a Hello World script". +8. In the Execution Location section use the **Run on the worker pool parameter** option. +9. Create a Worker Pool parameter. +10. Add the Worker Pool parameter to the **Worker Pool** field. +11. Paste the following PowerShell script into the **Inline Source Code** editor: + + ```powershell + Write-Host "Hello, World!" + ``` + +12. Commit your template. +13. Publish and Share your template. +14. Visit a project, and its deployment process +15. Choose the process template you just published +16. Choose the Worker Pool in the parameters tab +17. Add any steps before or after the process template + +You can now deploy this process to say "Hello, World!". diff --git a/src/pages/docs/platform-hub/templates/process-templates/troubleshooting.md b/src/pages/docs/platform-hub/templates/process-templates/troubleshooting.md new file mode 100644 index 0000000000..824a165676 --- /dev/null +++ b/src/pages/docs/platform-hub/templates/process-templates/troubleshooting.md @@ -0,0 +1,246 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2025-09-23 +modDate: 2025-11-20 +title: Troubleshooting +subtitle: Known issues that you may run into +icon: fa-solid fa-layer-group +navTitle: Troubleshooting +navSection: Process Templates +description: Known issues and limitations for process templates +navOrder: 151 +--- + +## Troubleshooting common issues + +You may run into a few issues when setting up your process templates. We've put together this page to help you diagnose and fix common issues. + +### Step support + +Process templates currently supports most Octopus steps. It currently doesn't support the following: + +1. Deploy a Bicep Template +2. AWS S3 Create Bucket +3. AWS ECS + +This document will be updated as additional step support is added. + +### Parameters and Variables + +If you are migrating an existing process to be used as a process template, you may run into a few issues when using parameters and variables in scripts. When copying a script from a step in a project into a process template step, you must convert project variables to use process template parameters. System variables will still work as normal. + +For example, consider this script that directly references project and system variables via `OctopusParameters`. + +```powershell +$packagePath = $OctopusParameters["Octopus.Action.Package[Trident.Database].ExtractedPath"] +$connectionString = $OctopusParameters["Project.Connection.String"] +$environmentName = $OctopusParameters["Octopus.Environment.Name"] +$reportPath = $OctopusParameters["Project.Database.Report.Path"] + +cd $packagePath +$appToRun = ".\Octopus.Trident.Database.DbUp" +$generatedReport = "$reportPath\UpgradeReport.html" + +& $appToRun --ConnectionString="$connectionString" --PreviewReportPath="$reportPath" + +New-OctopusArtifact -Path "$generatedReport" -Name "$environmentName.UpgradeReport.html" +``` + +The following variables should be updated to reference process templates parameters instead of project variables: + +1. `$packagePath` +2. `$connectionString` +3. `$reportPath` + +The `$environmentName` variable is fine, as system variables will continue to work as normal. The updated script will be: + +```powershell +$packagePath = $OctopusParameters["Octopus.Action.Package[Template.Database.Package].ExtractedPath"] +$connectionString = $OctopusParameters["Template.Database.ConnectionString"] +$environmentName = $OctopusParameters["Octopus.Environment.Name"] +$reportPath = $OctopusParameters["Template.Database.ChangeReportDirectory"] + +cd $packagePath +$appToRun = ".\Octopus.Trident.Database.DbUp" +$generatedReport = "$reportPath\UpgradeReport.html" + +& $appToRun --ConnectionString="$connectionString" --PreviewReportPath="$reportPath" + +New-OctopusArtifact -Path "$generatedReport" -Name "$environmentName.UpgradeReport.html" +``` + +### Parameter scoping + +Project supplied values for parameters will always take precedence over process template supplied ones. + +A couple scenarios that demonstrate the scoping precedence: + +
+ +**1. Scoped value provided by the project and the process template.** + +| Origin | Name | Value | Scope | +|------------------|--------------|------------------|-------------| +| Process Template | AzureAccount | Account-123 | Development | +| Project | AzureAccount | Account-124 | Development | + +When deploying to the **Development** environment, **Account-124** would be used. + +
+ +**2. Scoped value provided by the process template and an unscoped value provided by the project.** + +| Origin | Name | Value | Scope | +|------------------|--------------|------------------|-------------| +| Process Template | AzureAccount | Account-123 | Development | +| Project | AzureAccount | Account-124 | | + +When deploying to the **Development** environment, **Account-124** would be used. + +
+ +**3. Scoped process template value and scoped project value for different environments.** + +| Origin | Name | Value | Scope | +|------------------|--------------|------------------|-------------| +| Process Template | AzureAccount | Account-123 | Development | +| Project | AzureAccount | Account-124 | Staging | + +- When deploying to the **Development** environment, **Account-123** would be used. +- When deploying to the **Staging** environment, **Account-124** would be used. + +
+ +### Step specific issues + +- You cannot configure **Edit YAML** on the **Configure and apply Kubernetes resource** step. +- You cannot configure cloud target discovery on steps. You must use project variables when consuming a process template in a project instead. +- When referencing a file from a Git repo, for example, script, manifest, Kustomize, etc., you cannot pick the project Git repository as the source. You must supply the Git repository URL. The URL can be passed in via a parameter or hardcoded in the template itself. Hardcoding is not recommended. + +### Cloning process templates + +You cannot clone a process template in Platform Hub through the Octopus UI. The process for cloning a process template is: + +1. Clone the process template OCL file in the Platform Hub Git repository. +2. Change the name of the cloned OCL file to the desired name. +3. Change the name of the process template in the OCL file. +4. Commit and push the changes. +5. Refresh the process template list in the Octopus Deploy UI and find the newly created template. +6. Publish the template and configure the Spaces that have access to it. + +### Platform Hub account limitations + +The following account types are not supported: + +1. Token +2. SSH + +Platform Hub accounts cannot be used in the following situations: + +- Cannot be used by targets. +- Cannot be used in Cloud Target Discovery. + +### Public API + +Process templates can be created and managed through our [public API](/docs/octopus-rest-api). + +- Process templates are stored as code in the configured Git repository. The OCL files store all relevant information about the template - including the parameters, the steps, name, description and other settings. +- The published versions and Spaces configured are stored and managed via the database. + +:::div{.warning} +We do not currently support creating or managing process templates through the CLI or the Terraform provider. +::: + +See [CreateProcessTemplateUsageStep](https://github.com/OctopusDeploy/OctopusDeploy-Api/blob/master/Octopus.Client/Csharp/DeploymentProcesses/CreateProcessTemplateUsageStep.cs) for an example of how to configure a process template on a deployment process using [Octopus.Client](/docs/octopus-rest-api/octopus.client). + +### GitHub Connections + +The GitHub Connection is not supported in Platform Hub. Only usernames and PATs. + +### Losing access to an Octopus Enterprise license + +Process templates and all Platform Hub features are restricted to customers who have an Enterprise Tier license. When you no longer have an Enterprise license, process templates will work differently. + +#### What will continue to work + +- Existing deployments and runbook runs can be redeployed or rerun. +- New releases that have a process containing process templates can be created. +- New runbook runs that have a process containing process templates can be created. +- Auto-scheduled deployments or runbook runs will continue to work. + +#### What will not work anymore + +- Users will lose access to Platform Hub, including the ability to create and manage all Platform Hub features. +- Process templates cannot be modified inside a project. +- Process templates will no longer receive updates and automatically roll forward to a later version. +- Projects that contain process templates cannot be cloned until the process template is removed. + +### Output Variables + +To reference output variables from process template steps, add `.ProcessTemplate` to the standard output variable syntax. + +When referencing an output variable in a step **inside a process template**, use the format: + +```text +Octopus.ProcessTemplate.Action[StepName].Output.PropertyName +``` + +
+ +When referencing an output variable in a step **outside a process template**, include the name of the process template usage step as it appears in the project. + +```text +Octopus.ProcessTemplate[ProcessTemplateUsageStepName].Action[StepName].Output.PropertyName +``` + +#### Example + +Consider a process template named **Build and Create Web App** containing a step that runs a script and publishes an output variable `FilePath`: + +```hcl +name = "Build and Create Web App" +description = "" + +step "run-a-script" { + name = "Collect Details" + + action { + action_type = "Octopus.Script" + ... + } + ... +} +``` + +Reference the variable from another step **inside** the process template using: + +```text +Octopus.ProcessTemplate.Action[Collect Details].Output.FilePath +``` + +
+ +When this process template is used in a project with a process template usage step named **Create Web App**: + +```hcl +process_template "run-a-process-template" { + name = "Create Web App" + process_template_slug = "build-and-create-web-app" + version_mask = "1.X" + + parameter "linux worker" { + value = "WorkerPools-1" + } + ... +} +``` + +Reference the variable from any other step in the process, which is **outside** the process template, using: + +```text +Octopus.ProcessTemplate[Create Web App].Action[Collect Details].Output.FilePath +``` + +:::div{.hint} +Use the name of the process template usage step from the project, not the name of the process template itself, when referencing output variables outside a process template. +::: diff --git a/src/pages/docs/platform-hub/templates/project-templates/best-practices.md b/src/pages/docs/platform-hub/templates/project-templates/best-practices.md new file mode 100644 index 0000000000..4be2a8a0ac --- /dev/null +++ b/src/pages/docs/platform-hub/templates/project-templates/best-practices.md @@ -0,0 +1,103 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-03-05 +modDate: 2026-03-06 +title: Project template best practices +subtitle: Best practices for creating project templates in Platform Hub +icon: fa-solid fa-lock +navTitle: Best Practices +navSection: Project Templates +description: Best practices for creating project templates in Platform Hub +navOrder: 180 +--- + +This document uses **Producer** and **Consumer** frequently. To avoid confusion, use these definitions: + +- **Producer**: the user who creates and manages project templates in Platform Hub. +- **Consumer**: the user who creates projects from those templates. + +## Project template administration + +### Establish a naming standard + +Use a **[ Prefix ] - [ Template Name ]** convention that's easy for everyone to understand at a glance. The template name should be succinct and informative. + +The prefix should convey the intended use. For example: + +- **Project - [ Template Name ]** for general deployment project templates +- **Service - [ Template Name ]** for templates designed for specific service types (APIs, background workers, etc.) + +### Define what major, minor, patch, and pre-release mean for your organization + +Project template versioning provides hints: + +- **Major** (breaking changes) +- **Minor** (non-breaking changes) +- **Patch** (bug fixes) +- **Pre-release** + +Without a shared definition of breaking vs. non-breaking, teams will interpret these differently. A starting point for a policy: + +- **Major**: The change fundamentally alters how the template works. Parameters have been added or removed. Consumers need to review and test the update before accepting it. +- **Minor**: Parameters may have been added or adjusted, which could require a change in the consuming project, but the core behavior is preserved. +- **Patch**: No parameters were added or removed. Bug fixes only. Consuming projects can accept the update without a deployment process change. +- **Pre-release**: Use for changes that aren't ready for general use. Share with a specific space to test before promoting. + +### Use branch protection on the Platform Hub Git repository + +Template changes should happen in a branch and be reviewed via a pull request. Use the pre-release feature to test changes before promoting them to a stable version. + +## Building templates + +### Keep templates focused + +A project template should represent one clear type of project, not accommodate every variation your organization uses. If you find yourself adding conditional logic to handle different use cases, that's a sign you need more than one template. + +For example, a template for a Kubernetes microservice hosting an application and one that hosts a message queue may share similar infrastructure but have meaningfully different deployment processes. Separate templates are clearer for consumers and easier to maintain. + +### Use parameters for everything consumer-specific + +Parameters are the only way information should flow from a project into the template. This means: + +- Don't hardcode space-specific values, account names, or resource identifiers in the template +- Don't expect consumers to know internal variable names. Expose them as parameters +- Any external reference such as secrets, feeds, Worker Pools, and target tags must come in via a parameter +- Only expose parameters the consumer genuinely needs to provide. If the producer should control a value, use a variable instead + +### Keep consumer decision-making to a minimum + +A consumer should be able to create a project from the template by supplying a small set of well-defined inputs. They shouldn't need to understand the internal mechanics of how the deployment works. + +A consumer should be able to say: + +> I want to deploy this service using these values: +> +> - The container image +> - The target tag of the cluster to deploy to + - The connection string for the database + +It's the producer's job to figure out how to take those inputs and run a reliable deployment. + +### Lock values that must be consistent across projects + +Template variables are fixed. Consumers can't override them. Use this for values that must be the same across every project created from the template, such as accounts, credentials, or environment-specific configuration the producer controls. If you want projects to supply their own value for something, expose it as a parameter instead. + +Variable values can reference parameters, letting you combine fixed template-level values with project-supplied inputs where needed. + +### Include notes for each step in the deployment process + +Step notes help consumers understand what each step does and why. If a deployment fails, clear notes make it much easier for them to self-diagnose. Don't assume that a step name alone provides enough context. + +## Publishing and versioning + +### Test your template before publishing + +Before publishing a version, create a test project using the template in a development or sandbox space. Verify the deployment runs end-to-end with realistic parameter values. This is especially important for major versions, where consumers can't create new releases until they've applied the update. + +If you're testing a breaking change, use the pre-release feature so the new version is only visible to a specific space before you promote it. + +### Write release notes when publishing a new version + +Each published version can include release notes. Describe what changed, whether any parameters were added or removed, and what consumers need to do when updating. This information surfaces directly in the UI when consumers are deciding whether to apply the update. + +A concise, clear release note — *Added a required parameter for the image pull secret. Update your project before creating a new release.* — saves consumers time and reduces support requests. diff --git a/src/pages/docs/platform-hub/templates/project-templates/index.md b/src/pages/docs/platform-hub/templates/project-templates/index.md new file mode 100644 index 0000000000..7b039642b5 --- /dev/null +++ b/src/pages/docs/platform-hub/templates/project-templates/index.md @@ -0,0 +1,121 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-03-05 +modDate: 2026-03-06 +title: Project Templates +subtitle: An overview of Project Templates +icon: fa-solid fa-layer-group +navTitle: Overview +navSection: Project Templates +description: An overview of Project Templates +navOrder: 170 +--- + +:::div{.warning} +Project templates are in Alpha. The feature is incomplete and standard SLAs do not apply. Don't use it for production workloads. It is available to Enterprise customers on Cloud. Self-hosted customers can access it as an early preview via Octopus 2026.2. We're actively developing this feature and would love your feedback. +::: + +## Overview + +Project templates are reusable project blueprints that can be shared across multiple spaces in Octopus Deploy. Instead of manually configuring each new project from scratch, defining deployment steps and variables every time, you create a single template that any space can use as a starting point. This ensures teams follow the same standards and removes the risk of configuration drift. + +To create or manage your project templates, navigate to the Platform Hub. If you haven't set up your Git repository, you must do so before creating a project template. + +Before you can configure your template, you must create it. + +1. Navigate to **Project Templates** in Platform Hub. +2. Give the project template a **Name** and an optional **Description**. +3. Create your project template. + +:::figure +![Creating a project template with a name and description](/docs/img/platform-hub/project-templates/project-templates-onboarding.png) +::: + +After creating your template, Octopus adds the template's [folder and OCL files](#git-repository-structure) to your Git repository. If you've already created templates or are joining an existing team, you'll see the existing templates on the overview page. + +:::figure +![The Project Templates overview page](/docs/img/platform-hub/project-templates/project-templates-list.png) +::: + +You can now define the deployment process, parameters, and variables for the template. + +## Deployment process + +The deployment process defines the steps Octopus orchestrates when deploying a project created from this template. Each project template has a single deployment process, and you can use Octopus's built-in steps, Step Templates, Community Step Templates, and Process Templates to define it. + +Projects created from the template can't modify the deployment process. They can't add, remove, reorder, or disable steps. The only thing a project can configure is the parameter values the platform engineer has explicitly exposed, ensuring every project based on the template follows the same deployment process. + +Some steps behave differently inside the project template editor. Instead of letting you set a value directly, they ask for parameters or variables. Parameters are required when a step requires a resource that Platform Hub can't define, such as a Worker Pool, and that resource must be supplied by the project. These fields accept parameters so projects can provide the right values for their context. + +:::figure +![A step in a project template asking for a Worker Pool parameter](/docs/img/platform-hub/project-templates/project-templates-process-editor.png) +::: + +:::div{.hint} +Unlike standard projects, project templates validates the deployment process when you publish, not when you commit. You can save an incomplete process and continue configuring parameters and variables before publishing. This makes it easier to build your template incrementally — define the process first, then wire up parameters and variables as you go. +::: + +## Parameters + +Parameters let you define the inputs a project must supply when it's created from the template. They're the mechanism for making a template flexible. Rather than hardcoding values that differ between teams or spaces, you expose them as parameters. + +:::div{.warning} +In the Alpha release, project templates don't support parameter scoping or sensitive parameter values. We're still working out how parameters, variables, and scoping should work in project templates and expect this to evolve throughout Alpha. We'd love your [feedback](#feedback). +::: + +For a full reference of supported parameter types and default values, see [Template parameters](/docs/platform-hub/templates/parameters). + +To create a parameter, navigate to the **Parameters** tab on your project template and add a new parameter. + +:::figure +![The Parameters tab in a project template](/docs/img/platform-hub/project-templates/project-templates-parameters.png) +::: + +## Variables + +Variables in a project template work the same way as project variables in a standard Octopus project. Any variable you define is available to the deployment and can be selected in steps. + +Unlike parameters, projects can't override the variables set in a template. Use this for values that must be the same across every project, like accounts or credentials. If you want projects to supply their own value for something, expose it as a parameter instead. + +Variable values can reference parameters, letting you combine fixed template-level values with project-supplied inputs where needed. + +:::div{.warning} +In the Alpha release, the variable types you can use are limited to resources currently available in Platform Hub, such as Accounts and Git Credentials. Variable scoping is also not supported. We're adding support for additional resource types throughout Alpha. We'd love your [feedback](#feedback) on what you need. +::: + +:::figure +![The Variables tab in a project template](/docs/img/platform-hub/project-templates/project-templates-variables.png) +::: + +## Git repository structure + +Octopus stores each project template as a folder in the Platform Hub Git repository. The folder name is a slug derived from the template name. Each folder contains four OCL files: + +```text +project-templates// + deployment_process.ocl + parameters.ocl + template.ocl + variables.ocl +``` + +- **`template.ocl`** contains the template name and description. +- **`deployment_process.ocl`** contains the deployment process steps. +- **`parameters.ocl`** contains the parameters defined for the template. +- **`variables.ocl`** contains the variables defined for the template. + +Octopus stores published versions, sensitive variables, and space sharing configurations in the database, not in the Git repository. + +## Saving, publishing, and sharing + +After you've configured your project template, see [Publishing and sharing templates](/docs/platform-hub/templates/publishing-and-sharing) for how to commit, publish, and share it. + +## Using a project template + +After you publish and share a template, users in a space can create a new project from it. When creating the project, they supply values for the parameters you've defined. Octopus calls these **Template values** in the UI. After setting their parameter values, they can create a release and deploy it. They can't modify the deployment process. + +When you publish a new version of the template, projects receive and can accept the update in the same way as process templates. + +## Feedback + +Project templates are in Alpha and we're actively shaping how the feature works. If you run into something unexpected or have thoughts on how parameters, variables, scoping, or anything else should work, we'd love to hear from you. [Share your feedback](https://roadmap.octopus.com/submit-idea) to help us build this the right way. diff --git a/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md b/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md new file mode 100644 index 0000000000..61fd093ed2 --- /dev/null +++ b/src/pages/docs/platform-hub/templates/project-templates/troubleshooting.md @@ -0,0 +1,77 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-03-05 +modDate: 2026-03-05 +title: Troubleshooting +subtitle: Known issues and limitations for project templates +icon: fa-solid fa-layer-group +navTitle: Troubleshooting +navSection: Project Templates +description: Known issues and limitations for project templates +navOrder: 171 +--- + +## Alpha limitations + +Project templates are in Alpha. The following features are not yet supported and are planned for future releases: + +- Channels +- Lifecycles +- Environment templates +- Ephemeral environments +- Cloud target discovery on steps. Use project variables in the project instead +- Cloning a project template through the Octopus UI +- Creating and managing project templates through the REST API, CLI, or Terraform provider +- Feeds +- Project settings +- Runbooks +- Triggers +- Import and export of templated projects +- Inline variable and parameter configuration within the deployment process editor + +We'll update this page as the feature evolves. + +## Step support + +Project templates support most Octopus steps. The following step package framework steps are not supported: + +1. Deploy a Bicep Template +2. AWS S3 Create Bucket +3. AWS ECS + +These steps are being migrated away from the step package framework and will be supported in the future. + +## Cloning project templates + +You can't clone a project template through the Octopus UI. To clone a template: + +1. Copy the template's folder in the Platform Hub Git repository. +2. Rename the folder to the desired slug. +3. Update the template name inside `template.ocl`. +4. Commit and push the changes. +5. Refresh the project template list in the Octopus UI to find the newly created template. +6. Publish the template and configure the spaces that have access to it. + +## Public API + +The Alpha release doesn't support creating and managing project templates through the REST API. We're planning REST API support for a future release. + +- Octopus stores each project template as a folder in the configured Git repository, containing four OCL files: `template.ocl`, `deployment_process.ocl`, `parameters.ocl`, and `variables.ocl`. +- Published versions and space sharing configurations are stored in the database. + +## Losing access to an Octopus Enterprise license + +Project templates and all Platform Hub features require an Enterprise license. When you no longer have an Enterprise license, project templates behave differently. + +### What will continue to work + +- Existing deployments can be redeployed. +- New releases for projects created from a project template can still be created. +- Auto-scheduled deployments will continue to run. + +### What will no longer work + +- Users will lose access to Platform Hub, including the ability to create and manage project templates. +- You can no longer modify project templates in a project. +- Projects created from a template will no longer receive automatic updates when you publish a new template version. +- You can't clone projects created from a template until you remove the template reference. diff --git a/src/pages/docs/platform-hub/templates/publishing-and-sharing.md b/src/pages/docs/platform-hub/templates/publishing-and-sharing.md new file mode 100644 index 0000000000..50bc3632f9 --- /dev/null +++ b/src/pages/docs/platform-hub/templates/publishing-and-sharing.md @@ -0,0 +1,60 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-03-06 +modDate: 2026-03-06 +title: Publishing and sharing templates +subtitle: How to save, publish, and share templates in Platform Hub +icon: fa-solid fa-layer-group +navTitle: Publishing and sharing +navSection: Templates +description: How to save, publish, and share templates in Platform Hub +navOrder: 147 +--- + +## Saving a template + +Once you've finished making changes, commit them to save to your Git repository. You can either **Commit** with a description or quick commit without one. + +:::figure +![The commit experience for a template](/docs/img/platform-hub/process-templates-commit-experience.png) +::: + +## Publishing a template + +After committing your changes, publish the template to make them available. You have three options when publishing: + +- **Major** changes (breaking) +- **Minor** changes (non-breaking) +- **Patch** (bug fixes) + +You can also publish a pre-release version to test the template before promoting it. + +:::div{.hint} +The first time you publish a template, you can only publish a major or pre-release version. +::: + +Selecting any option increments the version number following Semantic Versioning. For minor or patch updates, projects that accept these changes will automatically upgrade to the newly published version. + +:::figure +![The publish experience for a template](/docs/img/platform-hub/process-templates-publishing.png) +::: + +### Pre-releases + +If you want to test your changes before publishing a major, minor, or patch version, you can mark a template as a pre-release version. + +:::figure +![Marking a template as pre-release](/docs/img/platform-hub/process-template-prerelease.png) +::: + +## Sharing a template + +You must share a template before any space can use it. Templates can be shared with all current and future spaces, or with a select few. + +:::div{.hint} +Sharing settings can be updated at any time. +::: + +:::figure +![The sharing experience for a template](/docs/img/platform-hub/process-template-sharing.png) +:::