Branch indexing and scanning in Jenkins - Commands & Configuration

Introduction

When you have many branches in your source code repository, Jenkins needs a way to find and manage them automatically. Branch indexing and scanning help Jenkins discover new branches and update existing ones so it can build them without manual setup.

When you want Jenkins to automatically detect new branches pushed to your Git repository and create jobs for them.

When you want to keep Jenkins jobs updated with changes in branch names or deletions.

When you manage multiple feature branches and want Jenkins to build each branch separately.

When you want to save time by avoiding manual job creation for every new branch.

When you want Jenkins to scan your repository regularly to keep branch jobs in sync.

Commands

This command updates or creates a Jenkins multibranch pipeline job using the configuration file. It sets up branch indexing and scanning based on the YAML file.

Terminal

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

Expected Output

Job 'my-multibranch-job' updated successfully

→

--conf - Specifies the Jenkins server configuration file

This command triggers branch indexing manually on the multibranch job to scan the repository and discover branches.

Terminal

curl -X POST http://localhost:8080/job/my-multibranch-job/indexing

Expected Output

No output (command runs silently)

This command fetches the list of branch jobs created by the multibranch pipeline and their build status.

Terminal

curl http://localhost:8080/job/my-multibranch-job/api/json?tree=jobs[name,color]

Expected Output

{"jobs":[{"name":"feature-1","color":"blue"},{"name":"feature-2","color":"blue"}]}

Key Concept

If you remember nothing else from branch indexing and scanning, remember: it lets Jenkins automatically find and manage all branches in your repository without manual job setup.

Common Mistakes

Not triggering branch indexing after creating or updating the multibranch job

Jenkins will not detect new or changed branches until indexing runs, so builds won't start for those branches.

Always trigger branch indexing manually or configure periodic indexing to keep branch jobs updated.

Using a single pipeline job instead of a multibranch pipeline for multiple branches

A single pipeline job cannot automatically detect or build multiple branches separately.

Use a multibranch pipeline job that supports branch indexing and scanning.

Summary

Use a multibranch pipeline job to let Jenkins manage multiple branches automatically.

Trigger branch indexing to scan the repository and discover branches.

Check branch jobs and their build status via Jenkins API or UI.