> User Documentation Home

User Handbook
Tutorials
Resources

The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Parameterized Remote Trigger Plugin

View this plugin on the Plugins site

step([$class: 'RemoteBuildConfiguration']): Trigger a remote parameterized job

  • abortTriggeredJob (optional)
    • Type: boolean
  • auth2 (optional)
    Using this parameter you can override the authentication used to connect to the selected remote Jenkins.
    • Don't Override
      The authentication configured in the (global) settings of the selected 'remote host' is used.
    • Token Authentication
      The specified user id and Jenkins API token is used.
    • Credentials Authentication
      The specified Jenkins Credentials are used. This can be either user/password or user/API Token.
    • No Authentication
      No Authorization header will be sent, independent of the global 'remote host' settings.
    • Bearer Authentication
      The bearer token is used.
    Note: Jenkins API Tokens are recommended since, if stolen, they allow access only to a specific Jenkins while user and password typically provide access to many systems.
      Nested Choice of Objects
    • BearerTokenAuth
      • token (optional)
        • Type: class hudson.util.Secret
    • CredentialsAuth
      • credentials (optional)
        • Type: String
    • NoneAuth
      • NullAuth
        • TokenAuth
          • apiToken (optional)
            • Type: class hudson.util.Secret
          • userName (optional)
            • Type: String
      • blockBuildUntilComplete (optional)
        • Type: boolean
      • disabled (optional)
        Set this field to disable the job step instead of removing it from job configuration.
        • Type: boolean
      • enhancedLogging (optional)
        Enable Enhanced Logging
        If this option is enabled, the console output of the remote job is also logged.
        • Type: boolean
      • httpGetReadTimeout (optional)
        • Type: int
      • httpPostReadTimeout (optional)
        • Type: int
      • job (optional)
        Remote Job Name or full URL.
        The name or URL of the job on the remote Jenkins host which you would like to trigger. If the full job URL is specified the URL of the remote Jenkins host configured above will be ignored.
        • Type: String
      • loadParamsFromFile (optional)
        • Type: boolean
      • maxConn (optional)
        The max concurrent connections to the remote host, default is 1, max is 5. It'll be 5 even if you set it greater than 5. Note: Set this field with caution, too many concurrent requests will not only fail your local jobs,
        but also block the remote server.
        • Type: int
      • overrideTrustAllCertificates (optional)
        • Type: boolean
      • parameterFile (optional)
        • Type: String
      • parameters (optional)
        Job Parameters
        Parameters which will be used when triggering the remote job.
        If no parameters are needed, then just leave this blank.
        Any line start with a pound-sign (#) will be treated as a comment.
        • Type: String
      • pollInterval (optional)
        • Type: int
      • preventRemoteBuildQueue (optional)
        • Type: boolean
      • remoteJenkinsName (optional)
        • Type: String
      • remoteJenkinsUrl (optional)
        It is possible to override the Remote Jenkins URL for each Job separately.
        • Type: String
      • shouldNotFailBuild (optional)
        Do Not Fail If Remote Fails
        If this option is enabled, the build will not fail even if the remote build fails.
        • Type: boolean
      • token (optional)
        Remote Job Token
        Security token which is defined on the job of the remote Jenkins host.
        If no job token is needed to trigger this job, then just leave it blank
        • Type: String
      • trustAllCertificates (optional)
        Trust all certificates

        It is possible to override/rewrite the 'Trust all certificate'-setting for each Job separately. Setting this checkbox to 'true' will result in accepting all certificates for the given Job.

        If your remote Jenkins host has a self-signed certificate or its certificate is not trusted, you may want to enable this option. It will accept untrusted certificates for the given host.

        This is unsafe and should only be used for testing or if you trust the host.

        • Type: boolean
      • useCrumbCache (optional)
        Set this field to enable cache of the crumb of remote server.
        It'll be more efficient for the local job execution & more stable for remote server when massive concurrent jobs are triggered.
        This cache will be cleared every 10 minutes.
        • Type: boolean
      • useJobInfoCache (optional)
        Set this field to enable cache of the job info of remote server.
        It'll be more efficient for the local job execution & more stable for remote server when massive concurrent jobs are triggered.
        This cache will be cleared every 10 minutes.
        • Type: boolean

      triggerRemoteJob: Trigger Remote Job

      The `triggerRemoteJob` pipeline step triggers a job on a remote Jenkins.
      The full documentation is available in GitHub.

      Example: 
      //Trigger remote job
def handle = triggerRemoteJob(remoteJenkinsName: 'remoteJenkins', job: 'RemoteJob')

//Get information from the handle
def status = handle.getBuildStatus()
def buildUrl = handle.getBuildUrl()
echo buildUrl.toString() + " finished with " + status.toString()

//Download and parse the archived "build-results.json" (if generated and archived by remote build)
def results = handle.readJsonFileFromBuildArchive('build-results.json')
echo results.urlToTestResults //only example


//List other available methods
echo handle.help()
      • job
        Remote Job Name or full URL.
        The name or URL of the job on the remote Jenkins host which you would like to trigger. If the full job URL is specified the URL of the remote Jenkins host configured above will be ignored.

        mandatory: yes

        • Type: String
      • abortTriggeredJob (optional)
        • Type: boolean
      • auth (optional)
        Using this parameter you can override the authentication used to connect to the selected remote Jenkins.
        • Don't Override
          The authentication configured in the (global) settings of the selected 'remote host' is used.
        • Token Authentication
          The specified user id and Jenkins API token is used.
        • Credentials Authentication
          The specified Jenkins Credentials are used. This can be either user/password or user/API Token.
        • No Authentication
          No Authorization header will be sent, independent of the global 'remote host' settings.
        Note: Jenkins API Tokens are recommended since, if stolen, they allow access only to a specific Jenkins while user and password typically provide access to many systems.
          Nested Choice of Objects
        • BearerTokenAuth
          • token (optional)
            • Type: class hudson.util.Secret
        • CredentialsAuth
          • credentials (optional)
            • Type: String
        • NoneAuth
          • NullAuth
            • TokenAuth
              • apiToken (optional)
                • Type: class hudson.util.Secret
              • userName (optional)
                • Type: String
          • blockBuildUntilComplete (optional)
            Wait/Block Until Remote Build Complete
            If enabled the remote job is called synchronously and the plugin waits until the remote job finished.
            If disabled the plugin triggers the remote job and returns.

            In both cases a handle is returned for further tracking the remote job or getting the results (see plugin main help page).

            mandatory: no
            default: true

            • Type: boolean
          • disabled (optional)
            Set this field to disable the job step instead of removing it from job configuration.
            • Type: boolean
          • enhancedLogging (optional)
            Enable Enhanced Logging
            If this option is enabled, the console output of the remote job is also logged.

            mandatory: no
            default: false

            • Type: boolean
          • httpGetReadTimeout (optional)
            • Type: int
          • httpPostReadTimeout (optional)
            • Type: int
          • loadParamsFromFile (optional)
            • Type: boolean
          • maxConn (optional)
            The max concurrent connections to the remote host, default is 1, max is 5. It'll be 5 even if you set it greater than 5. Note: Set this field with caution, too many concurrent requests will not only fail your local jobs,
            but also block the remote server.
            • Type: int
          • overrideTrustAllCertificates (optional)
            • Type: boolean
          • parameterFile (optional)
            • Type: String
          • parameters (optional)
            Job Parameters
            Parameters which will be used when triggering the remote job.
            If no parameters are needed, then just leave this blank.
            Any line start with a pound-sign (#) will be treated as a comment.
            • Type: String
          • pollInterval (optional)
            Polling Interval
            The plugin identifies the status of the remote build by polling. Here you can specify how often the plugin shall poll the remote status.
            Be aware that polling too often might cause an increased load on the remote Jenkins.

            mandatory: no
            default: 10

            • Type: int
          • preventRemoteBuildQueue (optional)
            Prevent Remote Build Queue
            Wait to trigger remote builds until no other builds are running.

            mandatory: no
            default: false

            • Type: boolean
          • remoteJenkinsName (optional)
            Remote Jenkins Name
            The name of the remote Jenkins as configured in the Jenkins global configuration (Manage Jenkins > Configure System > Parameterized Remote Trigger Configuration > Remote Hosts).

            mandatory: yes

            • Type: String
          • remoteJenkinsUrl (optional)
            It is possible to override the Remote Jenkins URL for each Pipeline separately.

            mandatory: no

            • Type: String
          • shouldNotFailBuild (optional)
            Do Not Fail If Remote Fails
            If this option is enabled, the build will not fail even if the remote build fails.

            mandatory: no
            default: false

            • Type: boolean
          • token (optional)
            Remote Job Token
            Security token which is defined on the job of the remote Jenkins host.
            If no job token is needed to trigger this job, then just leave it blank

            mandatory: no
            default: ""

            • Type: String
          • trustAllCertificates (optional)
            Trust all certificates

            It is possible to override/rewrite the 'Trust all certificate'-setting for each Job separately. Setting this checkbox to 'true' will result in accepting all certificates for the given Job.

            If your remote Jenkins host has a self-signed certificate or its certificate is not trusted, you may want to enable this option. It will accept untrusted certificates for the given host.

            This is unsafe and should only be used for testing or if you trust the host.

            • Type: boolean
          • useCrumbCache (optional)
            Set this field to enable cache of the crumb of remote server.
            It'll be more efficient for the local job execution & more stable for remote server when massive concurrent jobs are triggered.
            This cache will be cleared every 10 minutes.
            • Type: boolean
          • useJobInfoCache (optional)
            Set this field to enable cache of the job info of remote server.
            It'll be more efficient for the local job execution & more stable for remote server when massive concurrent jobs are triggered.
            This cache will be cleared every 10 minutes.
            • Type: boolean

          Was this page helpful?

          Please submit your feedback about this page through this quick form.

          Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

              


          See existing feedback here.