In a previous post, I wrote how to create a Bitbucket Pipe and integrate it with Octopus Deploy. If you’re starting out with Pipes for the first time, it’s worth a read.
In this post, I’ll give you an overview of the new experimental Bitbucket Pipe for Octopus - octopus-cli-run. If you’re interested in trying the experimental pipe, you can use it to run commands from the Octopus CLI, allowing you to further integrate your Atlassian Bitbucket Pipeline with Octopus to manage your packages, releases, and deployments.
In this post
Pipe YAML Definition
The base definition of the Pipe includes the reference to its repository hosted on Bitbucket. It has also been published as octopipes/octopus-cli-run on Docker Hub.
It has one required CLI_COMMAND variable. This is the CLI command to run.
To use the Pipe in your bitbucket-pipelines.yml file, add the following YAML snippet to the script section:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: "<string>"
# EXTRA_ARGS: ['<string>','<string>' ..] # Optional
# DEBUG: "<boolean>" # Optional
The Pipe also provides an optional array variable called EXTRA_ARGS that you can use to include any additional command line arguments for the specified command.
Pipe variable definitions
Variables in Bitbucket Pipelines and Pipes are configured as Environment variables. As the octopus-cli-run Pipe contains a number of commands, the specific variables that are required depend on which command you are using. See the README for further details of the variables that are required for each command.
Supported commands
The octopus-cli-run Pipe was written with the most commonly used CLI commands in mind, and it’s actually built on top of the Octopus CLI Docker image. This includes the ability to:
- Package your files or build artifacts using pack.
- Send packages to the Octopus built-in repository using push.
- Push build information to Octopus using build-information.
- Automate creation of releases using create-release.
- Deploy releases that have already been created using deploy-release.
Next, we’ll explore what the Pipeline steps look like for each of the commands using the PetClinic sample application available on Bitbucket. To keep it simple, the steps have been reduced to the minimum definition that is needed.
Pack
The pack command allows you to create packages (either as zip or nupkg) from files on disk, without the need for a .nuspec or .csproj file.
To create a package, define a step like this:
- step:
name: octo pack mysql-flyway
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'pack'
ID: 'petclinic.mysql.flyway'
FORMAT: 'Zip'
VERSION: '1.0.0.0'
SOURCE_PATH: 'flyway'
OUTPUT_PATH: 'flyway'
artifacts:
- "flyway/*.zip"
This packages the flyway folder and creates a zip file named petclinic.mysql.flyway.1.0.0.0.zip in the same folder.
Push
The push command enables you to push packages (.zip, .nupkg, .war, etc) to the Octopus built-in repository
It also supports pushing multiple packages at the same time. To perform a multi-package push, define a step like this:
- step:
name: octo push
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'push'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
PACKAGES: [ "./flyway/petclinic.mysql.flyway.1.0.0.0.zip", "target/petclinic.web.1.0.0.0.war" ]
This pushes both the petclinic.mysql.flyway.1.0.0.0.zip and the petclinic.web.1.0.0.0.war packages to Octopus.
Build information
The build-information command helps you to pass information about your build (number, URL, commits) to Octopus. This information can be viewed within Octopus, and can also be used in both release notes and deployment notes.
If you have already created a build-information file, you can supply this to the command using the FILE variable. If the variable isn’t provided, the Pipe will generate its own build information file and send it to Octopus.
To push an auto-generated build info file, define a step like this:
- step:
name: octo build-information
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'build-information'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
VERSION: '1.0.0.0'
PACKAGE_IDS: ['petclinic.web']
This creates build information, associates it with version 1.0.0.0 of the petclinic.web package, and pushes it to Octopus.
Create release
The create-release command allows you to create a release in Octopus. You specify the project to create the release for using the PROJECT variable.
Optionally, you can also deploy the release to one or more environments. To achieve this, you should use the global EXTRA_ARGS array variable and provide the appropriate options. For example:
EXTRA_ARGS: ['--deployTo', 'Development', '--guidedFailure', 'True']
To create a release, and let Octopus choose the version to use, create a step like this:
- step:
name: octo create-release
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'create-release'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
PROJECT: $OCTOPUS_PROJECT
Deploy release
The deploy-release command lets you deploy releases that have already been created. You specify the project and the release number to deploy the release for using the PROJECT and RELEASE_NUMBER variables.
Choose the environment(s) to deploy to by specifying them in the DEPLOY_TO variable using either the Name or ID, like so:
DEPLOY_TO: ['Environments-1', 'Development', 'Staging', 'Test']
To deploy the latest release to Development for a project, create a step like this:
- step:
name: octo deploy-release
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'deploy-release'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
PROJECT: $OCTOPUS_PROJECT
RELEASE_NUMBER: 'latest'
DEPLOY_TO: ['Development']
Using the Pipe
Finally, let’s see the use of the Pipe in multiple steps to make up the complete Bitbucket Pipeline:
image: maven:3.6.1
pipelines:
branches:
master:
- step:
name: build petclinic
caches:
- maven
script:
- mvn -B verify -DskipTests -Dproject.versionNumber=1.0.0.0 -DdatabaseUserName=$DatabaseUserName -DdatabaseUserPassword=$DatabaseUserPassword -DdatabaseServerName=$DatabaseServerName -DdatabaseName=$DatabaseName
artifacts:
- "target/*.war"
- step:
name: octo pack mysql-flyway
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'pack'
ID: 'petclinic.mysql.flyway'
FORMAT: 'Zip'
VERSION: '1.0.0.0'
SOURCE_PATH: 'flyway'
OUTPUT_PATH: './flyway'
artifacts:
- "flyway/*.zip"
- step:
name: octo push
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'push'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
PACKAGES: [ "./flyway/petclinic.mysql.flyway.1.0.0.0.zip", "target/petclinic.web.1.0.0.0.war" ]
- step:
name: octo build-information
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'build-information'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
VERSION: '1.0.0.0'
PACKAGE_IDS: ['petclinic.web']
- step:
name: octo create-release
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'create-release'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
PROJECT: $OCTOPUS_PROJECT
- step:
name: octo deploy-release
script:
- pipe: octopusdeploy/octopus-cli-run:0.13.0
variables:
CLI_COMMAND: 'deploy-release'
OCTOPUS_SERVER: $OCTOPUS_SERVER
OCTOPUS_APIKEY: $OCTOPUS_API_KEY
OCTOPUS_SPACE: $OCTOPUS_SPACE
PROJECT: $OCTOPUS_PROJECT
RELEASE_NUMBER: 'latest'
DEPLOY_TO: ['Development']
And that’s it!
You can view the complete PetClinic bitbucket-pipelines.yml file on Bitbucket.
Sample Octopus project
You can see the PetClinic Octopus project in our samples instance.
Conclusion
Using a Bitbucket Pipe really helps to simplify the configuration in your Bitbucket Pipeline, and as an author helps to promote re-use of your actions. Check out Bitbucket Pipelines for more information and the experimental Octopus Pipe for more details on how you can use Bitbucket and Octopus together.
