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.

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
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 credentials to use to connect (optional)
  • refspec (str) – refspec to fetch
  • name (str) – name to fetch
  • 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 credentials to use to connect
      (optional)
  • branches (list(str)) – list of branch specifiers to build
  • excluded-users (list(str)) – list of users to ignore revisions from when polling for changes. (if polling is enabled)
  • included-regions (list(str)) – list of file/folders to include
  • excluded-regions (list(str)) – list of file/folders to exclude
  • local-branch (str) – Checkout/merge to local branch
  • 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
  • basedir (str) – location relative to the workspace root to clone to (default: workspace)
  • skip-tag (bool) – Skip tagging
  • shallow-clone (bool) – Perform shallow clone
  • prune (bool) – Prune remote branches
  • clean (bool) – Clean after checkout
  • fastpoll (bool) – Use fast remote polling
  • disable-submodules (bool) – Disable submodules
  • recursive-submodules (bool) – Recursively update submodules
  • use-author (bool) – Use author rather than committer in Jenkin’s build changeset
  • git-tool (str) – The name of the Git installation to use
  • reference-repo (str) – Path of the reference repo to use during clone
  • scm-name (str) – The unique scm name for this Git SCM
  • wipe-workspace (bool) – Wipe out workspace before build
  • browser (str) – what repository browser to use (default ‘(Auto)’)
  • browser-url (str) – url for the repository browser
  • browser-version (str) – version of the repository browser (GitLab)
  • project-name (str) – project name in Gitblit and ViewGit repobrowser
  • choosing-strategy (str) – Jenkins class for selecting what to build
  • git-config-name (str) – Configure name for Git clone
  • git-config-email (str) – Configure email for Git clone
Browser values:
auto:
bitbucketweb:
cgit:
fisheye:
gitblit:
githubweb:
gitlab:
gitoriousweb:
gitweb:
redmineweb:
stash:
viewgit:
Choosing-strategy values:
 
default:
inverse:
gerrit:

Example:

scm:
  - git:
      url: https://example.com/project.git
      branches:
        - master
        - stable
      browser: githubweb
      browser-url: http://github.com/foo/example.git
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>
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 ‘.’)
  • workspaceupdater (str) – optional argument to specify how to update the workspace (default wipeworkspace)
  • repos (list) –

    list of repositories to checkout (optional)

    Repo:
    • url (str) – URL for the repository
    • basedir (str) – Location relative to the workspace
      root to checkout to (default ‘.’)
Workspaceupdater 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

Example:

scm:
  - svn:
     workspaceupdater: update
     repos:
       - url: http://svn.example.com/repo
         basedir: .
       - url: http://svn.example.com/repo2
         basedir: repo2
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:

scm:
  - tfs:
     server-url: "tfs.company.com"
     project-path: "$/myproject"
     login: "mydomain\\jane"
     use-update: false
     local-path: "../foo/"
     workspace: "Hudson-${JOB_NAME}"
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