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

P4 for Jenkins Documentation | 1.17.3

# Building jobs

This section describes how to start a build.

## Before you start

The job must be configured, there are a number of options for this. For details about configuring Jobs, see one of the following guides:

- FreeStyle job setup
- Pipeline job setup
- MultiBranch pipeline setup

## Automatic build using a Perforce triggered build

You can add a Perforce triggered build to a Jenkins job in the Build Triggers section of the job.

Perforce triggered build: Select to enable the Perforce P4 Server to trigger Jenkins to build based on an event, such as a submitted change. A triggered build requires an administrator to add a Perforce trigger. For more information on configuring Perforce triggered builds, see Perforce Triggered Build.

Caveats:

- You must use workspaces named using the recommended environment variables, see Variable Expansion.
- Do not use parameterized builds.

Start a build manually:

1. From the Jenkins dashboard, click the job link.
2. Click Build Now in the sidebar menu.

The job will start to build. You can see the build progress in Build History in the job sidebar.

To start a build from a URL, right click on the Build Now link and save the link. You can now use this link to start the build from another webpage.

## Manual build using P4 Trigger

You can manually trigger jobs from the Jenkins home page by clicking the P4 Trigger button found in the top-right corner of the page.

To manually trigger a build with P4 Trigger, follow these steps:

1. From the Jenkins dashboard, click P4 Trigger in the sidebar menu.

2. Complete the trigger form.
3. Click the Trigger button.

You can add a Perforce triggered build to a Jenkins job in the Build Triggers section of the job, see Perforce Triggered Build.

## Building at a change

A Jenkins job can build at any point in the codes history, identified by a Perforce P4 Server change or label.

The Jenkins job can be pinned to a Perforce P4 Server change, or label by setting the Pin build at Perforce Label field under the Populate options. Any time the Jenkins job is triggered, it will only build up to the pinned point.

If you are using downstream jobs (for example) you can use the Parameterized Trigger Plugin to pass ${P4_CHANGELIST} as the parameter to the downstream job. The downstream job can then pin the build at the passed in changelist so that both upstream and downstream jobs run against the same point in the history of the code.

Alternatively, a change or label can be passed using the Build Review parameters or URL end point (see the Build Review section for details)

## Parallel builds

The plugin supports parallel execution of Jenkins Jobs. Jenkins will create a new workspace directory workspace@2 and so on. The plugin will automatically template the current workspace appending .clone2 for the name of the template.

## Custom parallel builds

Used for custom workspaces, where an alternative location has been set. For example: Advanced, Use custom workspace, Provide a Directory. Then you will need to add the executor number to the end of your path.

/Users/aclaybourne/Workspaces/custom@${EXECUTOR_NUMBER}

The plugin will then correctly template the workspaces as needed.

## Build using a review

The plugin supports a Build Review Action with a review/build/ URL endpoint. The endpoint enables you to trigger a build from a review. Parameters can be passed informing Jenkins about a Perforce P4 Server shelf to unshelve and the changelist to sync to. There are also Pass/Fail callback URLs for use with P4 Code Review.

- P4 for Jenkins 1.10.11 and later: P4 Code Review must send the parameters for the build to Jenkins as a POST request. To do this, enter the parameters in the Post Body of the P4 Code Review project Automated Tests dialog and not in the URL.

- Only Jenkinsfiles in submitted reviews are executed by the build system. Currently, Jenkinsfiles in shelved reviews are not executed by the build system.

For example:
The URL below will build the review, parameters are passed to Jenkins using the variables in the Post Body:

The Build Review Action supports the following parameters in the Post Body:

- review - (Required) The shelf number to unshelve the pending change in the workspace prior to the build.
- change - (Required) The change number to sync the workspace to before unshelving.
- status - (Required) The review status. This must be one of the following strings:
  - shelved
  - committed
  - submitted
- pass - (Optional) A callback URL typically generated by P4 Code Review. This is called to indicate the build passed.
- fail - (Optional) A callback URL typically generated by P4 Code Review. This is called to indicate the build failed.
- update - (Optional) A P4 Code Review update URL to get a build status message of either running, pass and fail in P4 Code Review. If possible, use the update parameter instead of pass and fail.
- p4.label - (Optional) Use this parameter to override the change number to sync the workspace before unshelving.

These parameters are stored in the Environment and can be used with variable expansion for example ${label}. For this reason, please avoid these names for agents and matrix axis.

### Review authorization

If Jenkins requires users to login, your Perforce trigger needs to use a Jenkins authorized account.

Find the API Token for the trigger:

1. From the Jenkins dashboard, click People in the sidebar menu.
2. Click the Jenkins authorized user account link in the table.
3. Click Configure in the sidebar menu.
4. Click the Show API Token... button in the API Token section of the page.
5. Use the API Token with BasicAuth in the URL, for example:

### Manual Review

The Build Review Action can be invoked manually from within Jenkins.

1. From the Jenkins dashboard, click the job name in the table.

2. Click Build Review in the sidebar menu. Complete the form to specify the parameters for build.

   - review - (Required) The shelf number to unshelve the pending change in the workspace prior to the build.
   - change - (Required) The change number to sync the workspace to before unshelving.
   - status - (Required) The review status. This must be one of the following strings:
     - shelved
     - committed
     - submitted
   - pass - (Optional) A callback URL typically generated by P4 Code Review. This is called to indicate the build passed.
   - fail - (Optional) A callback URL typically generated by P4 Code Review. This is called to indicate the build failed.
   - update - (Optional) A P4 Code Review update URL to get a build status message of either running, pass and fail in P4 Code Review. If possible, use the update parameter instead of pass and fail.
   - p4.label - (Optional) Use this parameter to override the change number to sync the workspace before unshelving.

3. To trigger the build, click the Build button.

## Build steps and environment variable

When using build steps such as "Execute Shell", the standard Perforce variables P4PORT, P4USER, and P4CLIENT are not set in the environment. This is to ensure that the P4 Plugin does not overwrite variables on preconfigured build environments. If a build step needs access to these values, the P4_PORT, P4_USER, and P4_CLIENT variables can be used, for example, in a shell script:

export P4CLIENT=$P4_CLIENT

To make the standard variables accessible by default, set them in the Global properties section of the Jenkins Configure System page:

## Post Build Options and Viewing the Build Results

When your build is complete you can view the change summary, and manually tag the build. For more information on you post build options, see Post build options.

Your search for returned results