Working with Organization Folders

1. Creating Organization Folders

Organization folders in Jenkins allow you to group multiple repositories under a single organizational structure, simplifying management and configuration for teams working with multiple projects.

Property	Description	Default Value
name	Name of the organization folder	Empty string
organization	Organization name (e.g., company or team)	None
repositories	List of repositories to include in the organization folder	Empty list

Example: Creating an Organization Folder via Jenkins UI

1. Navigate to Jenkins Dashboard
2. Click "New Item"
3. Enter a name for the organization folder (e.g., "MyTeam-Projects")
4. Select "Organization Folder"
5. Click "OK"
6. Configure the organization details and repository sources

Example: Configuring Repository Sources in Organization Folder

organization {
  name = "MyTeam"
  repositories = [
    "myteam/project1",
    "myteam/project2"
  ]
}

2. Configuring GitHub Organization Sources

Property	Value	Description
github.organization	`myorg`	Name of the GitHub organization to scan
github.credentials	`github-token`	Credentials ID for GitHub API access
github.webhook	`true`	Enable webhook for real-time updates
github.filter	`.*`	Regex filter for repository names

Example: GitHub Organization Configuration

organizationFolder('myorg') {
    organizations {
        githubOrganization {
            name('myorg')
            credentialsId('github-token')
            webhook(true)
            repositoryFilter('.*')
        }
    }
}

Note: Ensure the Jenkins user has appropriate permissions to read repositories in the specified GitHub organization.

3. Configuring GitLab Group Sources

Property	Value	Description
gitlab.url	`https://gitlab.example.com`	URL of the GitLab instance
gitlab.credentialsId	`gitlab-credentials`	Credentials ID for accessing GitLab
gitlab.groupName	`my-organization`	Name of the GitLab group to scan
gitlab.includeSubgroups	`true`	Whether to include subgroups in the scan
gitlab.projectFilter	`.-jenkins.`	Regex pattern to filter projects

Example: GitLab Group Source Configuration

organizationFolder('my-organization') {
    organizations {
        gitlabOrganization {
            name('my-organization')
            credentialsId('gitlab-credentials')
            gitlabUrl('https://gitlab.example.com')
            projectFilter('.*-jenkins.*')
            includeSubgroups(true)
        }
    }
}

Note: Ensure the Jenkins user has appropriate permissions in GitLab to read project information and trigger builds.

4. Configuring Bitbucket Team Sources

Property	Value	Description
bitbucketTeamName	`"myteam"`	Name of the Bitbucket team
bitbucketProjectKey	`"PROJ"`	Project key in Bitbucket
bitbucketRepositoryName	`"my-repo"`	Repository name in Bitbucket
bitbucketBranchFilter	`"main"`	Branch filter pattern (e.g., `main`, `feature/*`)
bitbucketWebhookUrl	`"https://jenkins.example.com/bitbucket-webhook/"`	URL for Bitbucket webhook configuration

Example: Bitbucket Team Source Configuration

organizationFolder('my-organization') {
    organizations {
        bitbucketOrganization {
            name 'myteam'
            credentialsId 'bitbucket-credentials'
            repositories {
                repository('my-repo') {
                    branchFilter('main')
                }
            }
        }
    }
}

Note: Ensure that the Jenkins user has appropriate permissions in Bitbucket to read repositories and configure webhooks.

Warning: Webhook URL must be accessible from Bitbucket; ensure Jenkins is not behind a firewall or proxy without proper configuration.

5. Setting Repository Discovery Strategies

Strategy	Description	Configuration	Notes
SCM Repository	Discovers repositories from a specified SCM source, such as Git or SVN.	`scm` block in Jenkinsfile or configuration	Supports multiple SCM types; requires proper credentials setup
Webhook Trigger	Triggers repository discovery via webhook events from SCM providers.	`triggers` with `pollSCM` or `upstream`	Requires SCM provider to support webhooks (e.g., GitHub, GitLab)
Manual Discovery	Manually define repositories to be discovered and managed.	Defined in Jenkins UI under Organization Folder settings	Useful for testing or when automatic discovery is not desired

Example: Configuring SCM Repository Discovery

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

Note: Repository discovery strategies can be combined with other Jenkins features like multibranch pipelines to automate CI/CD workflows.

6. Filtering Repositories by Name

Filtering repositories by name in Jenkins Organization Folders allows you to control which Git repositories are scanned and built automatically. This is useful for organizing projects or excluding specific repositories from the build process.

Filter Type	Description	Configuration
Include	Only scan repositories matching the specified pattern.	`include` field in the configuration
Exclude	Do not scan repositories matching the specified pattern.	`exclude` field in the configuration

Example: Include repositories matching a pattern

organizationFolder('my-organization') {
    repositories {
        git {
            name 'origin'
            url 'https://github.com/myorg/'
            includes {
                pattern 'feature-*'
            }
        }
    }
}

Example: Exclude repositories matching a pattern

organizationFolder('my-organization') {
    repositories {
        git {
            name 'origin'
            url 'https://github.com/myorg/'
            excludes {
                pattern 'test-*'
            }
        }
    }
}

Note: The includes and excludes filters support glob patterns. For example, feature-* matches any repository starting with feature-.

Warning: If both includes and excludes are specified, excludes takes precedence and will filter out repositories even if they match an include pattern.

7. Configuring Branch Discovery

Option	Values	Description
Branch Discovery	`SCM`	Discovers branches from SCM (e.g., Git)
Branch Discovery	`Trunk/Tag`	Discovers branches from trunk or tag structure
Branch Discovery	`Branch and Tag`	Discovers both branches and tags from SCM

Example: Configure Branch Discovery in Jenkinsfile

pipeline {
    agent any
    triggers {
        pollSCM 'H/5 * * * *'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The pollSCM trigger enables Jenkins to periodically check for changes in the SCM repository.

Warning: Frequent polling can increase load on the SCM server and Jenkins.

8. Using Periodic Scan Triggers

Periodic scan triggers in Jenkins allow you to schedule when Jenkins should check for changes in your source control repository. This is useful for ensuring that builds are triggered at regular intervals, even if no changes have been committed.

Trigger	Description	Syntax	Notes
SCM polling	Triggers a build when changes are detected in the SCM repository.	`SCMTrigger`	Can be configured to scan at regular intervals.
Scheduled builds	Triggers a build at specific times or intervals using cron-like syntax.	`SCMTrigger`	Useful for nightly builds or periodic checks.

Example: Configure Scheduled Build

triggers {
    upstream()
    scm('H H(0-5) * * *')
}

Note: The cron-like syntax for scheduling builds is based on the Jenkins SCMTrigger and supports standard cron expressions. For example, H H(0-5) * * * means "run every hour between 0 and 5 AM daily".

Example: Using Cron Expression for Weekly Builds

triggers {
    scm('0 0 * * 0')
}

Note: The cron expression 0 0 * * 0 schedules a build every Sunday at midnight. This is useful for weekly builds or maintenance tasks.

Summary of Periodic Scan Triggers

SCM polling: Checks for changes in the repository at specified intervals.
Scheduled builds: Uses cron-like syntax to schedule builds at specific times.
Configuration: Can be defined in the Jenkinsfile or via the UI.

9. Managing Folder-Level Properties

Property	Values	Description
folder.name	`string`	Name of the folder in Jenkins UI
folder.description	`string`	Optional description for the folder
folder.displayName	`string`	Display name used in UI (can differ from name)
folder.inheritFromParent	`boolean`	If true, inherits configuration from parent folder
folder.disabled	`boolean`	Disables the folder and all its jobs if set to true

Example: Setting Folder Properties via Jenkinsfile

pipeline {
    agent any
    environment {
        FOLDER_NAME = 'my-organization'
    }
    stages {
        stage('Setup') {
            steps {
                script {
                    def folder = Jenkins.instance.getFolder(FOLDER_NAME)
                    folder.setDescription("Organization folder for my project")
                    folder.setDisplayName("My Organization Folder")
                    folder.save()
                }
            }
        }
    }
}

Note: Folder properties can also be managed through the Jenkins UI under Manage Jenkins > Configure System or via the REST API.

10. Implementing Shared Jenkinsfile Strategies

Example: Shared Library Usage in Jenkinsfile

pipeline {
    agent any
    environment {
        SHARED_LIB_VERSION = '1.0'
    }
    stages {
        stage('Build') {
            steps {
                script {
                    // Using a shared library function
                    def buildResult = callSharedBuild(
                        project: 'my-project',
                        version: env.BUILD_NUMBER
                    )
                    echo "Build result: ${buildResult}"
                }
            }
        }
    }
}

Strategy	Description	Usage
Pipeline Shared Libraries	Reusable Jenkins pipeline code stored in a Git repository	Define shared functions, steps, and variables across multiple pipelines
Global Shared Libraries	Libraries available to all jobs in the Jenkins instance	Use `library` directive to load and use shared code
Job-specific Libraries	Libraries specific to a single job or project	Use `library` directive with `optional: true` to avoid breaking builds

Note: Shared libraries must be defined in Jenkins configuration under Manage Jenkins > Configure System > Global Tool Configuration.

Example: Defining a Shared Library in Jenkins Configuration

libraries {
    library(
        name: 'my-shared-lib',
        version: '1.0',
        defaultStash: true
    )
}

Benefits of Shared Jenkinsfile Strategies

Reduces code duplication across multiple pipelines
Enables consistent CI/CD practices across teams
Improves maintainability by centralizing pipeline logic
Supports versioning and rollback of shared code