Pipeline Script setup

This section describes setting up a pipeline using a Pipeline script and assumes that you are experienced with Jenkins Pipeline. If you are not familiar with Pipeline please read the Jenkins Pipeline documentation: https://jenkins.io/doc/book/pipeline/

You can manually create a script, create a script using the Snippet Generator, or use a mixture of the two. The snippet generator is a simple way to create scripts and then see how they are constructed.

Credentials

P4 Plugin makes use of the Jenkins Credential store, making it easier to manage the Helix Core Server (P4D) connection for multiple Jenkins jobs. For details about creating a Perforce Password Credential or Perforce Ticket Credential, see Add a credential.

Add a new Pipeline

  1. From the Jenkins dashboard, click New item from the sidebar menu.
  2. Enter a name for the new project in the Enter an item name field at the top of the page.
  3. Click Pipeline.
  4. Click OK to start configuring your new Pipeline project.
  5. Description (optional): enter a description for the pipeline in the Description field.
  6. Now configure the pipeline on the pipeline page, see below.

Pipeline configuration

Example Pipeline Script Page

Definition

To configure the pipeline to use a pipeline script, select Pipeline script from the Definition dropdown.

Script

Create your scripts with the Snippet Generator and paste them into the Script text box. For instructions about creating scripts with the Snippet Generator, see Pipeline Syntax Snippet Generator.

Tip

You can also manually enter code into the script text box and modify code that you have pasted into the script text box.

Example script snippet generated for p4sync:P4 Sync

P4Sync is the simplest way to populate your Jenkins workspace from Perforce, see the example script below: 

p4sync( 
    charset: 'none',
    credential: 'Local Perforce 20231',
    format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
    populate: autoClean(
        delete: true,
        modtime: false,
        parallel: [enable: false, minbytes: '1024', minfiles: '1', threads: '4'],
        pin: '',
        quiet: true,
        replace: true,
        tidy: false),
    source: streamSource('//streams-depot/StreamA'
    )
)

Declarative pipeline scripts

If you are using declarative pipeline and not the earlier DSL, you will need to disable the automatic Declarative Checkout SCM step. For example, the declarative pipeline script has three steps, but the build will show four:

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Test') {
            steps {
                echo 'Testing...'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying...'
            }
        }
    }
}

Declarative pipeline

Add options { skipDefaultCheckout() } to the agent.

For example:

pipeline {
    agent any
    
    options { skipDefaultCheckout() }
    
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
        stage('Test') {
            steps {
                echo 'Testing...'
            }
        }
        stage('Deploy') {
            steps {
                echo 'Deploying...'
            }
        }
    }
}

Use Groovy Sandbox

  • To allow standard Groovy code to be executed, select the Use Groovy Sandbox checkbox. This is the default setting.
  • To allow P4Groovy code to be executed clear the Use Groovy Sandbox checkbox.

Pipeline Syntax

To create your script with the Snippet Generator, click the Pipeline Syntax link. The Pipeline Syntax Snippet Generator opens in a new browser tab.

Pipeline Syntax Snippet Generator

The snippet generator is used to automatically generate Groovy scripts from a user interface that is very similar to the forms used when you create a Freestyle project.

To open the Snippet Generator, click the Pipeline Syntax link.

The Snippet Generator is opened in a new tab:

Image of Pipeline SyntaxSnippet Generator, p4sync: P4Sync

Sample Step

The following scripting steps are available from the Sample Step dropdown:

  • Populate and workspace behavior steps:
    • p4sync: P4 Sync: This is the simplest way to populate your Jenkins workspace from Perforce. For details about populating your workspace using p4sync: P4Sync, see p4sync: P4 Sync.
    • checkout: General SCM: If you require full access to the populate options available with Freestyle Jobs you can use the checkout: General SCM option. Select checkout: General SCM from the dropdown and choose Perforce Software from the SCM dropdown. For details about populating your workspace using checkout: General SCM, see checkout: General SCM.
    • p4: P4Groovy: P4Groovy is a Groovy interface to P4Java that allows you to write Perforce commands in the pipeline DSL (Domain Specific Language). For more information about p4: P4Groovy, see p4: P4Groovy.
  • Post build steps:
    • cleanup: Perforce: Cleanup: Select to cleanup the workspace after the build. For more information about using cleanup: Perforce: Cleanup, see cleanup Perforce: Cleanup.
    • p4approve: P4 ApproveImpl Review: PerforceHelix Swarm required. Sets the Swarm review state when the build completes. For more information about using Perforce: ApproveImpl review, see p4approve: P4 ApproveImpl Review.
    • p4publish: P4 Publish: Jenkins can automatically shelve or submit build assets to the PerforceHelix Core Server. For example, you can use this function to publish a PDF of the release notes to the Helix Core Server. For more information about using Perforce: Publish Assets, see p4publish: P4 Publish.
    • p4tag: P4 Tag: Jenkins can tag builds automatically when the build completes. The Tags are stored in the PerforceHelix Core Server as Automatic Labels with the label view based on the workspace at the time of tagging. For more information about using Perforce: P4 Tag, see p4tag: P4 Tag.
  • Build step:
    • p4unshelve: P4 Unshelve: Select to unshelve one or more shelved changes into your Jenkins workspace as a build step. For more information about p4unshelve: P4 Unshelve, see p4unshelve: P4 Unshelve.

Generate Pipeline Script

To generate the pipeline script:

  1. Click Generate Pipeline Script.

    2. The script is generated in the text box below the button.

  2. Copy the generated script.
  3. Go back to the browser tab for your Jenkins Pipeline page.
  4. Paste the generated script into the Script box.

Save

When you have finished adding scripts to the pipeline job, click Save.

Building

Now that you have your scripts your job it is ready to be built. For information about building jobs, see Building Jobs.

Further pipeline script information

Multiple Syncs

If you need more than one sync task in a script you MUST use a different workspace name.

You can control this by customizing the Workspace Name Format field. The default value is jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER} and will not appear in the generated snippet, however if you change this to jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}-libs you will see a new attribute in the snippet format: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}-libs'.

Build Triggers

If no triggers are set, Jenkins will build based on the Polling build filters in use.

  • Perforce triggered build: A build trigger can be added to the job after you have tested the job and proved that it works correctly. For instructions about configuring a build trigger, see Automatic build using a Perforce triggered build.
  • Poll SCM: If you enable Poll SCM, ensure that your Auto build filters are configured to suit regular builds and that the polling frequency is longer than the time the build takes to complete.

    • Note

    It is generally better to use the Perforce triggered build option trigger a build based on an specific event, such as a submitted change.

Polling

Jenkins will poll for each sync step in a build script and also for the Jenkinsfile if using the Pipeline script from SCM option.

The advanced populate option checkout: General SCM provides check boxes to disable polling (and changelog).

Advanced Polling

Polling requires access to previous build data (build.xml). P4 Plugin tracks the previous build change using a syncID as a polling operation might iterate over multiple sync steps. The syncID is normally calculated from the client workspace name, but must be unique enough to distinguish between multiple sync steps, but common enough to identify previous builds. For this reason if the client Workspace name contains any of the following variables their values will be ignored when determining the syncID:

  • NODE_NAME (which might change between slaves)
  • BUILD_NUMBER (which changes for each build)
  • EXECUTOR_NUMBER (changes based on the execution thread)

In very rare circumstances a user may want to override the syncID, this can be done by specifying the attribute on a workspace: class.

Limitations

Changelist reporting

Core Jenkins ties changelist reporting to individual p4 sync commands. If the same job has multiple 'checkout' or 'p4sync' steps that sync the same changelist it will be reported once for each individual sync on the 'Status' and 'Changes' pages. P4 Plugin is not able to override this behavior.