checkout: General SCM

If you need full access to the populate options available with Freestyle Jobs you can use the checkout: General SCM step in the Snippet Generator.

Example checkout: General SCM configuration

Example script generated for checkout: General SCM

The checkout: General SCM form above generates the following script snippet:

checkout perforce(
    credential: 'publicperforcecom1666', 
    filter: [pathFilter('//depot/projects/alpha/tests/...')], 
    populate: autoClean(
        delete: true, 
        modtime: false, 
        parallel: [enable: false, minbytes: '1024', minfiles: '1', threads: '4'], 
        pin: '', 
        quiet: true, 
        replace: true, 
        tidy: false), 
    workspace: manualSpec(
        charset: 'none', 
        name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}', 
        pinHost: false, 
        spec: clientSpec(
            allwrite: false, 
            backup: true, 
            changeView: '', 
            clobber: true, 
            compress: false, 
            line: 'LOCAL', 
            locked: false, 
            modtime: false, 
            rmdir: false, 
            serverID: '', 
            streamName: '', 
            type: 'WRITABLE', 
            view: '''//depot/projects/alpha/... //${P4_CLIENT}/...
                     //depot/projects/beta/... //${P4_CLIENT}/...'''	
        )
    )
)

Tip

If you manually edit your script, remember to keep the single quotes that the snippet generator puts around the variables. Replacing them with full quotes " will expand the variables early and the script will fail. For more information about this, see Variable Expansion.

Reduce the script snippet size to make it more readable

You can reduce the script size and make it easier to read by removing any options that are set to the default value.

Example script snippet with default values removed:

checkout perforce(
    credential: 'publicperforcecom1666', 
    filter: [pathFilter('//depot/projects/alpha/tests/...')], 
    populate: autoClean(), 
    workspace: manualSpec(
        name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}', 
        spec: clientSpec(
            view: '''//depot/projects/alpha/... //${P4_CLIENT}/...
                     //depot/projects/beta/... //${P4_CLIENT}/...'''
        )
    )
)

Paste the script snippet into a basic script

Example: the script snippet above has been pasted into a basic script:

pipeline {
    agent any 
    stages {
        stage('Checkout') {
            steps {
                // checkout files from //depot/projects/alpha/...
                checkout perforce(
                    credential: 'publicperforcecom1666', 
                    filter: [pathFilter('//depot/projects/alpha/tests/...')], 
                    populate: autoClean(), 
                    workspace: manualSpec(
                        name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}', 
                        spec: clientSpec(
                            view: '''//depot/projects/alpha/... //${P4_CLIENT}/...
                                     //depot/projects/beta/... //${P4_CLIENT}/...'''
                        )			
                    )
                )
            }
        }
    }
}

Configure a checkout: General SCM script

To configure the pipeline to use checkout: General SCM, select checkout: General SCM from the Sample Step dropdown
To configure the project to use the Perforce Helix Server, select Perforce Software from the SCM dropdown.
Select the credentials for the project from the Perforce credentials dropdown.

Workspace behavior

Important

Use a unique workspace name for the Jenkinsfile that will not get reused by the sync steps in the script. A postfix of -script will help to identify the workspace's use and make it unique from code sync steps.
If you need more than one sync task in a script you MUST use a different workspace name. For instructions on how to do this, see Multiple Syncs.
Only map the Jenkinsfile (and perhaps Pipeline libraries) in the workspace view. Jenkins may create an @script directory on the master and you don't want to unnecessarily sync code to an area not used for the actual build.

Note

Many of the workspace fields can include environment variables to help define their value. We recommend that variables are used in the Workspace name to enable you to identify builds. For more information about environment variables, see Variable Expansion.

Perforce workspaces support the following behaviors:

Manual (custom view): Manually define the workspace view, and sync options. Creates the workspace if it does not already exist or updates the workspace spec by setting the various options if it already exists. Jenkins will fill out the workspace root and may override the clobber option. For details about manually configuring your workspace, see Manual workspace.
Static (static view, master only): Uses a predefined workspace, the workspace must have a valid view and must already exist. The plugin user must either own the workspace or the spec must be unlocked allowing the plugin user to make edits. The workspace view remains static, but Jenkins will update other fields such as the workspace root, and clobber option. For details about using a static predefined workspace, see Static workspace.
Template (view generated for each node): Uses a specified template to generate the workspace view. The name of the workspace is generated using the Workspace Name Format field. This makes it an ideal choice for Matrix builds. For details about using a template to generate the workspace, see Template workspace.
Streams (view generated by Perforce for each node): Uses a specified stream to generate the workspace view. The name of the workspace is generated using the Workspace Name Format field. This makes it an ideal choice for Matrix builds. For details about using a stream to generate the workspace, see Streams workspace.
Spec File (load workspace spec from file in Perforce): Loads the workspace configuration from a depot file containing a client workspace spec. This is the same output as p4 client -o and the Spec depot .p4s format. The name of the Workspace must match the name of the client workspace spec. For details about using a spec file for your workspace, see Spec File workspace.

Populate options

Perforce populates the workspace with the file revisions needed for the build, the options are:

Automatic Cleanup and Sync: Use when the Perforce Helix Server controls the files in the workspace. This is an efficient option that cleans and syncs file revisions in the workspace. Extra (non versioned files) are removed, missing and modified files are re-added. This option is best for clean builds. For details about the Automatic Cleanup and Sync options, see Automatic Cleanup and Sync.
Flush Workspace: Use when files in the workspace are not added by the Perforce Helix Server. No file Sync or cleanup is attempted and no files are removed, but the workspace "have list" is updated. This is effectively the same as using the p4 sync -k command. For details about the Flush Workspace options, see Flush Workspace.
Forced Clean and Sync: Not recommended because this option is very inefficient. Use if you do not trust the content of your workspace. Removes all of the files in the workspace root, including the build history, and then force syncs the required files. For details about the Forced Clean and Sync options, see Forced Clean and Sync.
Graph Force Clean and Sync: Perforce Git Connector required. Use for Perforce Graph and Hybrid only. Removes all of the files in the workspace root, including the build history, and then force syncs the required files. For details about the Graph Force Clean and Sync options, see Graph Force Clean and Sync.
Preview Check Only: No file sync or cleanup is attempted, and the Workspace "have list" is not updated. This is effectively the same as using the p4 sync -n command. For details about the Preview Check Only options, see Preview Check Only.
Sync Only: Use if you have a hand-crafted build environment that you don't want to lose any files from. No cleanup is attempted and the sync will update all files (as CLOBBER is set) to the required revisions. This option is best for incremental builds and is mostly used for Pipeline builds. For details about the Sync Only options, see Sync Only.

Parallel Sync

Parallel sync enables concurrent transfer of files between Jenkins and the Helix Server. Parallel sync can greatly reduce the amount of time it takes to update a workspace, especially when connecting across a high latency network. Parallel sync must be enabled on the Helix Server (2014.1 or later). For more information on parallel sync, see Using parallel processing for submits and syncs in Helix Core Server Administrator Guide. Parallel sync is disabled by default, to enable parallel sync:

Click Advanced.
Select Enabled.
The parallel sync settings will depend on the capabilities of the Jenkins build machine and the Helix Server:
- Threads: Set the number of threads available for parallel sync.
- Minimum Files: If the number of files being sync'ed is less than this value, parallel sync is not used.
- Minimum Bytes: If the total size of files being sync'ed is less than this value, parallel sync is not used.

Polling build filters

When polling is used, changes can be filtered to not trigger a build. If the build has more than one filter, the filters are processed starting from the top of the list of filters. Filters can be dragged up or down the list to change the order they are processed in. Click Add a new build filter and select a filter from the dropdown list, options are:

Exclude changes from depot path: Changes can be filtered to not trigger a build if all of the files within a change match the specified path. For examples, see Exclude Changes From Depot Path.
Exclude changes from user: Changes owned by the Perforce Helix Server user specified in the filter will not be built.
Exclude changes from outside Java pattern: Changes can be filtered to not trigger a build if none of the files within a change match the Java patterns (regular expression) listed. For examples, see Exclude Changes From Outside Java Pattern.
Exclude changes outside view mask: Changes can be filtered to not trigger a build if none of the files within a change are contained in the view mask. For examples, see Exclude Changes Outside view mask.
Polling per Change: A build is carried out for every change that is submitted. The polling event will only return the oldest unbuilt change, resulting in incremental builds.
Polling latest Change: A build is carried out for the latest change found during polling.

Repository browser

Repository browsing allows Jenkins to use an external browser to navigate files and changes associated with a Jenkins build. The Helix Swarm browser is recommended.
To enable the feature, select the browser from the Repository browser dropdown list, and provide the full URL to the browser.

Repository Browser

Example of a link to a change in Swarm:

Example Change in Swarm

Include in polling?

By default Jenkins polls for each sync step in the build script and the Jenkinsfile, clear the Include in Polling? checkbox to disable polling.

Include in changelog?

By default Jenkins polls for each sync step in the build script and the Jenkinsfile, clear the Include in Changelog? checkbox to stop the polling information being included in the changelog.

Generate Pipeline Script

To generate the pipeline script, click Generate Pipeline Script. The script is generated in the text box below the button.

Copy the generated script and paste it into the Script box on the Jenkins Pipeline Script page.