1. Resources
  2. /
  3. Plugins
  4. /
  5. create-release-buildkite-plugin

Create Release Buildkite Plugin

image

This is a Buildkite plugin to create a release in Octopus Deploy.

This plugin requires Octopus CLI to be installed on the Buildkite agent.

Releases in Octopus Deploy

A release is a snapshot of the deployment process and the associated assets (packages, scripts, variables) as they existed when the release was created. The release is given a version number, and you can deploy that release as many times as you need to, even if parts of the deployment process have changed since the release was created (those changes will be included in future releases but not in this version).

When you deploy the release, you are executing the deployment process with all the associated details, as they existed when the release was created.

More information about releases in Octopus Deploy:

Examples

Incorporate the following step in your pipeline.yml to create a release in Octopus Deploy:

Basic examples

Using version template configured on the project

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          project: "HelloWorld"
          server: "${MY_OCTOPUS_SERVER}"

Specifying the release version to use

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          project: "HelloWorld"
          release_number: "1.0.3"
          server: "${MY_OCTOPUS_SERVER}"

Version controlled projects

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          git_ref: "main"
          project: "HelloWorld"
          release_number: "1.0.3"
          server: "${MY_OCTOPUS_SERVER}"

Specifying Package Version

Package version to use for all packages

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          default_package_version: "1.0.1"
          project: "HelloWorld"
          release_number: "1.0.3"
          server: "${MY_OCTOPUS_SERVER}"

Multiple steps with a single package

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          packages:
            - "StepA:1.0.1"
            - "StepB:1.0.2"
          project: "HelloWorld"
          release_number: "1.0.3"
          server: "${MY_OCTOPUS_SERVER}"

Step with multiple packages

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          packages:
            - "StepA:Acme.Web:1.0.0"
            - "StepA:Acme.Data:2.0.0"
          project: "HelloWorld"
          release_number: "1.0.3"
          server: "${MY_OCTOPUS_SERVER}"

Source package version from a folder containing the packages used in a project

steps:
  - label: ":octopus-deploy: Create a release in Octopus Deploy"
  - plugins:
      - OctopusDeploy/create-release#v0.1.1:
          api_key: "${MY_OCTOPUS_API_KEY}"
          packages_folder: "packages"
          project: "HelloWorld"
          release_number: "1.0.3"
          server: "${MY_OCTOPUS_SERVER}"

Configuring

OCTOPUS_CLI_SERVER

Your Octopus Server URL should be set to this environment variable, or you can use server in the steps of your pipeline instead.

OCTOPUS_CLI_API_KEY

Your Octopus Server API key should be set to this environment variable, either in your pipeline’s environment variable settings or exposed in an environment hook. If you need different keys for different steps in your pipeline use api_key instead.

📥 Inputs

The following inputs are required:

NameDescription
projectThe name or ID of the project associated with this release.

The following inputs are optional:

NameDescriptionDefault
api_keyThe environment variable that is configured with your Octopus Server API key used to access Octopus Deploy. Use this if you need to specify different keys for different steps in your pipeline.
channelThe name or ID of the channel to use for the new release. If omitted, the best channel will be selected.
config_fileThe path to a configuration file of default values with one key=value per line.
debugEnable debug logging.false
default_package_versionUse the default version number of all packages for this release.false
git_commitGit commit to use when creating the release. Use in conjunction with the gitRef parameter to select any previous commit.
git_refGit reference to use when creating the release.
ignore_channel_rulesCreate the release ignoring any version rules specified by the channel.false
ignore_existingIgnore existing releases if present in Octopus Deploy with the matching version number.false
ignore_ssl_errorsIgnore certificate errors when communicating with Octopus Deploy. Warning: enabling this option creates a security vulnerability.false
log_levelThe log level; valid options are verbose, debug, information, warning, error, and fatal.debug
packagesA single version number or multi-line list of version numbers to use for a package in the release (format: StepName:Version, PackageID:Version, or StepName:PackageName:Version).
package_prereleasePre-release for latest version of all packages to use for this release.
package_versionThe version number of all packages to use for this release.
packages_folderThe folder designated for containing packages.
proxyThe URL of a proxy to use (i.e. https://proxy.example.com).
proxy_passwordThe password used to connect to a proxy. It is strongly recommended following the guidelines in the Buildkite Managing Pipeline Secrets docs. If proxy_username and proxy_password are omitted and proxy is specified, the default credentials are used.
proxy_usernameThe username used to connect to a proxy. It is strongly recommended following the guidelines in the Buildkite Managing Pipeline Secrets docs.
release_notesThe release notes associated with the new release (Markdown is supported).
release_notes_filePath to a file that contains release notes for the new release. Supports Markdown files.
release_numberThe number for the new release.
serverThe base URL hosting Octopus Deploy (i.e. “https://octopus.example.com/”). It is recommended to retrieve this value from the OCTOPUS_CLI_SERVER environment variable.
spaceThe name or ID of a space within which this command will be executed. If omitted, the default space will be used.
timeoutA timeout value for network operations (in seconds).600
what_ifPerform a dry run; do not create or deploy a release.false

Developing

To run the tests:

docker-compose run --rm tests

To lint the plugin:

docker-compose run --rm lint

🤝 Contributions

Contributions are welcome! :heart: Please read our Contributing Guide for information about how to get involved in this project.

The plugins listed on this webpage are provided for informational purposes only. They have not undergone any formal security review or assessment. While we strive to provide useful resources, we cannot guarantee the safety, reliability, or integrity of these plugins. Users are strongly advised to conduct their own security evaluations before downloading, installing, or using any plugin. By using these plugins, you acknowledge and accept any risks associated with their use. We disclaim any liability for any harm or damages arising from the use of the plugins listed.

Start turning complexity into an advantage

Create an account to get started with a 30-day free trial. No credit card required.

Buildkite Pipelines

Platform

  1. Pipelines
  2. Public pipelines
  3. Test Engine
  4. Package Registries
  5. Mobile Delivery Cloud
  6. Pricing

Hosting options

  1. Self-hosted agents
  2. Mac hosted agents
  3. Linux hosted agents

Resources

  1. Docs
  2. Blog
  3. Changelog
  4. Example pipelines
  5. Plugins
  6. Webinars
  7. Case studies
  8. Events
  9. Migration Services
  10. Comparisons

Company

  1. About
  2. Careers
  3. Press
  4. Brand assets
  5. Contact

Solutions

  1. Replace Jenkins
  2. Workflows for AI/ML
  3. Testing at scale
  4. Monorepo mojo
  5. Bazel orchestration

Legal

  1. Terms of Service
  2. Acceptable Use Policy
  3. Privacy Policy
  4. Subprocessors
  5. Service Level Agreement

Support

  1. System status
  2. Forum
© Buildkite Pty Ltd 2025