How to Integrate Jenkins with Git: Complete Setup Guide for CI/CD Pipelines

To integrate Jenkins with Git, install the Git Plugin, configure a Git executable in Global Tool Configuration, and configure your job to use Git SCM through either the web UI or the checkout scm step in a Jenkinsfile.

Jenkins provides a generic SCM abstraction in its core codebase that enables seamless Git integration through the Git Plugin. The jenkinsci/jenkins repository implements this via the hudson.scm.SCM base class, which the Git Plugin extends to provide concrete Git operations. This architecture allows both freestyle projects and pipelines to fetch code from any Git repository while supporting advanced features like webhook triggers and changelog tracking.

Core Architecture for Jenkins Git Integration

Jenkins delegates all source control operations to plugins through a well-defined API. According to the jenkinsci/jenkins source code, the Git Plugin implements several core interfaces to provide Git support.

The SCM Abstraction Layer

The hudson.scm.SCM class in core/src/main/java/hudson/scm/SCM.java serves as the abstract base class that all SCM plugins must extend. The Git Plugin provides hudson.plugins.git.GitSCM as its concrete implementation, handling repository cloning, branch fetching, and changelog generation.

Polling and Trigger Support

The jenkins.triggers.SCMTriggerItem interface (core/src/main/java/jenkins/triggers/SCMTriggerItem.java) enables jobs to poll repositories and respond to external triggers. This interface invokes the poll method on the SCM implementation to detect changes without performing a full checkout.

Extension Points

The jenkins.scm.SCMDecisionHandler class (core/src/main/java/jenkins/scm/SCMDecisionHandler.java) provides an extension point that allows plugins to influence polling behavior and checkout decisions dynamically.

Step-by-Step: How to Integrate Jenkins with Git

Install the Git Plugin

Navigate to Manage Jenkins → Manage Plugins, select the Available tab, and search for "Git plugin". Click Install without restart to deploy the plugin immediately.

The plugin bundles hudson.plugins.git.GitSCM, which implements the core SCM interface required for all Git operations.

Configure Git Tool Installation

1. Go to Manage Jenkins → Global Tool Configuration.

2. Under Git installations, click Add Git.

3. Provide a name (e.g., Default) and either allow Jenkins to auto-detect the executable or specify the full path to the git binary.

4. Save the configuration.

Jenkins validates the executable path using hudson.util.FormValidation.validateExecutable("git"), as tested in test/src/test/java/hudson/util/FormValidationTest.java.

Create a Job with Git SCM

Freestyle Project Configuration

1. Create a new Freestyle project.

2. Under Source Code Management, select Git.

3. Enter the Repository URL (e.g., https://github.com/example/my-app.git).

4. Select credentials from the dropdown or add new SSH key/username-password credentials.

5. Specify branches to build (e.g., */main).

Declarative Pipeline Configuration

Create a Jenkinsfile in your repository root:

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Build') {
            steps {
                sh './gradlew build'
            }
        }
    }
}

The checkout scm step automatically instantiates the configured GitSCM object and delegates to the core SCM API for workspace preparation and credential masking.

Pipeline Configuration Examples

Accessing Change Sets in Builds

After checkout, access commit metadata using the currentBuild.changeSets property, which is populated via the RunWithSCM interface (core/src/main/java/jenkins/scm/RunWithSCM.java):

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                checkout scm
                script {
                    def changeSets = currentBuild.changeSets
                    for (cs in changeSets) {
                        for (entry in cs.items) {
                            echo "Commit ${entry.commitId} by ${entry.author}: ${entry.msg}"
                        }
                    }
                }
            }
        }
    }
}

Programmatic Job Creation (Java API)

For advanced automation, create Git-backed jobs programmatically using the Jenkins Java API:

import hudson.plugins.git.GitSCM;
import hudson.model.FreeStyleProject;
import jenkins.model.Jenkins;
import hudson.plugins.git.UserRemoteConfig;
import hudson.plugins.git.BranchSpec;

Jenkins j = Jenkins.get();
FreeStyleProject proj = j.createProject(FreeStyleProject.class, "git-example");

GitSCM git = new GitSCM(
    List.of(new UserRemoteConfig("https://github.com/example/my-app.git", null, null, null)),
    List.of(new BranchSpec("*/main")),
    false, false, null, null, null
);

proj.setScm(git);
proj.save();

This demonstrates how FreeStyleProject accepts any SCM implementation, allowing the Git Plugin to integrate seamlessly with Jenkins core.

Triggering Builds Automatically

Configure SCM Polling

For freestyle jobs, enable Poll SCM in the build triggers section and enter a cron schedule (e.g., H/5 * * * * for every five minutes). The polling mechanism uses SCMTriggerItem.resolveMultiScmIfConfigured() to invoke Git-specific polling logic without checking out code.

Webhook Integration

Configure your Git provider to send POST requests to http://your-jenkins/github-webhook/ (GitHub) or the appropriate endpoint for GitLab/Bitbucket. The Git Plugin listener parses the payload and schedules builds immediately.

Test webhook delivery using curl:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"ref":"refs/heads/main"}' \
     http://jenkins.example.com/github-webhook/

Summary

• Install the Git Plugin to provide the hudson.plugins.git.GitSCM implementation of the core hudson.scm.SCM interface.
• Configure Git executables in Global Tool Configuration, validated via hudson.util.FormValidation.
• Use checkout scm in Jenkinsfiles to automatically instantiate the configured Git SCM for the job.
• Implement triggers using either SCM polling via SCMTriggerItem or webhooks for immediate build scheduling.
• Access change sets through currentBuild.changeSets, populated by the RunWithSCM interface in the core codebase.

Frequently Asked Questions

Do I need to install Git on Jenkins agents?

Yes, the Git executable must be available on every agent that executes Git operations. Configure this in Manage Jenkins → Global Tool Configuration, where Jenkins validates the path using FormValidation.validateExecutable(). Alternatively, use the Git Client Plugin with JGit for a pure Java implementation that does not require a system Git installation.

How does the checkout scm step work in Jenkins pipelines?

The checkout scm step is a built-in pipeline command that retrieves the SCM configuration defined in the job settings and executes a checkout. According to the jenkinsci/jenkins source code, this step creates an instance of the configured SCM implementation (such as GitSCM) and calls its checkout() method, which handles workspace cleanup, cloning, changelog generation, and credential injection automatically.

Can I integrate Jenkins with self-hosted Git repositories?

Yes, Jenkins integrates with any Git repository accessible via HTTPS or SSH, including self-hosted GitLab, Gitea, or Bitbucket instances. When configuring the Git SCM, enter the repository URL pointing to your internal server and provide appropriate credentials. The core SCM abstraction and GitSCM implementation handle the protocol details identically regardless of hosting provider.

What is the difference between the Git Plugin and the GitHub Branch Source plugin?

The Git Plugin provides the core hudson.plugins.git.GitSCM implementation for checking out repositories and works with any Git provider. The GitHub Branch Source plugin (part of the GitHub Organization folder type) extends this functionality to automatically discover branches and pull requests using the GitHub API, creating Multibranch Pipeline jobs dynamically. For simple repository checkout, the Git Plugin is sufficient; for complex GitHub workflows with PR discovery, use the Branch Source plugin.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}