Setting up trigger scripts

Important

Helix TeamHub 2022.1 and later supports extensions for events instead of triggers. Triggers will no longer be maintained. If you have triggers installed, remove them and install the extensions to use them instead. See Configuring Helix Core Server extensions.

Important

Make sure that the following required trigger dependencies have been installed on the computer hosting Helix Server:

  • Perl 5.08+

  • Perl Core on CentOS

  • On Ubuntu only, packages libnet-ssleay-perl and libio-socket-ssl-per

Helix Server provides triggers to customize the operation of the server, or to invoke additional processing for specific kinds of versioning operations. TeamHub provides a trigger script written in Perl that notifies TeamHub about activity within the Helix Server. When configured, any pushes you do to your graph depots are visible as events in the TeamHub activity stream in the Activity view.

For TeamHub to display push events in the UI, you need to configure the TeamHub trigger in the Helix Server. The trigger supports the following events:

  • branch create
  • branch delete
  • tag create
  • tag delete
  • push

The trigger script is part of the installation package you downloaded earlier (see Combo setup).

For more information about triggers, see the section Using triggers to customize behavior in the Helix Core Server Administrator Guide.

Configuring the trigger requires that you already have an admin bot account. For more information on setting up an admin bot account, see the Helix TeamHub User Guide, section Bots & programmatic repository access.

Note

Creating bots is not part of the TeamHub admin portal. You need to log out of <TeamHub-instance-URL>/admin/login and log on to <TeamHub-instance-URL>/login as company admin.

To set up the TeamHub trigger, you have the following options:

Depot installation (recommended)

Important

Trigger files cannot be stored in Graph depots.

  1. Copy the TeamHub trigger script file (/opt/hth/external/helix/triggers/hth-trigger.pl) and the trigger configuration file (/opt/hth/external/helix/triggers/hth-trigger.conf) from the TeamHub instance.

  2. Configure your triggers:

  3. The trigger by itself cannot run without connection to TeamHub. Edit the configuration file by specifying the values for the following variables:

    • HTH_HOST = Hostname of your TeamHub instance accessible from Helix Server (in the form of https://hostname or http://hostname)
    • HTH_COMPANY_KEY = Company key from your company admin bot settings in TeamHub, see Bot settings in the Helix TeamHub User Guide.
    • HTH_ACCOUNT_KEY = Account key for an admin bot account, see Bot settings in the Helix TeamHub User Guide.
    • VERIFY_SSL = Verification of the SSL certificate for TeamHub if running in SSL mode. Enabled by default.

  4. Submit the trigger script file and trigger configuration file to the depot. The recommended depot locations are:

    • //.hth/triggers/hth-trigger.pl

    • //.hth/triggers/hth-trigger.conf

  5. Note

    TeamHub does not create this depot. You either need to create it yourself or specify another depot.

    To create a //.hth depot, run the following as a user with admin-level privileges:

    $ p4 depot .hth

    For more information on creating and working with depots, see Working with depots in Helix Core Server Administrator Guide.

  6. As a Helix Server user with super privileges, edit the Helix Server trigger table by running the p4 triggers command and add the trigger including the initial tab character. For information about the p4 triggers command, see the p4 triggers section of the Helix Core Command-Line (P4) Reference.

    If you have copied the trigger script file and the trigger configuration file to the recommended locations, the trigger line will look similar to:

    hth.push-ref-complete graph-push-reference-complete //... "%//.hth/triggers/hth-trigger.pl% -c %//.hth/triggers/hth-trigger.conf% -t graph-push-reference-complete -d %depotName% -n %repo% -N %repoName% -p %pusher% -r %quote%%reference%%quote% -O %oldValue% -v %newValue%"

Filesystem installation

  1. Copy the TeamHub trigger file from the TeamHub instance to the server hosting Helix Server. The trigger file lives on the TeamHub instance at the following location: /opt/hth/external/helix/triggers/hth-trigger.pl
  2. If your Helix Server deployment uses the commit-edge architecture, you must also copy the script to all edge servers. In this case, make sure the script location has the same path on all servers.
  3. Copy the configuration file (/opt/hth/external/helix/triggers/hth-trigger.conf) to the same directory in Helix Server as the trigger file. If you copied the trigger script to the commit server and all edge servers in the previous step, also copy the configuration to the same directory on all servers.
  4. Configure your triggers:

  5. The trigger by itself cannot run without connection to TeamHub. Edit the configuration file by specifying the values for the following variables:

    • HTH_HOST = Hostname of your TeamHub instance accessible from Helix Server (in the form of https://hostname or http://hostname)
    • HTH_COMPANY_KEY = Company key from your company admin bot settings in TeamHub, see Bot settings in the Helix TeamHub User Guide.
    • HTH_ACCOUNT_KEY = Account key for an admin bot account, see Bot settings in the Helix TeamHub User Guide.
    • VERIFY_SSL = Verification of the SSL certificate for TeamHub if running in SSL mode. Enabled by default.

  6. To make sure that the script has execute permissions, run:

    chmod +x ./hth-trigger.pl

  7. In the filesystem location of your trigger script, run the following command to invoke it:

    ./hth-trigger.pl -o

    Note

    To see additional usage information, run the trigger script without any arguments.

  8. As a Helix Server user with super privileges, edit the Helix Server trigger table by running the p4 triggers command (P4 Command Reference) and adding the output lines from the previous command (including the initial tab character).

    Update the trigger script and configuration file paths in each line to reflect the actual paths on your Helix Server.

    Provided that you have copied the trigger script and configuration file to common paths on all servers, the trigger line will resemble the following:

    hth.push-ref-complete graph-push-reference-complete //... "%quote%/path/to/hth-trigger.pl%quote% -t graph-push-reference-complete -d %depotName% -n %repo% -N %repoName% -p %pusher% -r %quote%%reference%%quote% -O %oldValue% -v %newValue%"