Jenkins Pipeline projects

This page lists the arguments you can supply to the Octopus Jenkins Pipelines commands to run against your Octopus Deploy server.

The Jenkins Pipeline support requires plugin version 3.0.0 or later and Jenkins version 2.190.1 or later.

The toolId parameter refers to the Name of the Global Tool Configuration for Octopus CLI, available at Manage Jenkins ➜ Global Tool Configuration. The serverId parameter refers to the Server ID of the OctopusDeploy Plugin configuration, available at Manage Jenkins ➜ Configure System.

Pack

Step name: octopusPack

octopusPack allows you to create a package from files on disk during your pipeline execution.

ParametersRequiredDescription
toolIdYesThe configured Octopus CLI tool to use.
packageIdYesThe ID of the package.
packageFormatYesThe format of the package, zip or nupkg.
sourcePathYesPath containing files and directories to include in package.
overwriteExistingNoOverwrite an existing package with the same name and version. Valid values are true or false. Defaults to false.
includePathsNoNew-line separated paths to include files.
outputPathNoPath to write final package. Defaults to ..
packageVersionNoPackage version, defaults to a timestamp-based version.
verboseLoggingNoTurn on verbose logging. Valid values are true or false.
additionalArgsNoAdditional arguments to pass to the Octopus CLI pack command.

Example:

octopusPack \
  additionalArgs: '-author "My Company"', \
  outputPath: './artifacts/', \
  overwriteExisting: false, \
  packageFormat: 'zip', \
  packageId: 'OctoPetShop', \
  packageVersion: '1.1.${BUILD_NUMBER}', \
  sourcePath: './bin/Release/publish/', \
  toolId: 'octocli', \
  verboseLogging: false

Push

Step name: octopusPushPackage

octopusPushPackage allows you to push packages to the package repository in an Octopus Server.

ParametersRequiredDescription
toolIdYesThe configured Octopus CLI tool to use.
serverIdYesThe configured Server ID of the target server to push the package.
spaceIdYesThe ID of the Space on the server to push the package.
packagePathsYesThe path to the package.
overwriteModeYesValid values are FailIfExists, OverwriteExisting or IgnoreIfExists.
verboseLoggingNoTurn on verbose logging. Valid values are true or false.
additionalArgsNoAdditional arguments to pass to the Octopus CLI push command.

Example:

octopusPushPackage \
  overwriteMode: 'FailIfExists', \
  packagePaths: './artifacts/OctoPetShop.1.1.${BUILD_NUMBER}.zip', \
  serverId: 'octopus-server', \
  spaceId: 'Spaces-1', \
  toolId: 'octocli'

Examples for the packagePaths parameter:

Absolute path

The path to the package can be provided as an absolute path on the Jenkins server or Agent. ${WORKSPACE} is the directory which the job runs within.

  • packagePaths: "${WORKSPACE}/artifacts/Package.0.0.${BUILD_NUMBER}.zip".
  • packagePaths: "/home/jenkins/workspace/artifacts/Package.0.0.${BUILD_NUMBER}.zip".

Relative path

The path is a relative path from the WORKSPACE directory.

  • packagePaths: "artifacts/Package.0.0.${BUILD_NUMBER}.zip"

Glob Patterns

The package selection can also be done using ANT glob patterns.

  • packagePaths: "artifacts/**/*.0.0.${BUILD_NUMBER}.zip".
    • This will pick up all the packages, in all folders under the artifacts directory with a name matching the 0.0 version and current build number.

Multiple paths

The packagePaths parameter also supports multiple values from the above options separated by a \n character.

  • packagePaths: "artifacts/package1/Package1.0.0.${BUILD_NUMBER}.zip\nartifacts/package2/Package2.0.0.${BUILD_NUMBER}.zip"

Push package info

Step: octopusPushBuildInformation

octopusPushBuildInformation allows you to push package information to an Octopus Server.

ParametersRequiredDescription
toolIdYesThe configured Octopus CLI tool to use.
serverIdYesThe configured Server ID of the target server to push the build information.
spaceIdYesThe ID of the Space on the server to push the build information.
packageIdYesThe ID of the packages to push the version information, multiple values can be provided separated by \n.
commentParserYesValid values are GitHub and Jira.
overwriteModeYesValid values are FailIfExists, OverwriteExisting or IgnoreIfExists.
gitUrlNoThe URL of the repository for the package(s).
gitBranchNoThe branch that was checked out in the repository. Available via git checkout.
gitCommitNoThe commit ID of the most recent commit on the branch. Available via git checkout.
verboseLoggingNoTurn on verbose logging. Valid values are true or false.
additionalArgsNoAdditional arguments to pass to the Octopus CLI build-information command.

Example:

octopusPushBuildInformation \
  toolId: 'octocli', \
  serverId: 'octopus-server', \
  spaceId: 'Spaces-1', \
  commentParser: 'GitHub', \
  overwriteMode: 'FailIfExists', \
  packageId: 'OctoPetShopService', \
  packageVersion: '1.2.${BUILD_NUMBER}', \
  verboseLogging: false, \
  additionalArgs: '--debug', \
  gitUrl: 'https://github.com/OctopusSamples/OctoPetShop', \
  gitBranch: '${GIT_BRANCH}', \
  gitCommit: '${GIT_COMMIT}'

Due to limitations in Jenkins Pipelines, you will need to pass the Git URL, Git Branch and Git Commit values to the octopusPushBuildInformation. Including these values will allow the build information to provide correct URL links to the source.

For a pipeline source from SCM, set the parameters to gitUrl: '${GIT_URL}' gitBranch: '${GIT_BRANCH}' gitCommit: '${GIT_COMMIT}', the checkoutVars script will not be required. For a inline pipeline definition configure the step as:

steps {
    script {
        def checkoutVars = checkout([$class: 'GitSCM', userRemoteConfigs: [[url: 'https://github.com/OctopusSamples/RandomQuotes-Java.git']]])
        env.GIT_URL = checkoutVars.GIT_URL
        env.GIT_BRANCH = checkoutVars.GIT_BRANCH
        env.GIT_COMMIT = checkoutVars.GIT_COMMIT
    }
    octopusPushBuildInformation commentParser: 'GitHub', overwriteMode: 'FailIfExists', packageId: 'randomquotes', packageVersion: "1.0.${BUILD_NUMBER}", serverId: "octopus-server", spaceId: "Spaces-2", toolId: 'Default', gitUrl: "${GIT_URL}", gitBranch: "${GIT_BRANCH}", gitCommit: "${GIT_COMMIT}"
}

Create release

Step: octopusCreateRelease

octopusCreateRelease allows you to push packages to the package repository in an Octopus Server.

ParametersRequiredDescription
toolIdYesThe configured Octopus CLI tool to use.
serverIdYesThe configured Server ID of the target server to create the release in.
spaceIdYesThe ID of the space on the server to create the release in.
projectYesThe ID of the project to create the release in.
releaseVersionYesThe version number for the release.
channelNoThe name of the target channel. Defaults to Default channel.
packageConfigsNoCollection of package versions to set when creating the release.
defaultPackageVersionNoThe default version to use for packages associated with the release.
deployThisReleaseNoDeploy release after creation. Valid values are true or false. Defaults to false.
waitForDeploymentNoWait for deployment to complete before continuing. Valid values are true or false. Defaults to false.
cancelOnTimeoutNoCancel the deployment after the waitForDeployment time. Valid values are true or false. Defaults to false.
tenantNoThe tenant to deploy the release to.
tenantTagNoThe tenant tag to deploy the release to.
deploymentTimeoutNoHow long to wait for deployment. Format is HH:mm:ss. Default is 00:10:00.
environmentConditionalThe environment to deploy release to. Required if deployThisRelease is true.
jenkinsUrlLinkbackNoInclude link to the Jenkins build that created the release. Valid values are true or false. Default is false.
releaseNotesNoInclude release notes in release. Valid values are true or false. Default is false.
releaseNotesSourceNoValid values are file or scm.
releaseNotesFileConditionalThe file path for release notes, required if releaseNotesSource is file.
verboseLoggingNoTurn on verbose logging. Valid values are true or false.
additionalArgsNoAdditional arguments to pass to the Octopus CLI create-release command.

Example:

octopusCreateRelease \
  serverId: 'octopus-server', \
  spaceId: 'Spaces-1', \
  project: 'Random Quotes', \
  releaseVersion: '2.3.${BUILD_NUMBER}', \
  toolId: 'octocli', \
  packageConfigs: [[packageName: 'Nuget.CommandLine', packageReferenceName: 'NugetCLI', packageVersion: '5.5.1']], \
  deployThisRelease: true, \
  cancelOnTimeout: false, \
  deploymentTimeout: '00:15:00', \
  environment: 'test', \
  tenant: 'The Tenant', \
  tenantTag: 'importance/high', \
  jenkinsUrlLinkback: true, \
  releaseNotes: true, \
  releaseNotesSource: 'scm'

Deploy release

Step: octopusDeployRelease

octopusDeployRelease allows you to push packages to the package repository in an Octopus Server.

ParametersRequiredDescription
toolIdYesThe configured Octopus CLI tool to use.
serverIdYesThe configured Server ID of the target server to deploy the release.
spaceIdYesThe ID of the Space on the server to deploy the release.
projectYesThe ID of the project to deploy the release.
environmentYesEnvironment to deploy release.
releaseVersionYesThe version number for the release.
cancelOnTimeoutNoCancel the deployment after the waitForDeployment time. Valid values are true or false. Defaults to false.
tenantNoThe tenant to deploy the release to.
tenantTagNoThe tenant tag to deploy the release to.
waitForDeploymentNoWait for deployment to complete before continuing. Valid values are true or false.
deploymentTimeoutNoHow long to wait for deployment. Format is HH:mm:ss. Default is 00:10:00.
variablesNoSet prompted variable values. Format is key1=value1\nkey2=value2.
verboseLoggingNoTurn on verbose logging. Valid values are true or false.
additionalArgsNoAdditional arguments to pass to the Octopus CLI deploy-release command.

Example:

octopusDeployRelease \
  toolId: 'octocli', \
  serverId: 'octopus-server', \
  spaceId: 'Spaces-1', \
  project: 'OctoPetShop', \
  environment: 'test', \
  releaseVersion: '1.2.${BUILD_NUMBER}', \
  deploymentTimeout: '00:05:00', \
  waitForDeployment: false, \
  cancelOnTimeout: true

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023