Integrating with Git

1. Configuring Git Repository URL

Field	Description	Example Value
Repository URL	URL of the Git repository to clone and build from	`https://github.com/example/my-project.git`
Credentials	Credentials to access the repository (if private)	Username/password or SSH key
Branch/Tag	Specific branch or tag to build from	`main`, `v1.0.0`

Example: Setting up Git Repository URL in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git url: 'https://github.com/example/my-project.git', branch: 'main'
            }
        }
    }
}

2. Using Branch Specifiers

Branch Specifier	Description	Examples
origin/main	Matches the main branch on the remote repository	`origin/main`
origin/feature/*	Matches all feature branches on the remote repository	`origin/feature/*`
**	Matches all branches (local and remote)	`**`
main	Matches the local main branch	`main`
release/*	Matches all release branches	`release/*`

Example: Configuring Branch Specifiers in Jenkins Pipeline

pipeline {
    agent any
    triggers {
        pollSCM 'H/5 * * * *'
    }
    stages {
        stage('Build') {
            steps {
                git branch: 'origin/feature/new-feature', url: 'https://github.com/user/repo.git'
            }
        }
    }
}

Note: When using pollSCM, Jenkins will check for changes every 5 minutes.

3. Configuring Git Credentials

Option	Values	Description
git.credentials.username	`string`	Username for Git authentication
git.credentials.password	`string`	Password or personal access token for Git authentication
git.credentials.use-ssh	`true` \| `false`	Whether to use SSH key instead of username/password

Example: Configure Git Credentials via Jenkins UI

Manage Jenkins > Configure System > Global Tool Configuration > Git

Example: Using Jenkins Credentials Plugin

withCredentials([usernamePassword(credentialsId: 'git-credentials', 
                                variable: 'GIT_CREDENTIALS')]) {
    sh "git clone https://${GIT_CREDENTIALS}@github.com/user/repo.git"
}

Note: Store Git credentials securely using Jenkins Credentials Plugin to avoid exposing them in scripts or logs.

4. Using Multiple SCM Sources

Source	Type	Configuration	Notes
SCM 1	Git	`https://github.com/user/repo1.git`	Primary repository for main codebase
SCM 2	Git	`https://github.com/user/docs.git`	Secondary repository for documentation

Example: Configuring Multiple Git Repositories in Jenkins

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [[name: 'main']],
                    userRemoteConfigs: [
                        [
                            url: 'https://github.com/user/repo1.git'
                        ],
                        [
                            url: 'https://github.com/user/docs.git',
                            name: 'docs'
                        ]
                    ]
                ])
            }
        }
    }
}

Note: Ensure that each SCM source has a unique name to avoid conflicts when checking out multiple repositories.

Warning: Jenkins does not support nested checkout of multiple SCM sources directly in a single stage. Each must be handled separately or managed via custom scripts.

5. Using Git Sparse Checkout

git sparse-checkout allows you to clone only a subset of files from a repository, which is useful in CI/CD environments like Jenkins to reduce clone time and disk usage.

Command	Description	Notes
git sparse-checkout init	Initializes sparse checkout configuration	Must be run before setting patterns
git sparse-checkout set	Defines which files/directories to include	Supports wildcards and directory patterns
git sparse-checkout list	Lists currently configured sparse checkout patterns	Useful for debugging or verifying configuration

Example: Setting up sparse checkout in Jenkins pipeline

git init
git remote add origin https://github.com/example/repo.git
git sparse-checkout init --cone
git sparse-checkout set src/ tests/
git checkout

Note: Sparse checkout is supported in Git 2.25+ and requires the --cone mode for better performance.

Warning: Jenkins pipelines may not support sparse checkout in all environments. Ensure Git version compatibility.

6. Configuring Shallow Clone

Option	Values	Notes
shallow.clone	`true`	Enables shallow clone for faster checkout
shallow.clone.depth	`1`	Depth of the clone (default is 1)

Example: Jenkinsfile Configuration

pipeline {
    agent any
    stages {
        stage('Clone') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [[name: 'main']],
                    extensions: [
                        [$class: 'CloneOption', shallow: true, depth: 1]
                    ],
                    userRemoteConfigs: [[url: 'https://github.com/example/repo.git']]
                ])
            }
        }
    }
}

Note: Shallow clone reduces disk space usage and improves performance for large repositories.

7. Using Git Submodules

Property	Description	Default Value	Notes
submodule.path	Path to the submodule within the repository	None	Required for each submodule
submodule.url	URL to the submodule repository	None	Must be accessible from Jenkins
submodule.branch	Branch to checkout for the submodule	master	Can be any valid branch name

Example: Configuring Git Submodules in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [[name: 'main']],
                    userRemoteConfigs: [
                        [
                            url: 'https://github.com/example/main-repo.git'
                        ]
                    ],
                    extensions: [
                        [$class: 'SubmoduleOption', 
                         disableSubmodules: false,
                         recursiveSubmodules: true,
                         trackingSubmodules: true]
                    ]
                ])
            }
        }
    }
}

Note: Ensure Jenkins has appropriate permissions to access the submodule repositories.

Warning: Submodules must be initialized and updated properly to avoid build failures.

8. Tagging Builds in Git

Property	Value	Description
git.tag.name	`build-${BUILD_NUMBER}`	Name of the Git tag to create
git.tag.message	`Build ${BUILD_NUMBER} tagged`	Message for the Git tag
git.tag.target	`HEAD`	Commit to tag (default: current commit)

Example: Tagging a Build

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }
        stage('Tag Build') {
            steps {
                script {
                    def tagName = "build-${env.BUILD_NUMBER}"
                    def tagMessage = "Build ${env.BUILD_NUMBER} tagged"
                    sh "git tag -a ${tagName} -m '${tagMessage}'"
                    sh "git push origin ${tagName}"
                }
            }
        }
    }
}

Note: Ensure Git credentials are configured in Jenkins for pushing tags to remote repositories.

9. Using Git Flow Branches

Branch Type	Description	Usage in Jenkins	Examples
main	Production-ready code	Triggers deployment pipeline	`main`
develop	Integration branch for features	Used as base for feature branches	`develop`
feature/<feature-name>	Development of new features	Triggers build and test pipelines	`feature/user-authentication`
release/<version>	Preparation for release	Builds and tests release candidate	`release/1.0.0`
hotfix/<issue>	Fixes for production issues	Builds and deploys hotfix	`hotfix/critical-bug-fix`

Example: Jenkins Pipeline for Feature Branches

pipeline {
    agent any
    stages {
        stage('Checkout') {
            steps {
                git branch: 'feature/user-authentication', url: 'https://github.com/example/project.git'
            }
        }
        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }
        stage('Test') {
            steps {
                sh 'npm run test'
            }
        }
    }
}

Note: Ensure Jenkins has appropriate permissions to access Git repositories and branch names follow Git Flow conventions.

Warning: Avoid direct commits to main or develop branches in Jenkins pipelines without proper approval or merge strategies.

10. Handling Git Merge Conflicts

Note: Jenkins integrates with Git through plugins like Git Plugin and GitHub Plugin. Merge conflict resolution typically happens outside of Jenkins, but Jenkins can be configured to notify users or halt builds when conflicts occur.

Scenario	Description	Action in Jenkins
Merge Conflict Detected	Jenkins detects a merge conflict in the Git repository during a build or checkout.	Build fails with error message indicating conflict. Requires manual resolution in Git client or UI.
Build Fails Due to Conflicts	Build process stops when Jenkins attempts to merge branches and finds conflicts.	Jenkins logs the conflict details in build console output. Build status is marked as FAILED.

Example: Build Console Output on Merge Conflict

ERROR: Failed to checkout git repo
Caused by: Path "src/main/java/MyClass.java" has merge conflicts.
Build step &apos;Git Checkout&apos; marked build as failure

Recommended Workflow for Merge Conflicts

Resolve conflicts manually in Git client or web UI (e.g., GitHub, GitLab).
Push resolved changes to the branch.
Re-run Jenkins build to ensure success.

Warning: Jenkins does not automatically resolve Git merge conflicts. It is the responsibility of developers to resolve them before triggering a successful build.

11. Using Git Changelog

Property	Description	Default Value	Notes
git.changelog.includeUnstable	Include unstable changes in changelog	`false`	Set to `true` to include unstable changes
git.changelog.commitFilter	Commit filter regex pattern	`null`	Only commits matching the pattern are included
git.changelog.dateFormat	Date format for changelog entries	`yyyy-MM-dd`	Customizable date format string

Example: Configuring Git Changelog in Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Generate Changelog') {
            steps {
                git changelog: true,
                    commitFilter: '.*fix.*',
                    includeUnstable: false,
                    dateFormat: 'dd/MM/yyyy'
            }
        }
    }
}

Note: The git.changelog option requires the Git plugin to be installed and configured in Jenkins.