SCM

The SCM module allows you to specify the source code location for the project. It adds the scm attribute to the Job definition, which accepts any number of scm definitions. It is also possible to pass [] to the scm attribute. This is useful when a set of configs has a global default scm and you want to a particular job to override that default with no SCM.

Component: scm
Macro:scm
Entry Point:jenkins_jobs.scm

The scm module allows referencing multiple repositories in a Jenkins job. Note: Adding more than one scm definition requires the Jenkins Multiple SCMs plugin.

Example of multiple repositories in a single job:
- scm:
    name: first-scm
    scm:
      - git:
         url: ssh://jenkins@review.openstack.org:29418/first.git
         branches:
          - origin/master

- scm:
    name: second-scm
    scm:
      - git:
         url: ssh://jenkins@review.openstack.org:29418/second.git
         branches:
          - origin/master

- scm:
    name: first-and-second
    scm:
      - first-scm
      - second-scm

- job:
    name: my-job
    scm:
      - first-and-second
Example of an empty scm:
scm: []
bzr

Specifies the bzr SCM repository for this job. Requires the Jenkins Bazaar Plugin.

Parameters:
  • url (str) – URL of the bzr branch (required)
  • clean-tree (bool) – Clean up the workspace (using bzr) before pulling the branch (default false)
  • lightweight-checkout (bool) – Use a lightweight checkout instead of a full branch (default false)
  • browser (str) –

    The repository browser to use.

    browsers supported:
     
  • browser-url (str) – URL for the repository browser (required if browser is set).
  • opengrok-root-module (str) – Root module for OpenGrok (required if browser is opengrok).

Example:

scm:
  - bzr:
      url: lp:test_project
cvs

Specifies the CVS SCM repository for this job. Requires the Jenkins CVS Plugin.

Parameters:
  • repos (list) –

    List of CVS repositories. (required)

    Repos:
    • root (str) – The CVS connection string Jenkins uses to connect to the server. The format is :protocol:user@host:path (required)
    • locations (list) – List of locations. (required)
      Locations:
      • type (str) – Type of location.
        supported values:
         
        • HEAD - (default)
        • BRANCH
        • TAG
      • name (str) – Name of location. Only valid in case of ‘BRANCH’ or ‘TAG’ location type. (default ‘’)
      • use-head (bool) – Use Head if not found. Only valid in case of ‘BRANCH’ or ‘TAG’ location type. (default false)
      • modules (list) – List of modules. (required)
        Modules:
        • remote – The name of the module in the repository at CVSROOT. (required)
        • local-name – The name to be applied to this module in the local workspace. If blank, the remote module name will be used. (default ‘’)
    • excluded-regions (list str) – Patterns for excluding regions. (optional)
    • compression-level (int) – Compression level. Must be a number between -1 and 9 inclusive. Choose -1 for System Default. (default -1)
  • use-update (bool) – If true, Jenkins will use ‘cvs update’ whenever possible for builds. This makes a build faster. But this also causes the artifacts from the previous build to remain in the file system when a new build starts, making it not a true clean build. (default true)
  • prune-empty (bool) – Remove empty directories after checkout using the CVS ‘-P’ option. (default true)
  • skip-changelog (bool) – Prevent the changelog being generated after checkout has completed. (default false)
  • show-all-output (bool) – Instructs CVS to show all logging output. CVS normally runs in quiet mode but this option disables that. (default false)
  • clean-checkout (bool) – Perform clean checkout on failed update. (default false)
  • clean-copy (bool) – Force clean copy for locally modified files. (default false)

Example

scm:
  - cvs:
      repos:
          - root: ":protocol:user@host1:path"
            locations:
                - modules:
                    - remote: "remote1"
                    - remote: "remote2"
          - root: ":protocol:user@host2:path"
            locations:
                - modules:
                    - remote: "remote1"

scm:
  - cvs:
      repos:
          - root: ":protocol:user@host1:path"
            locations:
                - type: TAG
                  name: "tag name"
                  use-head: false
                  modules:
                    - remote: "remote1"
                      local-name: "localName"
                    - remote: "remote2"
            excluded-regions:
                - "pattern1"
                - "pattern2"
            compression-level: "1"
          - root: ":protocol:user@host2:path"
            locations:
                - modules:
                    - remote: "remote1"
      use-update: false
      prune-empty: false
      skip-changelog: true
      show-all-output: true
      clean-checkout: true
      clean-copy: true
dimensions

Specifies the Dimensions SCM repository for this job. Requires Jenkins Dimensions Plugin.

Parameters:
  • project (str) – Project name of format PRODUCT_ID:PROJECT_NAME (required)
  • permissions (str) –

    Default Permissions for updated files (default: DEFAULT)

    Permissions:
    • DEFAULT
    • READONLY
    • WRITABLE
  • eol (str) –

    End of line (default: DEFAULT)

    End of line:
    • DEFAULT
    • UNIX
    • WINDOWS
    • UNCHANGED
  • folders (list) – Folders to monitor (default /)
  • exclude (list) – Paths to exclude from monitor
  • username (str) – Repository username for this job
  • password (str) – Repository password for this job
  • server (str) – Dimensions server for this job
  • database (str) – Dimensions database for this job. Format must be database@dsn
  • update (bool) – Use update (default false)
  • clear-workspace (bool) – Clear workspace prior to build (default false)
  • force-build (bool) – Force build even if the repository SCM checkout operation fails (default false)
  • overwrite-modified (bool) – Overwrite files in worspace from repository files (default false)
  • expand-vars (bool) – Expand substitution variables (default false)
  • no-metadata (bool) – Checkout files with no metadata (default false)
  • maintain-timestamp (bool) – Maintain file timestamp from Dimensions (default false)
  • slave-checkout (bool) – Force slave based checkout (default false)
  • timezone (str) – Server timezone
  • web-url (str) – Dimensions Web URL

Examples:

scm:
  - dimensions:
      project: myProduct:myProject

scm:
  - dimensions:
      project: myProduct:myProject
      permissions: WRITABLE
      eol: UNIX
      folders:
        - src
        - test
      exclude:
        - excluded_dir
        - excluded_other_dir
      username: johnd
      password: passw0rd
      server: my.dmscm.server:1234
      database: myDatabase@myDsn
      update: true
      clear-workspace: true
      force-build: true
      overwrite-modified: true
      expand-vars: true
      no-metadata: true
      maintain-timestamp: true
      slave-checkout: true
      timezone: Europe/Berlin
      web-url: https://my.dmscm.weburl
git

Specifies the git SCM repository for this job. Requires the Jenkins Git Plugin.

Parameters:
  • url (str) – URL of the git repository
  • credentials-id (str) – ID of credential to use to connect, which is the last field (a 32-digit hexadecimal code) of the path of URL visible after you clicked the credential under Jenkins Global credentials. (optional)
  • refspec (str) – refspec to fetch (default ‘+refs/heads/*:refs/remotes/remoteName/*’)
  • name (str) – name to fetch (default ‘origin’)
  • remotes (list(str)) –

    list of remotes to set up (optional, only needed if multiple remotes need to be set up)

    Remote:
    • url (string) - url of remote repo
    • refspec (string) - refspec to fetch (optional)
    • credentials-id - ID of credential to use to connect, which is the last field of the path of URL (a 32-digit hexadecimal code) visible after you clicked credential under Jenkins Global credentials. (optional)
  • branches (list(str)) – list of branch specifiers to build (default ‘**’)
  • skip-tag (bool) –

    Skip tagging (default true)

    Deprecated since version 1.6.0.: Please use per-build-tag extension, which has the inverse meaning.

  • clean (bool) –

    Clean after checkout (default false)

    Deprecated since version 1.1.1.: Please use clean extension format.

  • fastpoll (bool) – Use fast remote polling (default false)
  • disable-submodules (bool) –

    Disable submodules (default false)

    Deprecated since version 1.1.1.: Please use submodule extension.

  • recursive-submodules (bool) –

    Recursively update submodules (default false)

    Deprecated since version 1.1.1.: Please use submodule extension.

  • git-tool (str) – The name of the Git installation to use (default ‘Default’)
  • reference-repo (str) – Path of the reference repo to use during clone (optional)
  • browser (str) –

    what repository browser to use.

    browsers supported:
     
  • browser-url (str) – url for the repository browser (required if browser is not ‘auto’, no default)
  • browser-version (str) – version of the repository browser (GitLab only, default ‘0.0’)
  • project-name (str) – project name in Gitblit and ViewGit repobrowser (optional)
  • repo-name (str) – repository name in phabricator repobrowser (optional)
  • git-config-name (str) – Configure name for Git clone (optional)
  • git-config-email (str) – Configure email for Git clone (optional)
Extensions:
  • basedir (string) - Location relative to the workspace root to
    clone to (default workspace)
  • changelog-against (dict)
    • remote (string) - name of repo that contains branch to create changelog against (default ‘origin’)
    • branch (string) - name of the branch to create changelog against (default ‘master’)
  • choosing-strategy: (string) - Jenkins class for selecting what
    to build. Can be one of default,`inverse`, or gerrit (default ‘default’)
  • clean (dict)
    • after (bool) - Clean the workspace after checkout
    • before (bool) - Clean the workspace before checkout
  • excluded-users: (list(string)) - list of users to ignore
    revisions from when polling for changes. (if polling is enabled, optional)
  • included-regions: (list(string)) - list of file/folders to
    include (optional)
  • excluded-regions: (list(string)) - list of file/folders to
    exclude (optional)
  • ignore-commits-with-messages (list(str)) - Revisions committed
    with messages matching these patterns will be ignored. (optional)
  • ignore-notify: (bool) - Ignore notifyCommit URL accesses
    (default false)
  • force-polling-using-workspace (bool) - Force polling using
    workspace (default false)
  • local-branch (string) - Checkout/merge to local branch
    (optional)
  • merge (dict)
    • remote (string) - name of repo that contains branch to merge to (default ‘origin’)
    • branch (string) - name of the branch to merge to
    • strategy (string) - merge strategy. Can be one of ‘default’, ‘resolve’, ‘recursive’, ‘octopus’, ‘ours’, ‘subtree’. (default ‘default’)
    • fast-forward-mode (string) - merge fast-forward mode. Can be one of ‘FF’, ‘FF_ONLY’ or ‘NO_FF’. (default ‘FF’)
  • per-build-tag (bool) - Create a tag in the workspace for every
    build. (default is inverse of skip-tag if set, otherwise false)
  • prune (bool) - Prune remote branches (default false)
  • scm-name (string) - The unique scm name for this Git SCM
    (optional)
  • shallow-clone (bool) - Perform shallow clone (default false)
  • do-not-fetch-tags (bool) - Perform a clone without tags
    (default false)
  • sparse-checkout (dict)
    • paths (list) - List of paths to sparse checkout. (optional)
  • submodule (dict)
    • disable (bool) - By disabling support for submodules you can still keep using basic git plugin functionality and just have Jenkins to ignore submodules completely as if they didn’t exist.
    • recursive (bool) - Retrieve all submodules recursively (uses ‘–recursive’ option which requires git>=1.6.5)
    • tracking (bool) - Retrieve the tip of the configured branch in .gitmodules (Uses ‘–remote’ option which requires git>=1.8.2)
    • parent-credentials (bool) - Use credentials from default remote of parent repository (default false).
    • reference-repo (str) - Path of the reference repo to use during clone (optional)
    • timeout (int) - Specify a timeout (in minutes) for submodules operations (default 10).
  • timeout (str) - Timeout for git commands in minutes (optional)
  • use-author (bool): Use author rather than committer in Jenkin’s
    build changeset (default false)
  • wipe-workspace (bool) - Wipe out workspace before build
    (default true)

Example:

scm:
  - git:
      url: https://example.com/project.git
      branches:
        - master
        - stable
      browser: githubweb
      browser-url: http://github.com/foo/example.git
      timeout: 20
hg

Specifies the mercurial SCM repository for this job. Requires the Jenkins Mercurial Plugin.

Parameters:
  • url (str) – URL of the hg repository
  • credentials-id (str) – ID of credentials to use to connect (optional)
  • revision-type (str) – revision type to use (default ‘branch’)
  • revision (str) – the branch or tag name you would like to track (default ‘default’)
  • modules (list(str)) – reduce unnecessary builds by specifying a list of “modules” within the repository. A module is a directory name within the repository that this project lives in. (default ‘’)
  • clean (bool) – wipe any local modifications or untracked files in the repository checkout (default false)
  • subdir (str) – check out the Mercurial repository into this subdirectory of the job’s workspace (optional)
  • disable-changelog (bool) – do not calculate the Mercurial changelog for each build (default false)
  • browser (str) –

    what repository browser to use

    browsers supported:
     
  • browser-url (str) – url for the repository browser (required if browser is set)

Example:

scm:
  - hg:
     revision: feature
     url: ssh://hg@hg/repo
     credentials-id: "abcdef01234567890"
     modules:
       - module1
       - module2
     clean: true
     subdir: my/sources
     disable-changelog: true
     browser: hgweb
     browser-url: http://hg/repo
openshift-img-streams

Rather than a Build step extension plugin, this is an extension of the Jenkins SCM plugin, where this baked-in polling mechanism provided by Jenkins is leveraged by exposing some of the common semantics between OpenShift ImageStreams (which are abstractions of Docker repositories) and SCMs - versions / commit IDs of related artifacts (images vs. programmatics files) Requires the Jenkins OpenShift Pipeline Plugin._

Parameters:
  • image-stream-name (str) – The name of the ImageStream is what shows up in the NAME column if you dump all the ImageStream’s with the oc get is command invocation. (default nodejs-010-centos7)
  • tag (str) – The specific image tag within the ImageStream to monitor. (default latest)
  • api-url (str) – This would be the value you specify if you leverage the –server option on the OpenShift oc command. (default https://openshift.default.svc.cluster.local)
  • namespace (str) – The value here should be whatever was the output form oc project when you created the BuildConfig you want to run a Build on. (default test)
  • auth-token (str) – The value here is what you supply with the –token option when invoking the OpenShift oc command. (default ‘’)
  • verbose (bool) – This flag is the toggle for turning on or off detailed logging in this plug-in. (default false)

Full Example:

scm:
  - openshift-img-streams:
      image-stream-name: nodejs-010-fedora
      tag: prod
      api-url: https://openshift.example.local.url/
      namespace: test-scm
      auth-token: ose-key-img-streams1
      verbose: true

Minimal Example:

scm:
  - openshift-img-streams
repo

Specifies the repo SCM repository for this job. Requires the Jenkins Repo Plugin.

Parameters:
  • manifest-url (str) – URL of the repo manifest (required)
  • manifest-branch (str) – The branch of the manifest to use (optional)
  • manifest-file (str) – Initial manifest file to use when initialising (optional)
  • manifest-group (str) – Only retrieve those projects in the manifest tagged with the provided group name (optional)
  • ignore-projects (list(str)) – a list of projects in which changes would not be considered to trigger a build when pooling (optional)
  • destination-dir (str) – Location relative to the workspace root to clone under (optional)
  • repo-url (str) – custom url to retrieve the repo application (optional)
  • mirror-dir (str) – Path to mirror directory to reference when initialising (optional)
  • jobs (int) – Number of projects to fetch simultaneously (default 0)
  • depth (int) – Specify the depth in history to sync from the source. The default is to sync all of the history. Use 1 to just sync the most recent commit (default 0)
  • current-branch (bool) – Fetch only the current branch from the server (default true)
  • reset-first (bool) – Remove any commits that are not on the repositories by running the following command before anything else (default false): repo forall -c "git reset --hard"
  • quiet (bool) – Make repo more quiet (default true)
  • force-sync (bool) – Continue sync even if a project fails to sync (default false)
  • no-tags (bool) – Don’t fetch tags (default false)
  • trace (bool) – Trace git command execution into the build logs. (default false)
  • show-all-changes (bool) – When this is checked –first-parent is no longer passed to git log when determining changesets (default false)
  • local-manifest (str) – Contents of .repo/local_manifest.xml, written prior to calling sync (optional)

Example:

scm:
  - repo:
      manifest-url: https://example.com/project/
      manifest-branch: stable
      manifest-file: repo.xml
      manifest-group: drivers
      ignore-projects:
        - static-project
        - unimportant-project
      destination-dir: build
      repo-url: https://internal.net/projects/repo
      mirror-dir: ~/git/project/
      jobs: 3
      current-branch: false
      reset-first: true
      quiet: false
      force-sync: true
      no-tags: true
      trace: true
      show-all-changes: true
      local-manifest: |
        <?xml version="1.0" encoding="UTF-8"?>
        <manifest>
          <project path="external/project" name="org/project"
            remote="gerrit" revision="master" />
        </manifest>
store

Specifies the Visualworks Smalltalk Store repository for this job. Requires the Jenkins Visualworks Smalltalk Store Plugin.

Parameters:
  • script (str) – name of the Store script to run
  • repository (str) – name of the Store repository
  • version-regex (str) – regular expression that specifies which pundle versions should be considered (optional)
  • minimum-blessing (str) – minimum blessing level to consider (optional)
  • parcel-builder-file (str) – name of the file to generate as input to a later parcel building step (optional - if not specified, then no parcel builder file will be generated)
  • pundles (list) –
    (package or bundle):
     (dict): A package or bundle to check

Example:

scm:
  - store:
      script: someStoreScript
      repository: StoreRepository
      version-regex: "[0-9]+"
      minimum-blessing: Integrated
      parcel-builder-file: parcelBuilderInput
      pundles:
        - package: SomePackage
        - package: AnotherPackage
        - bundle: SomeBundle
svn

Specifies the svn SCM repository for this job.

Parameters:
  • url (str) – URL of the svn repository
  • basedir (str) – location relative to the workspace root to checkout to (default ‘.’)
  • credentials-id (str) – optional argument to specify the ID of credentials to use
  • repo-depth (str) – Repository depth. Can be one of ‘infinity’, ‘empty’, ‘files’, ‘immediates’ or ‘unknown’. (default ‘infinity’)
  • ignore-externals (bool) – Ignore Externals. (default false)
  • workspaceupdater (str) – optional argument to specify
  • workspaceupdater –

    optional argument to specify how to update the workspace (default wipeworkspace)

    supported values:
     
    • wipeworkspace - deletes the workspace before checking out
    • revertupdate - do an svn revert then an svn update
    • emulateclean - delete unversioned/ignored files then update
    • update - do an svn update as much as possible
  • excluded-users (list(str)) – list of users to ignore revisions from when polling for changes (if polling is enabled; parameter is optional)
  • included-regions (list(str)) – list of file/folders to include (optional)
  • excluded-regions (list(str)) – list of file/folders to exclude (optional)
  • excluded-commit-messages (list(str)) – list of commit messages to exclude (optional)
  • exclusion-revprop-name (str) – revision svn-property to ignore (optional)
  • ignore-property-changes-on-directories (bool) – ignore svn-property only changes of directories (default false)
  • filter-changelog (bool) – If set Jenkins will apply the same inclusion and exclusion patterns for displaying changelog entries as it does for polling for changes (default false)
  • repos (list) – list of repositories to checkout (optional)
  • viewvc-url (str) –

    URL of the svn web interface (optional)

    Repo:
    • url (str) – URL for the repository
    • basedir (str) – Location relative to the workspace root to checkout to (default ‘.’)
    • credentials-id - optional ID of credentials to use
    • repo-depth - Repository depth. Can be one of ‘infinity’, ‘empty’, ‘files’, ‘immediates’ or ‘unknown’. (default ‘infinity’)
    • ignore-externals - Ignore Externals. (default false)

Multiple repos example:

scm:
  - svn:
     workspaceupdater: update
     repos:
       - url: http://svn.example.com/repo
         basedir: .
         credentials-id: "abcdef01234567890"
         repo-depth: files
         ignore-externals: true
       - url: http://svn.example.com/repo2
         basedir: repo2

Advanced commit filtering example:

scm:
  - svn:
      url: http://svn.apache.org/repos/asf/spamassassin/trunk
      credentials-id: "abcdef01234567890"
      repo-depth: empty
      ignore-externals: true
      workspaceupdater: wipeworkspace
      included-regions:
          - /region1/.*\.cpp
          - /region2
      excluded-regions:
          - /region3/.*\.jpg
          - /region4
      excluded-users:
          - user1
          - user2
      excluded-commit-messages:
          - test-msg
          - test-msg2
      exclusion-revprop-name: propname
      filter-changelog: true
      ignore-property-changes-on-directories: true
      viewvc-url: http://svn.apache.org/viewvc/spamassassin/trunk
tfs

Specifies the Team Foundation Server repository for this job. Requires the Jenkins Team Foundation Server Plugin.

NOTE: TFS Password must be entered manually on the project if a user name is specified. The password will be overwritten with an empty value every time the job is rebuilt with Jenkins Job Builder.

Parameters:
  • server-url (str) – The name or URL of the team foundation server. If the server has been registered on the machine then it is only necessary to enter the name.
  • project-path (str) – The name of the project as it is registered on the server.
  • login (str) – The user name that is registered on the server. The user name must contain the name and the domain name. Entered as domain\user or user@domain (optional). NOTE: You must enter in at least two slashes for the domain\user format in JJB YAML. It will be rendered normally.
  • use-update (str) – If true, Hudson will not delete the workspace at end of each build. This causes the artifacts from the previous build to remain when a new build starts. (default true)
  • local-path (str) – The folder where all files will be retrieved into. The folder name is a relative path, under the workspace of the current job. (default .)
  • workspace (str) –

    The name of the workspace under which the source should be retrieved. This workspace is created at the start of a download, and deleted at the end. You can normally omit the property unless you want to name a workspace to avoid conflicts on the server (i.e. when you have multiple projects on one server talking to a Team Foundation Server). (default Hudson-${JOB_NAME}-${NODE_NAME})

    The TFS plugin supports the following macros that are replaced in the workspace name:

    • ${JOB_NAME} - The name of the job.
    • ${USER_NAME} - The user name that the Hudson server or slave is
      running as.
    • ${NODE_NAME} - The name of the node/slave that the plugin currently
      is executed on. Note that this is not the hostname, this value is the Hudson configured name of the slave/node.
    • ${ENV} - The environment variable that is set on the master or slave.
  • web-access (dict) –

    Adds links in “changes” views within Jenkins to an external system for browsing the details of those changes. The “Auto” selection attempts to infer the repository browser from other jobs, if supported by the SCM and a job with matching SCM details can be found. (optional, default Auto).

    web-access value:
     
    • web-url – Enter the URL to the TSWA server. The plugin will strip the last path (if any) of the URL when building URLs for change set pages and other pages. (optional, default uses server-url)

Examples:

scm:
  - tfs:
      server-url: "tfs.company.com"
      project-path: "$/myproject"
      login: "mydomain\\\\jane"
      use-update: false
      local-path: "../foo/"
      workspace: "Hudson-${JOB_NAME}"
      web-access:
        - web-url: "http://TFSMachine:8080"

scm:
  - tfs:
      server-url: "tfs.company.com"
      project-path: "$/myproject"
      login: "jane@mydomain"
      use-update: false
      local-path: "../foo/"
      workspace: "Hudson-${JOB_NAME}"
      web-access:
url

Watch for changes in, and download an artifact from a particular url. Requires the Jenkins URL SCM.

Parameters:
  • url-list (list) – List of URLs to watch. (required)
  • clear-workspace (bool) – If set to true, clear the workspace before downloading the artifact(s) specified in url-list. (default false)

Examples:

scm:
  - url:
      url-list:
        - 'http://jenkins.domain.local/jnlpJars/jenkins-cli.jar'

scm:
  - url:
      url-list:
        - 'http://jenkins.domain.local/jnlpJars/jenkins-cli.jar'
        - 'http://code.jquery.com/jquery-1.11.3.min.js'
      clear-workspace: true
workspace

Specifies the cloned workspace for this job to use as a SCM source. Requires the Jenkins Clone Workspace SCM Plugin.

The job the workspace is cloned from must be configured with an clone-workspace publisher

Parameters:
  • parent-job (str) – The name of the parent job to clone the workspace from.
  • criteria (str) – Set the criteria to determine what build of the parent project to use. Can be one of ‘Any’, ‘Not Failed’ or ‘Successful’. (default Any)

Example:

scm:
  - workspace:
      parent-job: my-upstream-job
      criteria: Any