Working with Build Triggers

1. Triggering Builds Manually

Trigger Type	Description	Configuration
Manual Trigger	Builds are initiated manually by a user through the Jenkins UI or API.	`Build Triggers` section in job configuration with `Build after other projects are built` or `Trigger builds remotely`.

Example: Manual Build via Jenkins UI

1. Navigate to the job in Jenkins UI.
2. Click on <span class="highlight">Build Now</span> button in the left sidebar.
3. The build will start immediately if no dependencies are blocking it.

Example: Remote Trigger via API

curl -X POST <span class="highlight">http://jenkins-server/job/your-job/build</span> --user <span class="highlight">username:token</span>

Note: The Build Now option is available for all jobs, but remote triggers require enabling the Trigger builds remotely option in the job configuration.

2. Scheduling with Cron Syntax

Jenkins uses a cron-like syntax to schedule builds. The syntax is slightly different from standard Unix cron and includes an additional field for seconds.

Field	Allowed Values	Description
Seconds	`0-59`	Seconds in the minute (0-59)
Minutes	`0-59`	Minutes in the hour (0-59)
Hours	`0-23`	Hours in the day (0-23)
Day of Month	`1-31`	Day of the month (1-31)
Month	`1-12` or `JAN-DEC`	Month (1-12 or JAN-DEC)
Day of Week	`0-7` or `SUN-SAT`	Day of the week (0-7 or SUN-SAT, where 0 and 7 both mean Sunday)

Examples of cron expressions:

Example: Run every minute

* * * * *

Example: Run at 2 AM daily

0 0 2 * * *

Example: Run every Monday at 9 AM

0 0 9 * * 1

Example: Run every 15 minutes

0 */15 * * * *

Note: Jenkins cron syntax supports the 0-59 range for seconds, which is not part of standard Unix cron. The syntax is SECONDS MINUTES HOURS DOM MONTH DOW.

3. Polling SCM for Changes

Property	Values	Description
pollSCM	`true`	Enables polling SCM for changes
scm	`git`, `svn`, `mercurial`	Source control management system to poll
pollingInterval	`5m`, `10m`, `30m`	How often to check for changes (in minutes)

Example: Polling Git Repository

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

Note: The H/5 * * * * syntax uses Jenkins' cron-like scheduler where H represents a hash-based randomization to distribute load across Jenkins nodes.

Warning: Frequent polling can increase load on SCM servers and may cause performance issues. Consider using Webhooks instead for more efficient change detection.

4. Using GitHub Webhooks

Property	Value	Description
GitHub Webhook URL	`https://jenkins.example.com/github-webhook/`	The endpoint Jenkins uses to receive GitHub events
Trigger Type	`Pull Request`	Builds when a pull request is opened or updated
Trigger Type	`Push`	Builds when code is pushed to a branch
Trigger Type	`Comment`	Builds when a comment is added to a pull request or issue

Example: Configure GitHub Webhook in Jenkins

curl -X POST \
  https://jenkins.example.com/job/my-project/buildWithParameters \
  -d "token=github-webhook-token" \
  -H "Content-Type: application/json" \
  -d '{"event": "push", "branch": "main"}'

Note: The webhook URL must be configured in your GitHub repository settings under Settings > Webhooks.

Warning: Ensure that the token parameter matches the one configured in Jenkins to prevent unauthorized builds.

GitHub Webhook Configuration Steps

Navigate to your Jenkins job configuration page
Under Build Triggers, select GitHub hook trigger for GITScm polling
Copy the webhook URL from Jenkins: https://jenkins.example.com/github-webhook/
Go to your GitHub repository settings and add a new webhook
Set the payload URL to the Jenkins webhook endpoint
Set content type to application/json
Save the webhook configuration

5. Using GitLab Webhooks

Jenkins can be configured to trigger builds automatically when changes are pushed to a GitLab repository using webhooks. This allows for continuous integration and deployment workflows.

Configuration	Description	Value
GitLab Plugin	Required plugin to handle GitLab webhooks	`gitlab-branch-source`
Webhook URL	URL to configure in GitLab project settings	`http://jenkins.example.com/project/{project-name}/gitlab-webhook/`
Trigger Events	Events that trigger a build	`Push Events, Merge Request Events`

Example: Configure GitLab Webhook in Jenkins

pipeline {
    agent any
    triggers {
        gitlab(
            projectBranches: [
                [name: 'main'],
                [name: 'develop']
            ],
            triggerOnPush: true,
            triggerOnMergeRequest: true
        )
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: Ensure the GitLab plugin is installed and configured in Jenkins before setting up webhooks.

Warning: The webhook URL must be accessible from GitLab. If Jenkins is behind a firewall or proxy, ensure proper network configuration.

6. Using Bitbucket Webhooks

Property	Value	Description
Bitbucket Webhook URL	`https://jenkins.example.com/bitbucket-webhook/`	Endpoint to receive Bitbucket push events
Trigger on	`Push events`	Builds triggered when code is pushed to Bitbucket repository
Repository	`myorg/myrepo`	Bitbucket repository to monitor

Example: Configure Bitbucket Webhook in Jenkins

curl -X POST https://jenkins.example.com/job/myjob/buildWithParameters \
  -H "Authorization: Bearer <token>" \
  -d "bitbucket_payload={"push": {"changes": [{"new": {"name": "main"}}]}}"

Note: Ensure the Jenkins Bitbucket Plugin is installed and configured to handle webhook events.

Warning: Bitbucket webhooks must be secured with a secret token to prevent unauthorized builds.

7. Triggering After Other Jobs

Trigger	Description	Configuration	Notes
Build after other builds	Triggers a build when another job completes successfully or fails.	`Upstream project names`: comma-separated list of jobs `Build when upstream project is built`: true/false `Build when upstream project fails`: true/false	Supports parameterized upstream jobs Can be configured to trigger on specific build results
Build after other builds (with parameters)	Triggers a build when another job completes and passes parameters to the downstream job.	`Upstream project names`: comma-separated list of jobs `Parameters to pass`: parameter mapping `Build when upstream project is built`: true/false	Parameters can be passed dynamically using `$BUILD_NUMBER`, `$BUILD_ID`, etc.

Example: Build after other builds

pipeline {
    agent any
    triggers {
        upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS)
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The upstream trigger requires the Build Authorization plugin or appropriate permissions to access upstream jobs.

Warning: Circular dependencies between jobs can cause infinite loops. Ensure job dependencies are properly configured.

8. Using Remote Build Triggers

Trigger	Description	Configuration	Notes
Build Triggers	Triggers builds based on external requests	`remoteBuildTrigger`	Requires `build-token-root` plugin

Example: Configuring Remote Build Trigger

pipeline {
    agent any
    triggers {
        remoteTrigger(
            token: 'build-token',
            cause: 'Remote build trigger'
        )
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The remote trigger requires the build-token-root plugin to be installed and configured.

Warning: Ensure proper authentication and authorization to prevent unauthorized builds.

9. Triggering on Pull Requests

Trigger	Description	Configuration	Notes
GitHub Pull Request Trigger	Triggers a build when a pull request is created, updated, or merged.	`github-pr-trigger`	Requires GitHub plugin installed.
Bitbucket Pull Request Trigger	Triggers a build on Bitbucket pull request events.	`bitbucket-pr-trigger`	Requires Bitbucket plugin installed.

Example: GitHub PR Trigger Configuration

pipeline {
    agent any
    triggers {
        upstream(upstreamProjects: 'parent-job', threshold: hudson.model.Result.SUCCESS)
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The github-pr-trigger requires the Jenkins GitHub plugin to be installed and configured.

Warning: Pull request triggers can lead to high build frequency; consider using scmTrigger for less frequent builds.

Summary of PR Triggers

Triggers on creation, update, or merge of a pull request.
Supports GitHub and Bitbucket integrations.
Can be configured to build only on specific events (e.g., PR creation or merge).

10. Using Pipeline Triggers

Pipeline triggers in Jenkins allow you to define when a build should be initiated based on specific conditions or events. These triggers are particularly useful in continuous integration and deployment workflows.

Trigger	Description	Configuration Example	Notes
upstream	Triggers the build when a specified upstream project completes successfully.	`upstream(upstreamProjectName: 'upstream-job', threshold: 'SUCCESS')`	Useful for chaining builds in a dependency tree.
pollSCM	Triggers the build by polling the source code management system for changes.	`pollSCM('H/5 * * * *')`	Requires SCM to be configured. Polling interval is specified in cron format.
githubPush	Triggers the build when a push event occurs in a GitHub repository.	`githubPush()`	Requires the GitHub plugin to be installed.
webhook	Triggers the build via a webhook call to Jenkins.	`webhook()`	Can be configured to trigger on specific events or payloads.
cron	Triggers the build at a specific time based on cron syntax.	`triggers { cron('H 0 * * *') }`	Useful for scheduled builds or nightly jobs.

Example: GitHub Push Trigger Configuration

pipeline {
    agent any
    triggers {
        githubPush()
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Example: Polling SCM Trigger

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