The Perforce plugin requires p4-java; however at the time of writing this is not in Maven Central. The jar is shipped in the root directory, so to add it into your local maven repo run the following command:
mvn install:install-file \ -Dfile=p4java-2013.2.788582.jar \ -DgroupId=com.perforce \ -DartifactId=p4java \ -Dversion=2013.2.788582 \ -Dpackaging=jar
To build the plugin and run the tests use the following:
Note: for the tests to run you must have p4d in your PATH, to skip tests use the -DskipTests flag.
The plugin makes use of the Jenkins Credential store making it easier to manage the Perforce Server connection for multiple Jenkins jobs. Perforce Server credentials must be added to the Global or a user defined domain, using one of the two supported Perforce Credentials: 'Perforce Password Credential' or 'Perforce Ticket Credential'.
To add a Perforce Credential:
The Perforce Ticket Credential supports using a ticket file (such as the default P4TICKETS file) or a ticket value (returned by the command p4 login -p). If Ticket authentication is used for remote builds the Ticket must be valid for the remote host (either login on the remote host or use p4 login -a).
All Perforce Credential types support SSL for use on Secured Perforce Servers; to use just check the SSL box and provide the Trust fingerprint.
Perforce workspaces are configured on the Jenkin Job configuration page and support the following behaviours:
The workspace specified must have been previously defined. The Perforce Jenkins user must either own the workspace or the spec should be unlocked allowing it to make edits. The workspace View remains static, but Jenkins will update other fields such as the workspace root and clobber option.
The workspace configuration is loaded from a depot file containing a Client workspace Spec (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.
This allows the specified workspace to be created (if it does not exist) or update the spec by setting the various options. Jenkins will fill out the workspace root and may override the clobber option.
In this mode the workspace View is generated using the specified template workspace or stream. The name of the workspace is generated using the Workspace Name Format field and makes it an ideal choice for matrix builds.
Perforce will populate the workspace with the file revisions needed for the build, the way the workspace is populated is configured on the Jenkin Job configuration page and support the following behaviours:
Perforce will revert any shelved or pending files from the workspace; this includes the removal of files that were added by the shelved or pending change. Depending on the two check options boxes Perforce will then clean up any extra files or restore any modified or missing files. Finally, Perforce will sync the required file revisions to the workspace populating the 'have' table.
Perfore will remove all files from under the workspace root, then force sync the required file revisions to the workspace. If the populating the 'have' table options is enabled then the 'have' list will be updated.
This method is not recommended as the cost of IO resources on server and client are high. Apart from exceptional circumstances the Automatic cleanup and sync option will produce the same result.
Perforce will not attempt to cleanup the workspace; the sync operation will update all files (as CLOBBER is set) to the required set of revisions. If the populating the 'have' table options is enabled then the 'have' list will be updated.
Building a Jenkins Job can be triggered using the SCM polling option, Build Now button or calling the build/ URL endpoint.
To enable SCM polling, check the 'Poll SCM' option and provide a Schedule using the Cron format. For example every 10 minutes Monday to Friday, the 'H' is a time offset (calculated using a Hash of the Job name).
To build immediately select the Build now button...
Or use the call the build/ URL endpoint e.g. http://jenkins_host:8080/job/myJobID/build
(where myJobID is the name of your job and jenkins_host the name or IP address of your Jenkins server).
When polling is used, changes can be filtered to not trigger a build; the filters are configured on the Jenkin Job configuration page and support the following types:
Changes owned by the Perforce user specified in the filter will be excluded.
Changes where all the file revision's path starting with the String specified in the filter will be excluded.
For example, with a Filter of "//depot/main/tests":
Case A (change will be filtered):
Files: //depot/main/tests/index.xml //depot/main/tests/001/test.xml //depot/main/tests/002/test.xml
Case B (change will not be filtered, as build.xml is outside of the filter):
Files: //depot/main/src/build.xml //depot/main/tests/004/test.xml //depot/main/tests/005/test.xml
The plugin supports a Build Review Action with a review/build/ URL endpoint. Parameters can be passed informing Jenkins of Perforce shelf to unshelve and changelist to sync to. There are also Pass/Fail callback URLs for use with Swarm.
An example URL that would build the review in the shelved change 23980:
The Build Review Action support the following parameters:
The Build Review Action can be invoked manually from within Jenkins by selecting the Build Review button on the left hand side. This provides a form to specify the parameters for build.
After a build Jenkins provides the ability to see the details of a build. Select the build of interest from the Build History on the left hand side. You then get a Perforce change summary for the build and clicking on the View Detail link for specific files.
Jenkins can tag builds automatically as a Post Build Action or allow manual tagging of a build. The Tags are stored in Perforce as Automatic Labels with the label view based on the workspace at the time of tagging.
Tagging with Post Build Action
Repository browsing allows Jenkins to use an external browser, like Swarm, P4Web, etc... to navigate files and changes associated with a Jenkins build.
To enable the feature select the Repository browser from the Job Configuration page and provide the full URL to the browser.
Link to change in Swarm
|#31||25082||paul_allen||Added a shields for min version.|
|#30||24643||paul_allen||Update Release notes for 1.9.0|
|#29||24489||paul_allen||Updated min requirements.|
|#28||24174||paul_allen||Deprecated Helix 'Build Farm' servers.|
Merge pull request #72 from p4kevin/master
Updates to Freestyle documentation.
|#26||23013||paul_allen||Add new pages for Pipeline.|
Update URLs in README.
Minor find bug fix.
|#24||21856||paul_allen||Update min Jenkins version|
Draft: documentation notes page.
Hints and Tips from Jenkins Users.
|#22||17834||paul_allen||Helix branding update.|
|#21||16541||paul_allen||Document unshelve step and DSL|
|#20||16540||paul_allen||Split up README to separate docs.|
|#19||16539||paul_allen||Update release notes for 1.3.3|
|#18||16187||paul_allen||Update release notes|
|#17||15858||paul_allen||Docs: Workflow setup|
|#16||15696||paul_allen||Update release notes|
|#15||15671||paul_allen||Added Parallel & Custom Parallel builds to the README.|
|#14||15527||paul_allen||Update release notes and docs.|
|#13||15493||paul_allen||Update Swarm URLs in README|
|#12||15419||paul_allen||Updates README with 'change' vs 'P4_CHANGELIST' issue|
Update POM and release notes for next release.
|#10||15329||paul_allen||Update release notes.|
|#9||14915||paul_allen||Update release notes.|
Update Troubleshooting section for Edge/Commit issue.
Added release notes for 1.2.4 and 1.2.3 releases.
Document building at a change.
Documenting solution for overcoming Java 128bit encryption restriction.
Unable to connect: com.perforce.p4java.exception.ConnectionException: Error occurred during the SSL handshake: invalid SSL session
Due to current US export control restrictions for some countries, the standard JDK package only comes with 128 bit encryption level cyphers. In order to use P4Java to connect to an SSL-enabled Perforce server, those living in eligible countries may download the unlimited strength JCE (Java Cryptography Extension) package and replace the current default cryptography jar files with the unlimited strength files.
|#5||11235||paul_allen||MarkDown for Publish Asset.|
|#4||10014||paul_allen||Added doc warning for reserved environment vars.|
|#3||9704||paul_allen||Tidy up README and pushed out a new release 1.0.3 for null/empty params|
|#2||9696||paul_allen||Updated install notes and removed old ref to p4-client|
[Branching using p4-jenkins]