The checkout Step
The checkout step gives you full control over how Jenkins clones your repository.
Syntax
checkout scmWhile the git step is a handy shortcut, the checkout step is the full-featured way to fetch source code. It exposes every option the Git plugin supports.
Why use checkout?
- Configure multiple repositories.
- Control clone depth (shallow clones for speed).
- Set submodule behavior.
- Use
checkout scmto fetch exactly what the pipeline was triggered from.
checkout scm
In a Multibranch or 'Pipeline from SCM' job, the shorthand checkout scm checks out the same commit and branch that triggered the build — the most common form.
Example
pipeline {
agent any
stages {
stage('Checkout') {
steps {
// Full form with a shallow clone for speed
checkout([
$class: 'GitSCM',
branches: [[name: '*/main']],
userRemoteConfigs: [[
url: 'https://github.com/example/my-app.git',
credentialsId: 'github-token'
]],
extensions: [[$class: 'CloneOption', depth: 1, shallow: true]]
])
}
}
}
}When to use it
- A pipeline uses checkout scm to let Jenkins automatically determine the branch and repo from the multibranch job configuration.
- A build needs files from two repositories, so a second checkout step fetches a shared config repo into a subdirectory.
- A team uses the checkout step with a custom extension to clean the workspace before cloning to avoid stale files.
More examples
Auto-checkout with checkout scm
Uses checkout scm to clone the repo and branch automatically from the multibranch or pipeline job's SCM settings.
pipeline {
agent any
stages {
stage('Checkout') {
steps {
checkout scm // uses the SCM configured in the job
}
}
}
}Checkout second repo into subdirectory
Checks out the main repository, then clones a shared configuration repo into a config/ subdirectory.
steps {
checkout scm // main repo
dir('config') {
git url: 'https://github.com/org/shared-config.git',
credentialsId: 'github-https-token'
}
}Checkout with clean before
Runs git clean -fdx before each checkout to guarantee a pristine workspace.
steps {
checkout([
$class: 'GitSCM',
branches: [[name: '*/main']],
extensions: [[$class: 'CleanBeforeCheckout']],
userRemoteConfigs: [[url: 'https://github.com/org/myapp.git',
credentialsId: 'github-https-token']]
])
}
Discussion