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

> Learn how to easily integrate Jenkins with Git for your CI/CD pipelines. Follow our complete setup guide to streamline your development workflow and automate builds.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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:

```groovy
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`](https://github.com/jenkinsci/jenkins/blob/main/core/src/main/java/jenkins/scm/RunWithSCM.java)):

```groovy
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:

```java
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:

```bash
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.