What does the pollSCM trigger refer to in this Jenkinsfile?

Question

Consider the following setup using Jenkins 2.176.1:

• A new pipeline project named Foobar
• Poll SCM as (only) build trigger, with: H/5 * * * * ... under the assumption that this refers to the SCM configured in the next step
• Pipeline script from SCM with SCM Git and a working Git repository URL
  • Uncheck Lightweight checkout because of JENKINS-42971 and JENKINS-48431 (I am using build variables in the real project and Jenkinsfile; also this may affect how pollSCM works, so I include this step here)
• Said repository contains a simple Jenkinsfile

The Jenkinsfile looks approximately like this:

#!groovy
pipeline {
    agent any
    triggers { pollSCM 'H/5 * * * *' }
    stages {
        stage('Source checkout') {
            steps {
                checkout(
                    [
                        $class: 'GitSCM',
                        branches: [],
                        browser: [],
                        doGenerateSubmoduleConfigurations: false,
                        extensions: [],
                        submoduleCfg: [],
                        userRemoteConfigs: [
                            [
                                url: 'git://server/project.git'
                            ]
                        ]
                    ]
                )
                stash 'source'
            }
        }
        stage('OS-specific binaries') {
            parallel {
                stage('Linux') {
                    agent { label 'gcc && linux' }
                    steps {
                        unstash 'source'
                        echo 'Pretending to do a build here'
                    }
                }
                stage('Windows') {
                    agent { label 'windows' }
                    steps {
                        unstash 'source'
                        echo 'Pretending to do a build here'
                    }
                }
            }
        }
    }
}

My understanding so far was that:

1. a change to the Jenkinsfile (not the whole repo) triggers the pipeline on any registered agent (or as configured in the pipeline project).
2. said agent (which is random) uses the pollSCM trigger in the Jenkinsfile to trigger the pipeline stages.
   • But where does the pollSCM trigger poll (what SCM repo)? And if it's a random agent then how can it reasonably detect changes across poll runs?
3. then the stages are being executed on the agents as allocated ...

Now I am confused what refers to what. So here my questions (all interrelated which is why I keep it together in one question):

• The pipeline project polls the SCM just for the Jenkinsfile or for any changes? The repository in my case is the same (for Jenkinsfile and source files to build binaries from).
  • If the (project-level) polling triggers at any change rather than changes to the Jenkinsfile
• Does the pollSCM trigger in the Jenkinsfile somehow automagically refer to the checkout step?
  • Then ... what would happen, would I have multiple checkout steps with differing settings?
  • What determines what repository (and what contents inside of that) gets polled?
• ... or is this akin to the checkout scm shorthand and pollSCM actually refers to the SCM configured in the pipeline project and so I can shorten the checkout() to checkout scm in the steps?

Unfortunately the user handbook didn't answer any of those questions and pollSCM has a total of four occurrences on a single page within the entire handbook.

Answer 1

I'll take a crack at this one:

The pipeline project polls the SCM just for the Jenkinsfile or for any changes? The repository in my case is the same (for Jenkinsfile and source files to build binaries from).

The pipeline project will poll the repo for ANY file changes, not just the Jenkinsfile. A Jenkinsfile in the source repo is common practice.

If the (project-level) polling triggers at any change rather than changes to the Jenkinsfile Does the pollSCM trigger in the Jenkinsfile somehow automagically refer to the checkout step?

Your pipeline will be executed when a change to the repo is seen, and the steps are run in the order that they appear in your Jenkinsfile.

Then ... what would happen, would I have multiple checkout steps with differing settings?

If you defined multiple repos with the checkout step (using multiple checkout SCM calls) then the main pipeline project repo would be polled for any changes and the repos you define in the pipeline would be checked out regardless of whether they changed or not.

What determines what repository (and what contents inside of that) gets polled? ... or is this akin to the checkout scm shorthand and pollSCM actually refers to the SCM configured in the pipeline project and so I can shorten the checkout() to checkout scm in the steps?

pollSCM refers to the pipeline project's repo. The entire repo is cloned unless the project is otherwise configured (shallow clone, lightweight checkout, etc.).