Poll SCM configuration in Jenkins - Commands & Configuration

Introduction

Sometimes you want Jenkins to check your code repository regularly to see if there are any changes. Poll SCM configuration lets Jenkins look for updates on a schedule and start a build only when there is new code. This saves time and resources by not building when nothing changed.

When you want Jenkins to automatically build your project only if new code is pushed to the repository.

When you do not have webhooks set up to notify Jenkins about code changes.

When you want to reduce unnecessary builds and save server resources.

When your team commits code at irregular times and you want Jenkins to check periodically.

When you want a simple way to trigger builds without complex event setups.

Commands

This command downloads the current configuration of the Jenkins job named 'example-job' to a file called job-config.xml so you can edit it.

Terminal

jenkins-cli get-job example-job > job-config.xml

Expected Output

<?xml version="1.0" encoding="UTF-8"?>

<project>

  ...

</project>

This command adds the Poll SCM trigger to the job configuration XML, setting Jenkins to check the source code every 5 minutes.

Terminal

sed -i '/<triggers>/a\    <hudson.triggers.SCMTrigger>\n      <spec>H/5 * * * *</spec>\n    </hudson.triggers.SCMTrigger>' job-config.xml

Expected Output

No output (command runs silently)

This command uploads the modified job configuration back to Jenkins, applying the Poll SCM schedule to the job.

Terminal

jenkins-cli update-job example-job < job-config.xml

Expected Output

No output (command runs silently)

This command verifies that the Poll SCM trigger was added by showing the triggers section of the job configuration.

Terminal

jenkins-cli get-job example-job | grep -A 3 '<triggers>'

Expected Output

  <triggers>

    <hudson.triggers.SCMTrigger>

      <spec>H/5 * * * *</spec>

    </hudson.triggers.SCMTrigger>

Key Concept

If you remember nothing else from this pattern, remember: Poll SCM lets Jenkins check your code repository on a schedule and build only when there are changes.

Common Mistakes

Setting the Poll SCM schedule to an invalid cron syntax.

Jenkins will reject the configuration or ignore the trigger, so builds won't start as expected.

Use valid cron syntax like 'H/5 * * * *' to schedule polling every 5 minutes.

Forgetting to update the job configuration after editing the XML file.

Changes won't take effect, so Jenkins will not poll the SCM.

Always upload the modified job configuration back to Jenkins using the update-job command.

Using Poll SCM and webhooks together without understanding their interaction.

This can cause duplicate builds or unexpected triggers.

Choose either Poll SCM or webhooks to trigger builds to avoid conflicts.

Summary

Use Jenkins CLI to download the job configuration XML file.

Add the Poll SCM trigger with a valid cron schedule inside the triggers section.

Upload the updated configuration back to Jenkins to apply the changes.

Verify the Poll SCM trigger is set by inspecting the job configuration.