Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 for Jenkins Documentation | 1.17.3

# p4publish: P4 Publish

Jenkins can automatically shelve or submit build assets to a Perforce P4 Server. For example, you could use this function to publish a PDF version of the release document to the P4 Server you use for the build or even a different P4 Server if required. View the details of the shelved or submitted changes on the Changes page of the build.

## Configure a p4publish: P4Publish script

1. To create a P4 Publish script, select p4publish: P4 Publish from the Sample Step dropdown

2. Select the credentials for the project from the Perforce credentials dropdown.

### Workspace behavior

Use a unique Perforce Workspace to Publish the assets. The Client View should be as narrow as possible, ideally only mapping the assets that need to be published. Adding a postfix of -publish to the Workspace will help to identify its purpose.

The Workspace behavior you select determines which configurations are available to you.

Many of the workspace fields can include environment variables to help define their value.

To enable you to identify builds, consider using variables in the Workspace name. 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.
- 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.
- Static (static view, controller 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.
- 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.
- 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.

### Publish Options

Now complete the configuration by selecting one of the following change types:

- Shelve change
- Submit change

## Shelve Change

### Example generated script for p4publish: P4 Publish Shelve Change

The form above generates the following script snippet:

    p4publish(
        credential: 'publicperforcecom1666',
        publish: shelve(
            delete: false,
            description: 'Shelved by Jenkins. Build: ${BUILD_TAG}',
            onlyOnSuccess: true,
            revert: false),
        workspace: staticSpec(
            charset: 'none',
            name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
            pinHost: false
        )
    )

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:

    p4publish(
        credential: 'publicperforcecom1666',
        publish: shelve(
            description: 'Shelved by Jenkins. Build: ${BUILD_TAG}',
            onlyOnSuccess: true),
        workspace: staticSpec(
            name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
        )
    )

### 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('Publish') {
    			steps {
    				// shelve build
    				p4publish(
    					credential: 'publicperforcecom1666',
    					publish: shelve(
    						description: 'Shelved by Jenkins. Build: ${BUILD_TAG}',
    						onlyOnSuccess: true),
    					workspace: staticSpec(
    						name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
    					)
    				)
    			}
            }
        }
    }

### Configure a p4publish: P4Publish Shelve Change script

1. Publish options: Select Shelve change from the dropdown list.
2. Description: The change description used to shelve the assets to the Perforce P4 Server. ${VAR} variables are expanded based on the system environment. For more information about environment variables, see Variable Expansion.
3. Options there are a number of options that can be set to configure client behavior:
   - Only publish on build success: The assets will only be shelved when the build is successful.
   - Propagate deletes: Select to enable files to be deleted when the asset is published.
   - Revert opened file list: Reverts open files in the pending changelist, but leaves the content in the workspace unchanged. Equivalent to p4 revert -k.

#### Generate Pipeline Script

To generate the script, click Generate Pipeline Script. Paste the script into the Script box on the Jenkins Pipeline Script page.

## Submit Change

### Example generated script for p4publish: P4 Publish Submit Change

The form above generates the following script snippet:

    p4publish(
        credential: 'publicperforcecom1666',
        publish: submit(
            delete: false,
            description: 'Submitted by Jenkins. Build: ${BUILD_TAG}',
            onlyOnSuccess: true,
            purge: '',
            reopen: false),
        workspace: staticSpec(
            charset: 'none',
            name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
            pinHost: false
        )
    )

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:

    p4publish(
        credential: 'publicperforcecom1666',
        publish: submit(
            description: 'Submitted by Jenkins. Build: ${BUILD_TAG}',
            onlyOnSuccess: true
    	),
        workspace: staticSpec(
            name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
        )
    )

### 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('Publish') {
    			steps() {
    				// submit build
    				p4publish(
    					credential: 'publicperforcecom1666',
    					publish: submit(
    						description: 'Submitted by Jenkins. Build: ${BUILD_TAG}',
    						onlyOnSuccess: true),
    					workspace: staticSpec(
    						name: 'jenkins-${NODE_NAME}-${JOB_NAME}-${EXECUTOR_NUMBER}',
    					)
    				)
    			}
            }
        }
    }

### Configure a p4publish: P4Publish Submit Change script

1. Publish options: Select Submit change from the dropdown list.
2. Description: The change description used to submit the assets to the Perforce P4 Server. ${VAR} variables are expanded based on the system environment. For more information about environment variables, see Variable Expansion.
3. Options there are a number of options that can be set to configure client behavior:
   - Only publish on build success: The assets will be submitted when the build is successful.
   - Propagate deletes: Select to enable files to be deleted when the asset is published.
   - Reopened files: Submitted files are reopened, allowing subsequent modification.

#### 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.

Your search for returned results