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

You can set up P4 Code Review triggers with a Windows-hosted P4 Server.

Prerequisites

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

  • Ensure that the required dependencies are installed on the machine hosting the P4 Server. For more information, see Trigger dependencies.

  • Find your P4 Code Review API token. This token is required to configure P4 Server for P4 Code Review. To find the token, follow these steps:

    1. Log in to P4 Code Review as a super user. For information, see Log in/Log out.

      If you are not a super user, obtain the token from a member of your team who has super user permissions.

    2. On the main toolbar at the upper right, click your user ID.

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

    4. Under Trigger Token, copy the API token. Enter this token in the swarm-trigger.conf file when you configure P4 Server for P4 Code Review.

Set up P4 Code Review triggers

To set up triggers, complete the following steps:

Copy the Perl trigger script 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 directory: p4-bin/scripts

  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 earlier than 2020.1, contact support for assistance with installing triggers.

Configure the API token for the P4 Code Review trigger

You must add the API token to the swarm-trigger.conf configuration file. Ensure that both the configuration file and the swarm-trigger.pl trigger script are in the following depot location on your P4 Server: //.swarm/triggers/

The following procedure is based on the assumption that 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 preferred location is:

    //.swarm/triggers/swarm-trigger.conf

    If you installed P4 Code Review manually, you must manually create the swarm-trigger.conf file.

    Ensure that the configuration file in the same location as the swarm-trigger.pl file.

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

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

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

    The swarm-trigger.conf file has the following structure:

    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

  4. If the workflows feature is disabled, follow the instructions in Additional configuration steps if workflows are disabled.

  5. 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, ensuring that the files exist in the same path on all servers.

  6. If you do not have the HTTP::Tiny Perl module installed, edit the swarm-trigger.pl trigger script and specify the full path to curl.exe.

Additional configuration steps if workflows are disabled

In P4 Code Review version 2019.2 and later, workflows are enabled by default. However, if workflows are disabled, you must provide a value for the 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:

  • 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 port number used by your P4 Server.

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

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

In this example, the ticket for the user specified with ADMIN_USER should be created 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 includes the port that the trigger is attempting to use. The error message is similar to the following example:

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

You might have to comment out some triggers in the trigger table, depending on whether workflows are enabled. For information, see Update the P4 Server triggers table.

Test the trigger script

Test the trigger script to ensure that it runs as expected. Run following command, where <file_path> specifies the path to the swarm-trigger.pl script.

Copy 
C:\>  perl "C:\<file_path>\swarm-trigger.pl" -t ping -v 0

If you do not see output, the trigger script works. If you see a security warning, follow the instructions in Troubleshooting: Curl generates a security warning.

If you see an error message, you must reconfigure the trigger script. For information, see Configure the API token for the P4 Code Review trigger.

Troubleshooting: Curl generates a security warning

A security warning might appear when you run a trigger script and the curl.exe program.

This security prompt causes the swarm-trigger.pl script to hang and creates zombie Perl processes, which are not doing work.

To resolve this issue:

  1. In the security prompt window, clear the Always ask before opening this file checkbox and click Run.

    Windows security warning dialog image

  2. Go to the folder that contains curl.exe.

  3. Right-click curl.exe, click Properties, and click Unblock.

  4. Rerun the swarm-trigger.pl script.

Update the P4 Server triggers table

To run the trigger script, you must update the P4 Server triggers table.

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

  1. To access P4 Server triggers table, run the following command:

    p4 triggers

  2. Add the following lines to the trigger table. You must include a tab at the beginning of each line and replace 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 must 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 committed both the trigger script and the configuration file to the P4 Server, update the trigger table with the following new lines and replace the variables with appropriate values:

    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>/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 copied the trigger script and configuration file to common paths on all servers, add the following lines to the trigger table and replace the variables with appropriate values:

    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%"

  3. Take any additional steps that are required, depending on whether the workflow feature is enabled or disabled. See Additional configuration steps depending on workflow status.

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

Additional configuration steps depending on workflow status

The P4 Code Review workflow feature is enabled by default, starting with version 2019.2. The trigger lines that you must 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 the workflow feature is enabled (default)

Ensure these trigger lines are present in the trigger table:

  • swarm.enforce change-submit

  • swarm.strict change-content

  • swarm.shelvesub shelve-submit

Comment out these trigger lines if they exist:

  • swarm.enforce.1

  • swarm.enforce.2

  • swarm.strict.1

  • swarm.strict.2

If the workflow feature 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 correctly configured:

  • swarm.enforce.1

  • swarm.enforce.2

  • swarm.strict.1

  • swarm.strict.2

To correctly configure the previous trigger lines, review the guidelines:

  • The lines swarm.enforce.1 and .2 are used to ensure that submitted changes are tied to an approved review.

  • The lines swarm.strict.1 and .2 are used to ensure that changelist contents match their approved review contents.

  • You must configure the DEPOT_PATH1 and DEPOT_PATH2 values correctly for the swarm.enforce and swarm.strict triggers to work. For an example, see the example trigger table.

  • The swarm.enforce and swarm.strict triggers are deprecated, and will become unavailable in a future P4 Code Review release.

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

You can ensure that P4 Code Review has access to shelved changelists (which is required for pre-commit reviews). To promote shelved changes, run the following command:

p4 configure set dm.shelve.promote=1

To verify this setting, run the following command:

p4 configure show dm.shelve.promote

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

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. Run a command with the following structure, where <changelist_number> specifies the changelist to be promoted:

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 taking the following additional steps:

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

  • If you installed P4 Code Review by 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 by using a tarball installation, set up a recurring task to spawn workers. For more information, see Set up a recurring task to spawn workers.