Lightweight checkout in Jenkins - Commands & Configuration

Introduction

When Jenkins runs a pipeline, it usually downloads the entire source code repository. Lightweight checkout lets Jenkins download only the pipeline script, saving time and space.

When your repository is very large but your pipeline script is small.

When you want faster pipeline startup by avoiding full repository clone.

When you only need the Jenkinsfile to run the pipeline and not the full code.

When you want to reduce network usage on your Jenkins server.

When you want to speed up multibranch pipeline scans.

Commands

This command updates or creates a Jenkins job using a YAML job definition that enables lightweight checkout.

Terminal

jenkins-jobs --conf jenkins.ini update my-pipeline-job.yaml

Expected Output

Job my-pipeline-job updated successfully

This command simulates what Jenkins does internally to fetch only the Jenkinsfile without cloning the full repo.

Terminal

git ls-remote https://github.com/example/my-repo.git

Expected Output

e1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0	refs/heads/main

This command fetches just the Jenkinsfile script from the repository, similar to lightweight checkout behavior.

Terminal

curl -s https://raw.githubusercontent.com/example/my-repo/main/Jenkinsfile

Expected Output

pipeline {

    agent any

    stages {

        stage('Build') {

            steps {

                echo 'Building...'

            }

        }

    }

}

Key Concept

Lightweight checkout downloads only the Jenkinsfile script, not the entire repository, making pipeline runs faster and lighter.

Common Mistakes

Not enabling lightweight checkout in multibranch pipeline settings.

Jenkins will clone the full repository, causing slower pipeline startup and higher resource use.

Enable the 'Lightweight checkout' option in the pipeline job configuration to fetch only the Jenkinsfile.

Using pipeline scripts that require files outside the Jenkinsfile without full checkout.

The pipeline will fail because those files are not available with lightweight checkout.

Use lightweight checkout only if your pipeline script does not depend on other repository files, or add a full checkout step later.

Summary

Lightweight checkout fetches only the Jenkinsfile, not the full repository.

It speeds up pipeline startup and reduces resource use.

Enable it in multibranch pipeline settings for best results.