Run Selector

This plugin contains Run Selector, which originally used to be in Copy Artifact Plugin.

The Run Selector extension point has several implementations which can be used to select a specific build:

• Status Run Selector - selects the run based on the last status. Possible filters are:
  • Stable
  • Stable or unstable
  • Unstable
  • Failed
  • Completed (any status)
  • Any (including not completed)
• Permalink Run Selector - selects the run based on the permalink. Possible values:
  • lastBuild
  • lastStableBuild
  • lastSuccessfulBuild
  • lastFailedBuild
  • lastUnstableBuild
  • lastUnsuccessfulBuild
  • lastCompletedBuild
• Triggering Run Selector - selects the run that triggered this run (usually the upstream run)
• Build Number Run Selector - selects the run based on the given build number parameter
• Parameterized Run Selector - selects the run based on a parameter
• Fallback Run Selector - tries multiple selectors consequently

Moreover, you can specify a Run Filter, that can be used as an additional condition for the Run Selector. The implementations for the Run Filter are the followings:

• Downstream Run Filter - selects a run which is a downstream of a run build (Note: this is not applicable for Pipeline jobs)
• Parameters Run Filter - filter to find builds matching particular parameters
• Saved Run Filter - selects the saved build (marked "keep forever")
• Parameterized Run Filter - selects the run based on a parameter
• Display Name Run Filter - selects the run based on its display name
• And Run filter - accepts a build only when every underlying filters accepts it
• Or Run filter - accepts a build when any of underlying filters accepts it
• Not Run filter - accepts a build when the underlying filters don't accept it

This plugin may also be used in Pipeline code. It provides the selectRun step that selects a specific build based on the input parameters. The step returns a RunWrapper object which can be used as input parameter for other steps.

By default, if no selector parameter is provided, the selectRun step selects the last stable build from the upstream job.

def runWrapper = selectRun 'upstream-project-name'

Alternatively, you can specify the StatusRunSelector. For example, if you'd like to select the last successful build (stable or unstable), the value of the buildStatus parameter has to be SUCCESSFUL:

def runWrapper = selectRun job: 'upstream-project-name', 
 selector: status('SUCCESSFUL') 

The complete list of buildStatus values may be found in the Pipeline Snippet Generator.

Or, if you'd like to make use of Permalink, you can use the PermalinkRunSelector. For example, the permalink for selecting the last unstable build is lastUnstableBuild:

def runWrapper = selectRun job: 'upstream-project-name', 
 selector: permalink('lastUnstableBuild') 

The complete list of Permalink id values may be found in the Pipeline Snippet Generator.

You can select a specific build number from the upstream job. In the following example, the UPSTREAM_BUILD_NUMBER is a build parameter.

def runWrapper = selectRun job: 'upstream-project-name', 
 selector: buildNumber(UPSTREAM_BUILD_NUMBER)

You may have an upstream job that triggers a specific downstream job by using the build step:

build 'downstream-project-name'

A possible solution to select the run that triggered your downstream job is by using the TriggeringRunSelector:

def runWrapper = selectRun job: 'upstream-project-name', 
 selector: triggering() 

Of course you could instead (and more explicitly) have the upstream build pass currentBuild.number as a build parameter.