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: []
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
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 ‘**’)
  • excluded-users (list(str)) – list of users to ignore revisions from when polling for changes. (if polling is enabled, optional)
  • included-regions (list(str)) – list of file/folders to include (optional)
  • excluded-regions (list(str)) – list of file/folders to exclude (optional)
  • local-branch (str) – Checkout/merge to local branch (optional)
  • merge (dict) –
    merge:
    • 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’)
  • basedir (str) – location relative to the workspace root to clone to (default workspace)
  • skip-tag (bool) – Skip tagging (default false)
  • shallow-clone (bool) – Perform shallow clone (default false)
  • prune (bool) – Prune remote branches (default false)
  • 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.

  • use-author (bool) – Use author rather than committer in Jenkin’s build changeset (default false)
  • 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)
  • scm-name (str) – The unique scm name for this Git SCM (optional)
  • ignore-notify (bool) – Ignore notifyCommit URL accesses (default false)
  • 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)
  • choosing-strategy (str) – Jenkins class for selecting what to build. Can be one of default, inverse, or gerrit (default ‘default’)
  • git-config-name (str) – Configure name for Git clone (optional)
  • git-config-email (str) – Configure email for Git clone (optional)
Extensions:
  • 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’)
  • clean (dict)
    • after (bool) - Clean the workspace after checkout
    • before (bool) - Clean the workspace before checkout
  • ignore-commits-with-messages (list(str)) - Revisions committed with messages matching these patterns will be ignored. (optional)

  • force-polling-using-workspace (bool) - Force polling using workspace (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)
    • timeout (int) - Specify a timeout (in minutes) for submodules operations (default: 10).
  • timeout (str) - Timeout for git commands in minutes (optional)

  • 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 OpenShift3 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. (optional)

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

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
  • 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)
  • 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)
  • current-branch (bool) – Fetch only the current branch from the server (default true)
  • quiet (bool) – Make repo more quiet (default true)
  • 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
      destination-dir: build
      repo-url: https://internal.net/projects/repo
      mirror-dir: ~/git/project/
      jobs: 3
      current-branch: false
      quiet: false
      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:
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

Previous topic

Reporters

Next topic

Triggers

This Page