Helix Plugin for Jenkins Guide (1.11.x)

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. P4 Plugin credentials must be added to a Global or User defined domain, using one of the two supported P4 Plugin Credentials: Perforce Password Credential or Perforce Ticket Credential.

Add a credential

  1. Navigate to the Jenkins Credentials page by clicking Credentials in the sidebar menu.
  2. Add a domain if required and select the domain or global link as required.
  3. Click Add credentials in the sidebar menu.
  4. Now complete credential configuration by selecting one of the following credential types:

Add a Perforce Password Credential

Password credentials

  1. Select Perforce Password Credential from the Kind dropdown.
  2. Select the scope for the credential from the Scope dropdown.
  3. If you are using Freestyle to configure jobs, the ID field can be left blank. If you are using Pipeline or MultiBranch to configure jobs, enter a unique short friendly name for the ID for the credentials in the ID field.
  4. Optional: Enter a description for the credential in the Description field.
  5. Enter the Helix server and port number details in the P4Port field. For example: 10.0.0.4:1666 perforce:1666 perforce.domain.com:1666 localhost:1666
  6. If the Helix server is configured for SSL connections, select the SSL connection checkbox and enter the Trust fingerprint in the Trust field. If you have a problem connecting with SSL, see Error using SSL below.
  7. Note
    • The P4 Plugin defaults to TLSv1.2 for SSL connections to the Helix server. For instructions on specifying a different TLS version for the SSL connection, see Solution 2 in the Error using SSL section.
    • Helix server version 2019.1 or later is required for TLSv1.2 SSL connections.

  8. Enter a valid username in the Username field. The minimum protection level for the Jenkins user account is open.
  9. Enter a valid password in the Password field.
  10. To check that you have configured the credentials correctly, click Test Connection. The credentials are tested against the Helix serverand if they are configured correctly Success is displayed.
  11. Click Save to save the credentials.

Add a Perforce Ticket 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.

Password credentials

  1. Select Perforce Ticket Credential from the Kind dropdown.
  2. Select the scope for the credential from the Scope dropdown.
  3. If you are using Freestyle to configure jobs the ID field can be left blank. If you are using Pipeline or MultiBranch to configure jobs, enter a unique short friendly name for the ID for the credentials in the ID field.
  4. Optional: Enter a description for the credential in the Description field.
  5. Enter the Helix server and port number details in the P4Port field. For example: 10.0.0.4:1666 perforce:1666 perforce.domain.com:1666 localhost:1666
  6. If the Helix server is configured for SSL connections, select the SSL connection checkbox and enter the Trust fingerprint in the Trust field. If you have a problem connecting with SSL, see Error using SSL below.
  7. Note
    • The P4 Plugin defaults to TLSv1.2 for SSL connections to the Helix server. For instructions on specifying a different TLS version for the SSL connection, see Solution 2 in the Error using SSL section.
    • Helix server version 2019.1 or later is required for TLSv1.2 SSL connections.

  8. Enter a valid username in the Username field. The minimum protection level for the Jenkins user account is open.
  9. Select one of the following options for the Perforce ticket: Ticket value: Select the Login with ticket value checkbox and enter a valid session ticket. Use the p4 login -p command to print the ticket, add the '-a' flag to enable the ticket to be used from any machine. P4TICKETS file: Select the Use P4TICKETS file checkbox and enter the full path to the Perforce tickets file. Typically /[HOME]/.p4tickets or c:[HOME]\p4tickets.txt.
  10. To check that you have configured the credentials correctly, click Test Connection. The credentials are tested against the Helix server and if they are configured correctly Success is displayed.
  11. Click Save to save the credentials.

Connection Issues

Error using SSL

Error: Connection to an SSL enabled Helix server (P4D) fails.

Unable to connect: com.perforce.p4java.exception.ConnectionException:
Error occurred during the SSL handshake:
invalid SSL session

There are two common causes for this SSL error and your connection might fail for both of them:

  • Your Java distribution does not have the required JCE libraries for 256-bit SSL connections, see Solution 1 below.
  • You have configured your Helix server for a minimum TLS version greater than v1.2, see Solution 2 below.

Solution 1

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 Helix server (P4D), those living in eligible countries can download the unlimited strength JCE (Java Cryptography Extension) package and replace the current default cryptography jar files on the build server with the unlimited strength files. The libraries can be downloaded from: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html Installation instructions can be found in the file 'README.txt' in the JCE download.

Solution 2

To use a different TLS version from the default one used by the P4 Plugin, start Jenkins with the additional flag -DsecureSocketEnabledProtocols=VERSION where VERSION is a comma-separated list of accepted protocol versions.

For example, edit /etc/default/jenkins and set the flag to JAVA_ARGS:

JAVA_ARGS="-Djava.awt.headless=true -DsecureSocketEnabledProtocols=TLSv1.1"

This will need to be set on the master and on every build slave.

Error with Edge/Commit Server

Error: Perforce login error part way through a build with an Edge/Commit setup.

Perforce password (P4PASSWD) invalid or unset.
- no such file(s).
ERROR: Unable to update workspace:
com.perforce.p4java.exception.AccessException: Perforce password (P4PASSWD) invalid or unset.

Solution: The following configurables must be set to allow the Edge to forward the login information to the Commit server.

p4 configure set cluster.id=myID

p4 configure set myEdge#rpl.forward.login=1