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:
-
-
bzr
Specifies the bzr SCM repository for this job.
Requires the Jenkins Bazaar Plugin.
Example:
scm:
- bzr:
url: lp:test_project
-
cvs
Specifies the CVS SCM repository for this job.
Requires the Jenkins CVS Plugin.
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.
- 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)
- 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)
- 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.
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. (optional)
- verbose (str) – This flag is the toggle for
turning on or off detailed logging in this plug-in. (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
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
- 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)
- 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
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.
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