Secure Copy plugin

The CloudBees Secure Copy plugin is deprecated. We invite you to use its replacement, the cluster wide copy of artifacts documented in Cluster-wide Copy Artifacts. The CloudBees Secure Copy plugin will be supported until September 1st, 2018 with exclusively security and severity one fixes. Beyond this date, the plugin will no longer be supported.

The Secure Copy plugin provides the ability to share artifacts meeting defined criteria between two jobs on different Jenkins instances (or the same Jenkins instance). The job that will consume the artifacts creates an import build step and is assigned a random key for that build step. The job that will produce the artifacts is then (manually) given the importer’s key and generates a secret which is (manually) given to the import build step. This sets up the trusted channel between the two jobs. Every time the consuming job runs, it will copy the latest build artifacts meeting the criteria defined in the producing job.

The Secure Copy plugin was introduced in CloudBees Jenkins Enterprise 12.04.

Creating an exported permalink

The Secure Copy plugin creates a one way link between two jobs. We will call the job producing the artifacts the Producer, and the job that will consume the artifacts the Consumer.

The Producer job must be configured to archive the artifacts to be shared.

  • For jobs using the Maven job type, if the Maven lifecycle is advanced to a phase on or after the "package" phase, all the artifacts that are attached to the Maven reactor will be automatically archived by the Jenkins job.

    Do not confuse a Maven project built using a Freestyle job type and a Maven Build Step with a Maven project built using a Maven job type. The first does not have automatic archiving of artifacts, while the second does.
  • For all other job types (e.g. Freestyle, Matrix, etc), it is necessary to configure the "Archive Artifacts" publisher.

    A Maven project built with a Freestyle job type will need the "Archive Artifacts" publisher configured.

The Producer job will also need the appropriate permalink which is used to select the build from which the artifacts will be copied. Jenkins comes with a number of built-in permalinks:

  • Last build - the most recent build. This is rarely useful, as it can include a currently running build.

  • Last stable build - the most recent stable build. Usually a good choice.

  • Last successful build - the most recent successful build. A good choice if you can accept artifacts from builds with test failures.

  • Last failed build - the most recent failed build. Probably not useful unless implementing some sort of automated failure analysis.

  • Last unstable build - the most recent unstable build. Again rarely useful.

  • Last unsuccessful build - the most recent unsuccessful build. Again rarely useful.

In addition, Jenkins plugins can define their own permalinks. For example, the "Promoted builds" plugin defines a permalink for each promotion process.

Creating an exported permalink starts with adding an "Import artifacts from an exported permalink" build step to the Consumer job. See Adding the "Import artifacts from an exported permalink" and After adding the "Import artifacts from an exported permalink"

sec copy sel buildstep
Figure 1. Adding the "Import artifacts from an exported permalink"
sec copy key generated
Figure 2. After adding the "Import artifacts from an exported permalink"

When the build step has been added, a random key will be generated. This key will be provided to the Producer job, which will generate a secret to be given to the Consumer job.

If the Producer and Consumer jobs are on the same Jenkins instance, or if you are navigating away from the Consumer job’s configure screen, be sure to save the configuration after adding the build step. The key is generated when the build step is added, and if the job is not saved, the next time the build step is added a new key will be generated.

On the Producer job navigate to the "Exports" screen (The exported permalinks screen) and select the "Create" option. Enter the key from the Consumer job (Creating an exported permalink) and select the permalink (Selecting the permalink to export). Click on the "Create" button to generate the secret (An exported permalink with generated secret).

sec copy producer exports
Figure 3. The exported permalinks screen
sec copy export create
Figure 4. Creating an exported permalink
sec copy secret generated
Figure 6. An exported permalink with generated secret

On the Consumer job’s configure screen enter the secret generated by the Producer job (A fully configured "Import artifacts from an exported permalink" build step) along with any other configuration options, such as:

  • An Apache Ant-style glob pattern to select a subset of artifacts to copy.

  • The target directory into which the artifacts should be copied.

  • Whether to flatten any directory structure information from the Producer job.

  • Whether this build step is optional; if not, the Consumer build will be marked as failed if there are no artifacts to copy.

sec copy secret entered
Figure 7. A fully configured "Import artifacts from an exported permalink" build step