Branch discovery configuration in Jenkins - Commands & Configuration

Introduction

When you have many branches in your code repository, you want Jenkins to find and build the right ones automatically. Branch discovery configuration helps Jenkins find all branches to test without setting each one manually.

When you want Jenkins to automatically find new branches in your Git repository and build them.

When you have feature branches created by multiple developers and want to test each branch separately.

When you want to avoid manually adding each new branch to Jenkins jobs.

When you want to control which branches Jenkins builds by filtering them.

When you want to keep your CI pipeline up to date with all active branches.

Commands

This command fetches the current configuration of the Jenkins multibranch pipeline job named 'my-multibranch-pipeline' so you can see or edit the branch discovery settings.

Terminal

jenkins-cli get-job my-multibranch-pipeline

Expected Output

<?xml version="1.0" encoding="UTF-8"?>

<org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject>

  <sources>

    <jenkins.branch.BranchSource>

      <source class="hudson.plugins.git.GitSCMSource">

        <id>unique-id-1234</id>

        <remote>https://github.com/example/my-app.git</remote>

        <credentialsId>git-credentials</credentialsId>

        <traits>

          <jenkins.plugins.git.traits.BranchDiscoveryTrait>

            <strategyId>1</strategyId>

          </jenkins.plugins.git.traits.BranchDiscoveryTrait>

        </traits>

      </source>

    </jenkins.branch.BranchSource>

  </sources>

</org.jenkinsci.plugins.workflow.multibranch.WorkflowMultiBranchProject>

This command updates the Jenkins multibranch pipeline job with a new configuration file that includes the branch discovery settings you want to apply.

Terminal

jenkins-cli update-job my-multibranch-pipeline < config.xml

Expected Output

No output (command runs silently)

This command triggers Jenkins to scan the repository and discover branches based on the configured branch discovery strategy, starting builds for each found branch.

Terminal

jenkins-cli build my-multibranch-pipeline

Expected Output

Started build #1 for my-multibranch-pipeline

Waiting for build to start...

This command lists all branches Jenkins has discovered and is managing under the multibranch pipeline job.

Terminal

jenkins-cli list-branches my-multibranch-pipeline

Expected Output

Branches:

  - main

  - feature/login

  - bugfix/issue-123

Key Concept

If you remember nothing else from this pattern, remember: branch discovery lets Jenkins automatically find and build all relevant branches without manual setup.

Common Mistakes

Not setting the branch discovery trait in the multibranch pipeline configuration.

Jenkins will not scan or build any branches except the default one, missing new or feature branches.

Add the BranchDiscoveryTrait with the correct strategyId to enable branch scanning.

Using an incorrect or missing credentials ID for accessing the Git repository.

Jenkins cannot access the repository to discover branches, causing scan failures.

Ensure the credentialsId matches a valid Jenkins credential with access to the Git repository.

Not triggering a scan or build after updating the branch discovery configuration.

Jenkins will not apply the new settings until a scan or build is triggered, so branches won't be discovered.

Run a build or scan command to apply the new branch discovery settings immediately.

Summary

Use Jenkins CLI to get and update the multibranch pipeline job configuration for branch discovery.

Configure the BranchDiscoveryTrait with the desired strategy to control which branches Jenkins finds.

Trigger a build or scan to let Jenkins discover and build branches automatically.