Skip to content

Latest commit

 

History

History
324 lines (250 loc) · 11.1 KB

checkoutScm.md

File metadata and controls

324 lines (250 loc) · 11.1 KB
Raw

checkoutScm

The main purpose of the checkoutScm step is to remove some complexity from pipeline scripts and bring back some functionality not existing yet in Jenkins pipeline.

Table of contents

Features

Credential auto lookup

Especially in company environments where you have one account for Jenkins checkouts setting the correct credentials in each project/pipeline script can be annoying.

If you provide a JSON file at this location resources/credentials/scm/credentials.json in the format described in Credentials the step will automatically try to lookup the credentials for the provided scm url and use them

This step uses the best match by using the PatternMatcher so the Credential with the most matching characters will be used for checkout.

GIT_BRANCH environment variable support

With Jenkins pipeline the support for the GIT_BRANCH environment variable was removed. This step reenables this functionality by calling the setGitBranch step after checkout.

💡 If you are using Mode 2 (Job SCM) you have to add the "Check out to specific local branch" extension with empty branch name checkout-to-local-branch

SCM_URL environment variable support

With pipeline also the SCM_URL environment variable disappeared. This step reenables this functionality by calling the setScmUrl step after checkout

Modes

The checkoutScm option run with two modes

Mode 1 (Configuration Mode)

This mode is used when your Jenkinsfile and the project to build are not in the same repository.

You have to provide a configuration for this step. The configuration uses the same format/syntax as the checkout: General SCM step for GIT.

💡 See also How to Customize Checkout for Pipeline Multibranch

You have to provide at least the repository url for the checkout or a userRemoteConfig or userRemoteConfigs configuration.

Examples

Example 1: Simple checkout
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

checkoutScm( 
    (SCM) : [
        (SCM_URL) : "git@domain.tld/group/project.git",
    ]
)
Example 2: Advanced checkout
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

checkoutScm( 
    (SCM) : [
        (SCM_URL) : "git@domain.tld/group/project.git",
        (SCM_BRANCHES) : [[name: '*/master'], [name: '*/develop']],
        (SCM_DO_GENERATE_SUBMODULE_CONFIGURATION) : false,
        (SCM_EXTENSIONS) : [[$class: 'LocalBranch']]
    ]
)
Example 3: Checkout with url and credentialId
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

checkoutScm( 
    (SCM) : [
        (SCM_URL) : "git@domain.tld/group/project.git",
        (SCM_CREDENTIALS_ID) : "jenkins-credential-id",
        (SCM_BRANCHES) : [[name: '*/master'], [name: '*/develop']],
    ]
)
Example 4: Checkout with userRemoteConfigs
import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

checkoutScm( 
    (SCM) : [
        (SCM_BRANCHES) : [[name: '*/master'], [name: '*/develop']],
        (SCM_EXTENSIONS) : [[$class: 'LocalBranch']],
        (SCM_USER_REMOTE_CONFIGS) : [[credentialsId: 'jenkins-credential-id', url: 'git@domain.tld/group/project.git']]
    ]
)

Mode 2 (Job SCM Configuration)

This mode is used when your Jenkinsfile and the project to build are in the same repository. In this case the pipeline has an scm variable which contains the configuration made on the Job page.

mode-2

To do a checkout within your pipeline script with this mode you have to call the step in your pipeline as follows:

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

checkoutScm( 
    (SCM): [
        (SCM_USE_SCM_VAR): true
    ]
)

The scm checkout will be executed exactly with the options you specified on the job page so you can for example to merges with branches, specifiy advanced clone behaviors etc.

The GIT_BRANCH and SCM_URL detection also works in this mode

💡 In order to detect the branch name please add the "Checkout to specific local branch" option

💡 When useScmVar is set to true this will overwrite any other option specified

Configuration options

Complete list of all configuration options. Please note that they can not be used all at the same time.

All configuration options must be inside the scm (ConfigConstants.SCM) map element to be evaluated and used by the step.

💡 Use the "pipeline-syntax" helper which is available on pipeline job configuration pages to generate the configuration options

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

checkoutScm( 
    (SCM) : [
        (SCM_BRANCHES): [[name: 'branch identifier']],
        (SCM_CREDENTIALS_ID): "jenkins credential id",
        (SCM_DO_GENERATE_SUBMODULE_CONFIGURATION): false,
        (SCM_EXTENSIONS): [[$class: 'Class of git extension']],
        (SCM_SUBMODULE_CONFIG): [],
        (SCM_URL): "repository-url",
        (SCM_USER_REMOTE_CONFIG): [credentialsId: 'jenkins-credential-id', url: 'git@domain.tld/group/project.git'],
        (SCM_USER_REMOTE_CONFIGS): [[credentialsId: 'jenkins-credential-id', url: 'git@domain.tld/group/project.git']],
        (SCM_USE_SCM_VAR): true
    ]
)

branches (optional)
Constant ConfigConstants.SCM_BRANCHES
Type List of Map [name: 'name-of-branch']
Default [[name:'*/master'], [name: '*/develop']]

Use this configuration option to specify the branches you want to checkout

❗ This configuration option is not used when useScmVar is set to true

credentialsId (optional)
Constant ConfigConstants.SCM_CREDENTIALS_ID
Type String
Default null

When provided this credential id is used to generate the userRemoteConfigs for checkout. If not provided the step will try to do a credential auto lookup by using resources/credentials/scm/credentials.json.

❗ This configuration option is not used when

  • userRemoteConfig or
  • userRemoteConfigs or
  • useScmVar

are set

doGenerateSubmoduleConfigurations (optional)
Constant ConfigConstants.SCM_DO_GENERATE_SUBMODULE_CONFIGURATION
Type Boolean
Default false

Set to either false or true. At the moment no use case was found where true made sense. It is safe to omit this configuration option.

❗ This configuration option is not used when useScmVar is set to true

extensions (optional)
Constant ConfigConstants.SCM_EXTENSIONS
Type List of Map
Default [[$class: 'LocalBranch']]

Use this config option to specify your extensions like "Clean before checkout" or "Checkout to specific local branch"

To ensure that GIT_BRANCH is set correctly always add the LocalBranch extension.

submoduleCfg (optional)
Constant ConfigConstants.SCM_SUBMODULE_CONFIG
Type List
Default []

For now no use case was found for this option but to make sure all config options are supported this option was added

❗ This configuration option is not used when useScmVar is set to true

url
Constant ConfigConstants.SCM_URL
Type String
Default null

The url to the repository, e.g. "git@domain.tld/group/project.git"

❗ This configuration option is not used when

  • userRemoteConfig or
  • userRemoteConfigs or
  • useScmVar

are set

userRemoteConfig (optional)
Constant ConfigConstants.SCM_USER_REMOTE_CONFIG
Type Map with format [credentialsId: 'jenkins-credential-id', url: 'git@domain.tld/group/project.git']
Default null

Can be used to define one userRemoteConfig. This option will be transformed into userRemoteConfigs by putting it in a List

❗ This configuration option is not used when

  • userRemoteConfigs or
  • useScmVar

are set

userRemoteConfigs (optional)
Constant ConfigConstants.SCM_USER_REMOTE_CONFIGS
Type List of Map with format [[credentialsId: 'jenkins-credential-id', url: 'git@domain.tld/group/project.git']]
Default null

❗ This configuration option is not used when

  • userRemoteConfigs or
  • useScmVar

are set

useScmVar (optional)
Constant ConfigConstants.SCM_USE_SCM_VAR
Type Boolean
Default false

When set to true the step uses the scm variable of the pipeline to checkout the scm.

Related classes