Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 40 ยท Source Control and Triggers

Checking Out Code with Git

Learn how a Jenkins pipeline gets your code: checkout scm, the git step, branches, shallow clones, submodules, sparse checkout and clean workspaces.

Almost every build starts the same way: get the code. Jenkins does not keep your source on the controller; each build asks Git for the right commit and places it in a workspace on an agent. How you do that decides how fast the build is, how reproducible it is, and whether leftovers from an earlier build can poison the next one.

This lesson covers checkout scm, the git step, branch and tag selection, shallow clones, submodules, sparse checkout and cleaning the workspace. It ends with a comparison of polling and webhooks, which the next lesson explores in depth. Git itself is explained in the Git tutorial; here we focus on how Jenkins uses it. The real Jenkins cannot run on this site, so Pipeline code is read-only and the runnable examples are small stand-ins written in JavaScript.

Three ways to get code

checkout scm Use the repo that holds the Jenkinsfile.
git step Quick clone of a URL and branch.
checkout step Full control through extensions.

Start with checkout scm, reach for the others when you need them.

1 / 2

The automatic checkout and checkout scm

When a Pipeline job is defined as "Pipeline script from SCM", or when you use a multibranch job, Jenkins already knows which repository, branch and credentials produced the build. That knowledge is held in a special variable called scm. The step checkout scm clones (or updates) exactly that repository at exactly that revision.

In a Declarative Pipeline you often do not write it at all: unless you opt out, Jenkins runs a checkout for you at the start of the first agent that has a workspace. You can see it in the log as a stage named "Declarative: Checkout SCM". To control it yourself, switch the automatic one off:

GROOVY
pipeline {
  agent any
  options {
    skipDefaultCheckout(true)
  }
  stages {
    stage('Get code') {
      steps {
        checkout scm
      }
    }
    stage('Build') {
      steps {
        sh 'ls -la'
      }
    }
  }
}

Jenkins also fetches the Jenkinsfile itself before the build starts, using a lightweight request that does not create a full clone. This is why a pipeline can be defined, and fail to parse, before any workspace exists.

The git step

For a simple build of a known repository, the git step is a short form:

GROOVY
git url: 'https://git.example.com/team/app.git',
    branch: 'main',
    credentialsId: 'git-readonly-token'

It clones the repository (or fetches into an existing clone) and checks out the branch. It is convenient for scripts and small jobs, but it has fewer options than the general checkout step, and it is not tied to the job's own SCM configuration. Prefer checkout scm when the Jenkinsfile lives in the same repository you are building, and use git when you need a different repository, such as a repository of deployment manifests.

Credentials are never typed into the Jenkinsfile; you pass the ID of a stored credential. See Credentials and Secrets.

Branches, tags and the environment

After a checkout, the Git plugin sets some environment variables for the steps that follow. The most useful ones are:

Variable Typical value
GIT_COMMIT the full commit hash that was checked out
GIT_PREVIOUS_SUCCESSFUL_COMMIT the commit of the last successful build
GIT_BRANCH the branch, often with the remote name, like origin/main
GIT_URL the repository URL

Note that GIT_BRANCH usually includes origin/. In a multibranch pipeline, BRANCH_NAME holds the plain branch name and is the better choice for conditions (see Multibranch Pipelines and Pull Requests).

A job can build a branch (*/main), a tag (refs/tags/v1.2.0) or a specific commit. Remember that Git ends up in a detached HEAD state in many Jenkins checkouts: Jenkins checks out a commit, not a moving branch name. If a script runs git push, it needs to create or switch to a branch first.

The full checkout step and its extensions

The checkout step takes a description of the SCM, including a list of extensions. This is where shallow clones, submodules and sparse checkouts are switched on:

GROOVY
checkout([
  $class: 'GitSCM',
  branches: [[name: '*/main']],
  userRemoteConfigs: [[
    url: 'https://git.example.com/team/app.git',
    credentialsId: 'git-readonly-token'
  ]],
  extensions: [
    [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 20],
    [$class: 'SubmoduleOption', recursiveSubmodules: true, shallow: true],
    [$class: 'CleanBeforeCheckout']
  ]
])

Here is what each extension buys you:

  • Shallow clone (CloneOption with shallow: true and a depth) fetches only the newest commits. For a repository with ten years of history, this can turn minutes into seconds. The cost: commands that need history, such as git describe, git log over a long range, or computing a version from tags, may not work. Use a deeper clone, or fetch tags, when your build needs them.
  • Submodules (SubmoduleOption) initialize and update nested repositories. Make sure the credentials can read them too.
  • Sparse checkout (SparseCheckoutPaths) writes only chosen folders into the workspace. It is helpful in a monorepo where one pipeline builds one service.
  • Clean before checkout (CleanBeforeCheckout) removes untracked files and resets changes from a previous build in the same workspace.

You can also lower the cost further with a reference repository on the agent or by letting a build reuse its workspace, so the clone becomes a quick fetch.

Keeping the workspace honest

Builds on the same agent often reuse the same workspace directory. That is fast, and it is also a classic source of "works on the build server, fails on a fresh machine" bugs: a generated file left over from an earlier build can make a broken build pass.

Your options, from lightest to heaviest:

  1. Clean as part of the checkout (CleanBeforeCheckout or CleanCheckout).
  2. Delete the workspace at the end with the Workspace Cleanup plugin: cleanWs() inside a post { cleanup { ... } } block.
  3. Use a fresh container or ephemeral agent for every build, so there is nothing to clean. See Agents, Labels and Scaling.

A good habit is to put cleanWs() in post { cleanup { cleanWs() } } for jobs that produce a lot of data, and rely on caches (see Building Java, Node and Python Projects) rather than on leftover files.

Polling versus webhooks, in one paragraph

How does Jenkins know a new commit exists? In polling, Jenkins asks the Git server on a schedule ("anything new on main?"). It is simple and works behind firewalls, but it adds delay and load. With a webhook, the Git server calls Jenkins the moment a push happens, so builds start within seconds and Jenkins asks nothing in between. Most teams use webhooks and keep a slow poll as a safety net. The details, including cron syntax, are in Triggers: Webhooks, Polling and Schedules.

A stand-in checkout

The code below models a tiny repository as a list of commits with parents, branches and tags. A function resolves a ref to a commit, as checkout does, then lists the files in the workspace and the history a shallow clone would fetch. It is a simplification: real Git stores objects, not arrays, but the resolution rules (a branch name, a tag, or a hash prefix) are the same idea.

JS A stand-in ref resolver and shallow clone

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Every spec resolves to one commit. With depth: 1 the history shrinks to a single commit, and with sparse only the chosen folder lands in the workspace. A name that matches nothing fails early, just as a build does when the branch was deleted.

The second stand-in compares the work polling and webhooks do over a day. It counts requests only: no real network is involved, and the numbers come from the simple model written in the code.

JS Polling versus webhooks: how many requests?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

If checkout is slow, measure before you change anything. The log shows how long the clone took. A shallow clone, a reference repository or a warm workspace usually fixes it; changing the agent hardware rarely does.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does checkout scm do in a pipeline from SCM or a multibranch job?

    The scm variable remembers the repository, revision and credentials of the build, so checkout scm fetches exactly that code.
  2. 2. What is a drawback of a shallow clone with depth 1?

    A shallow clone is fast because it skips history. Builds that compute versions from tags or compare old commits need more depth or fetched tags.
  3. 3. Why does GIT_BRANCH often look like origin/main?

    The checkout uses a remote-tracking branch, so the name includes the remote. In multibranch jobs use BRANCH_NAME for the plain branch name.
  4. 4. What is the main reason to clean the workspace?

    Reused workspaces can contain generated files from older builds. Cleaning keeps each build reproducible.

Summary

  • checkout scm fetches the repository and revision that started the build; Declarative does it automatically unless you set skipDefaultCheckout.
  • The git step is a short form for simple clones, while checkout with extensions gives full control.
  • Shallow clones, submodules, sparse checkout and clean checkouts are extensions of the GitSCM checkout.
  • GIT_COMMIT and related variables tell later steps what was built; GIT_BRANCH includes the remote name.
  • Clean the workspace or use ephemeral agents so old files cannot influence new builds.
  • Webhooks start builds faster and with fewer requests than polling.

Next, decide when builds start in Triggers: Webhooks, Polling and Schedules.