Custom step templates stored in Git

Since Octopus 2023.4, it is now possible to create custom step templates with scripts sourced directly from Git.

To start, use the same steps you would normally take to create a custom step template. Just be sure to select a compatible step as some steps aren’t suitable for being sourced from Git.

Git compatible base steps

The built-in steps listed below are compatible with being sourced from Git and can be used for custom step templates:

Note: This is not a complete list as it is anticipated that additional steps will be added

You may use the filter at the top to help find a step to base your custom step template on: Base Step Filter

Source

Git compatible base steps for custom step templates will provide an option to select a source. The name of this option can differ depending on the step, including:

Script Source
Template Source
Chart Source

To use Git as the applicable source, simply select the Git repository option in the Step tab.

Script Source

Once Git repository is selected, additional options will appear below in the Step tab. Below are common examples while certain base steps may differ.

Repository URL

In this section, you will specify the full URL to the root of your target repository.

Repository URL

Authentication

Unlike database sourced custom step templates, authentication is typically required to access the repository holding the script.

Git credentials can be added to a Space by navigating to Deploy ➜ Git Credentials or via the + button in the Authentication section of the Step tab. Use the drop-down arrow to select the appropriate Git credentials once they have been added.

If newly added Git credentials aren’t showing up, click on the circular refresh button next to the drop-down arrow.

Authentication

Branch Settings

In this section, you will specify the default branch name.

Branch Settings

Path

Similar to Source, the Path section will be titled differently depending on the base step type. Examples include:

Script File Path
Template Path
Chart Directory

Any of the above allows you to specify a relative path from the root of the Git repository to the targeted item. Using the example repository of https://Github.com/OctopusSamples/OctoPetShop.Git and a target file residing at Scripts/MyScript.sh within the repository, simply use Scripts/MyScript.sh here as shown below:

Path

Parameters and other options

Different base steps used for custom step templates sourced from Git may have additional options such as Script Parameters and other options specific to that type of step. You may refer to the instructions found in the UI for these options or relevant step pages in our documentation for more information.

Version management

For custom step templates sourced from Git, aside from the specified target item, only some of the information relating to the step template is stored in Git. Everything in the Step, Parameter, and Settings tab is stored in the Octopus database.

Once a step template is added to a project, an entry is added to the Usage section (located just under the title of the step template). Within Usage, there are two tabs:

Version-Controlled Projects
Database-Backed Projects

Git sourced custom step templates work just like standard step templates in that they are compatible with both types of projects. However, the version displayed on the usage page is only incremented by database changes to a given custom step template.

Git commits that change or update the item sourced from Git are not reflected in the version numbers shown on the usage page for Git sourced custom step templates. This is handled separately when:

creating a release
creating runbook snapshot (database sourced)
running a Git sourced runbook

Selecting Git sourced custom step templates versions

Octopus offers three ways to select a Git sourced custom step template version, including:

Branches
Tags
Commits

All three options correspond to the listed repository.

When creating a new release, you can see the selection that was made for the previous release. You will notice an icon corresponding to the adjacent branch name, tag, or commit hash.

Select By Branch Tag Or Commit