Set up P4 Code Review triggers with a Linux-hosted P4 Server

The operating system which hosts your P4 Server determines how to set up P4 Code Review triggers. This guide outlines how to set up P4 Code Review triggers with a Linux-hosted P4 Server.

Prerequisites

Complete the following steps before setting up P4 Code Review triggers:

  • Check the required dependencies have been installed on the machine hosting the P4 Server. For more information, see Trigger dependencies.

  • Find your P4 Code Review API token. You need this token you configure P4 Server for P4 Code Review. To find this API token, follow these steps:

    1. Log in to P4 Code Review as a super user. For more information, see Log in/Log out.
    2. Click your userid, found at the right of the main toolbar.

    3. Select About P4 Code Review. The About P4 Code Review dialog is displayed and P4 Code Review generates an API token if it doesn't already exist.

    4. Copy the API token displayed at the bottom of the dialog. This token is the trigger token to enter in the swarm-trigger.conf file when you configure P4 Server for P4 Code Review.

Set up P4 Code Review triggers

As there are many steps involved in setting up P4 Code Review triggers, these have been broken into the following sections:

Copy the Perl trigger script on to your P4 Server

Follow these steps to locate and copy the Perl trigger script:

  1. Find the P4 Code Review Perl trigger script, swarm-trigger.pl, in the following location: p4-bin/scripts/swarm-trigger.pl

  2. Copy this Perl script to the following depot on your P4 Server: //.swarm/triggers/swarm-trigger.pl

If you are using a version of P4 Code Review that is older than 2020.1, contact support for assistance on installing triggers.

Configure the API token for the P4 Code Review trigger

This sections outlines how to add the API token to the swarm-trigger.conf configuration file. Both the configuration file and the swarm-trigger.pl trigger script should be in the depot.

The following steps assume you have installed and configured P4 Code Review from a package. For more information, see Install and configure P4 Code Review from a package (recommended).

  1. Find the P4 Code Review configuration file in the following location: /opt/perforce/etc/swarm-trigger.conf.

  2. Copy the swarm-trigger.conf file to the depot. The recommended depot location is //.swarm/triggers/swarm-trigger.conf

    If you installed P4 Code Review manually, you will also need to manually create the swarm-trigger.conf file.

    Ensure the configuration file in the same location as the swarm-trigger.pl file. The recommended depot location is //.swarm/triggers/swarm-trigger.conf

  3. Modify the swarm-trigger.conf configuration file to update the following:

    • SWARM_HOST: Update this with the host name of the P4 Code Review instance. This starts with either http:// or https://, for example: SWARM_HOST="http://my-swarm-host

    • SWARM_TOKEN: Update this with the API token you copied before. To find your API token, see the prerequisites above.

Below is a sample of the swarm-trigger.conf:

Copy 
# SWARM_HOST (required)
# Hostname of your Swarm instance, with leading "http://" or "https://".
SWARM_HOST="http://my-swarm-host"

# SWARM_TOKEN (required)
# The token used when talking to Swarm to offer some security. To obtain the
# value, log in to Swarm as a super user and select 'About Swarm' to see the
# token value.
SWARM_TOKEN="MY-UUID-STYLE-TOKEN"

# ADMIN_USER (optional) Do not use if the Workflow feature is enabled (default)
# For enforcing reviewed changes, optionally specify the normal Perforce user
# with admin privileges (to read keys); if not set, will use whatever Perforce
# user is set in environment.
ADMIN_USER=

# ADMIN_TICKET_FILE (optional) Do not use if the Workflow feature is enabled (default)
# For enforcing reviewed changes, optionally specify the location of the
# p4tickets file if different from the default ($HOME/.p4tickets).
# Ensure this user is a member of a group with an 'unlimited' or very long
# timeout; then, manually login as this user from the Perforce server machine to
# set the ticket.
ADMIN_TICKET_FILE=                
                
# VERIFY_SSL (optional)
# If HTTPS is being used on the Swarm web server, then this controls whether
# the SSL certificate is validated or not. By default this is set to 1, which
# means any SSL certificates must be valid. If the web server is using a self
# signed certificate, then this must be set to 0.
VERIFY_SSL=1

When using Linux, swarm-trigger.pl looks for configuration in the following files.

  • /etc/perforce/swarm-trigger.conf
  • /opt/perforce/etc/swarm-trigger.conf
  • The swarm-trigger.conf file stored in the same directory as swarm-trigger.pl.
  • Any file passed to the swarm-trigger.pl script using the -c command line argument.

Variables defined in the later files override the earlier defined variables of the same name, for example, variables set inside the swarm-trigger.pl script itself.

Troubleshooting: If workflows are disabled

From P4 Code Review version 2019.2 and later, workflows are enabled by default. When workflows are enabled, you need to provide an ADMIN_USER in the swarm-trigger.conf file.

The login for the ADMIN_USER is authenticated using a ticket file which is found in either of the following locations:

  • On Windows, the file path is: %USERPROFILE%\p4tickets.txt

  • In the swarm-trigger.conf file, the file path is set using ADMIN_TICKET_FILE.

If you provide an ADMIN_USER, the login ticket contain the exact same port number used by your P4 Server.

For example, if P4 Server is initiated with the following code:

Copy 
p4d -p my-helix-core-server:1666 ...

Then the ticket for the user specified with ADMIN_USER should be established with:

Copy 
p4 -p my-helix-core-server:1666 -u admin_userid login

If the ticket was established using the wrong port, the error message you encounter includes the port that the trigger is attempting to use. Below is an example of the error message:

'swarm.strict.1' validation failed: Invalid login credentials to [port] within this trigger script; please contact your administrator

Troubleshooting: Copying swarm-trigger.conf when using edge servers

If you copied the swarm-trigger.pl trigger script to the commit server and all relevant edge servers in the previous step, also copy the swarm-trigger.conf configuration file to the commit server as well as the edge servers, making sure that the files exist in the same path on all servers.

Ensure trigger script works

Skip this step if you have committed the trigger script to the P4 Server.

The swarm-trigger.pl trigger script requires execute permissions. Run the following command in the terminal to grant the script the relevant permissions:

Copy 
$ chmod +x /<file_path>/swarm-trigger.pl

Replace <file_path> with the file path to the swarm-trigger.pl trigger script.

Verify that the trigger script executes correctly. On Linux, open the terminal and run the following:

Copy 
$ /<file_path>/swarm-trigger.pl -t ping -v 0

If you do not see any output, then the trigger script works.

If you see an error, the trigger script is needs to be reconfigured. For more information, see Configure the API token for the P4 Code Review trigger.

Update the P4 Server triggers table

Update the P4 Server triggers table to run the trigger script. To access the table, enter p4 triggers in your command line.

You must be a P4 Server user with super privileges to edit the table.

Add the following lines (make sure to include the initial tab character at the start of each line) to the trigger table, replacing the following variables with the corresponding file path:

  • <perl_path> - the file path to perl.exe.

  • <trigger_path> - the file path to swarm-trigger.pl.

  • <config_path> - the file path to swarm-trigger.conf.

Depending on whether you committed the trigger script and configuration file to the P4 Server or copied them to common paths on all servers, you will need to update the trigger table accordingly.

When updating the trigger table:

  • An initial tabbed indent is required for each trigger line.

  • Commented out trigger lines are not stored.

If you have committed both the trigger script and the configuration file to the P4 Server, add the following lines to the trigger table

Copy 
    swarm.job        form-commit   job    "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t job        -v %formname%"
    swarm.user       form-commit   user   "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t user       -v %formname%"
    swarm.userdel    form-delete   user   "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t userdel    -v %formname%"
    swarm.group      form-commit   group  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t group      -v %formname%"
    swarm.groupdel   form-delete   group  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t groupdel   -v %formname%"
    swarm.changesave form-save     change "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t changesave -v %formname%"
    swarm.shelve     shelve-commit  //...  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t shelve     -v %change%"
    swarm.commit     change-commit  //...  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t commit     -v %change%"
    swarm.shelvedel  shelve-delete  //...  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t shelvedel  -v %change% -w %client% -u %user% -d %quote%%clientcwd%^^^%quote% -a %quote%%argsQuoted%%quote% -s %quote%%serverVersion%%quote%"
#    The following three triggers are used by workflows. 
#    If workflows are enabled in P4 Code Review, 
#    then these triggers should also be disabled. 
    swarm.enforce    change-submit  //...  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/triggers/swarm-trigger.conf% -t checkenforced -v %change% -u %user%"
    swarm.strict     change-content //...  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t checkstrict   -v %change% -u %user%"
    swarm.shelvesub  shelve-submit  //...  "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t checkshelve   -v %change% -u %user%"
#    The following triggers are only used to prevent a commit
#    without an approved review. They predate the workflow
#    functionality and should only be used if workflow is disabled.
#    Support for these will be dropped in a later release.
#    swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
#    swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
#    swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t strict -v %change% -p %serverport%"
#    swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%<perl_path>\perl.exe%quote% %<trigger_path>/swarm-trigger.pl% -c %<config_path>/swarm-trigger.conf% -t strict -v %change% -p %serverport%"

If you have copied the trigger script and configuration file to common paths on all servers:

Copy 
    swarm.job        form-commit   job    "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t job        -v %formname%"
    swarm.user       form-commit   user   "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t user       -v %formname%"
    swarm.userdel    form-delete   user   "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t userdel    -v %formname%"
    swarm.group      form-commit   group  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t group      -v %formname%"
    swarm.groupdel   form-delete   group  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t groupdel   -v %formname%"
    swarm.changesave form-save     change "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t changesave -v %formname%"
    swarm.shelve     shelve-commit  //...  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t shelve     -v %change%"
    swarm.commit     change-commit  //...  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t commit     -v %change%"
    swarm.shelvedel  shelve-delete  //...  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t shelvedel  -v %change% -w %client% -u %user% -d %quote%%clientcwd%^^^%quote% -a %quote%%argsQuoted%%quote% -s %quote%%serverVersion%%quote%"
#    The following three triggers are used by workflows. 
#    If workflows are enabled in P4 Code Review, 
#    then these triggers should also be disabled. 
    swarm.enforce    change-submit  //...  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t checkenforced -v %change% -u %user%"
    swarm.strict     change-content //...  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t checkstrict   -v %change% -u %user%"
    swarm.shelvesub  shelve-submit  //...  "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t checkshelve   -v %change% -u %user%"                            
#    The following triggers are only used to prevent a commit
#    without an approved review. They predate the workflow
#    functionality and should only be used if workflow is disabled.
#    Support for these will be dropped in a later release.
#    swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%"
#    swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t enforce -v %change% -p %serverport%"
#    swarm.strict.1  change-content //DEPOT_PATH1/... "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"
#    swarm.strict.2  change-content //DEPOT_PATH2/... "%quote%<perl_path>\perl.exe%quote% %quote%<trigger_path>/swarm-trigger.pl%quote% -c %quote%<config_path>/swarm-trigger.conf%quote% -t strict -v %change% -p %serverport%"
If you are using a version of P4 Code Review that is older than 2020.1, contact support for assistance on installing triggers.

Troubleshooting: Workflows require triggers to be enabled or disabled

P4 Code Review workflow feature is enabled by default from version 2019.2 onwards. The trigger lines you need to configure in the P4 Server depend on whether this feature is enabled or disabled.

If you disable the workflow feature in the P4 Code Review config.php file, workflows are not processed by P4 Code Review but a small overhead is still incurred by the P4 Server each time it runs a workflow trigger script. This overhead can be eliminated by commenting out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit workflow triggers.

If Workflow is enabled (default)

Comment out these trigger lines if they exist:

  • swarm.enforce.1

  • swarm.enforce.2

  • swarm.strict.1

  • swarm.strict.2

Ensure these trigger lines are present in the trigger table:

  • swarm.enforce change-submit

  • swarm.strict change-content

  • swarm.shelvesub shelve-submit

If Workflow is disabled

Comment out these trigger lines if they exist:

  • swarm.enforce change-submit

  • swarm.strict change-content

  • swarm.shelvesub shelve-submit

The following trigger lines are optional and should be commented out unless configured properly:

  • swarm.enforce.1

  • swarm.enforce.2

  • swarm.strict.1

  • swarm.strict.2

Notes on these optional triggers:

  • The lines swarm.enforce.1 and .2 enforce that submitted changes must be tied to an approved review.

  • The lines swarm.strict.1 and .2 enforce that changelist contents must match their approved review contents.

  • You must configure the DEPOT_PATH1 and DEPOT_PATH2 values correctly for these triggers to work.

  • Support for these triggers will be removed in future P4 Code Review releases.

If you want to apply the triggers for enforce or strict to additional depot paths, copy the existing lines and update the depot paths accordingly.

Configure the P4 Server to promote all shelved changes

Configuring this setting ensures P4 Code Review has access to shelved changelists (which is required for pre-commit reviews). Run the following in the command line to configure promote shelved changes:

Copy 
p4 configure set dm.shelve.promote=1

To verify this setting, enter the following into the command line:

Copy 
p4 configure show dm.shelve.promote

If the setting is configured correctly, the following text is returned.

Copy 
dm.shelve.promote=1

If this setting is not configured and you are using an edge server, you must use the -p option when promoting shelved files to the commit server when initiating a pre-commit review. An example of which is shown below:

Copy 
p4 shelve -p -c <changelist_number>

Optional installation steps

Depending on how you installed P4 Code Review and what other P4 products are available to you, consider the following:

  • If you intend to use P4V and its P4 Code Review integration, consider using forwarding logins to the commit server. For more information, see P4V Authentication.

  • If you installed P4 Code Review using a package installation, review the post-install configuration options to customize your P4 Code Review installation. For more information, see Post-install configuration options.

  • If you installed P4 Code Review using a tarball installation, set up a recurring task to spawn workers. For more information, see Set up a recurring task to spawn workers.