Documentation (2024.2 Enterprise)

# Setting up trigger scripts

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.

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

- Perl 5.08+

- Perl Core on CentOS

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

Helix Core 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 Core 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 Core 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 Standard setup).

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

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

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)
- Filesystem installation

### Depot installation (recommended)

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:

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 Core 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.
- `HTH_ACCOUNT_KEY` = Account key for an admin bot account, see Bot settings.
- `VERIFY_SSL` = Verification of the SSL certificate for TeamHub if running in SSL mode. Enabled by default.

3. 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

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 Administration Documentation.

4. As a Helix Core Server user with super privileges, edit the Helix Core 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 Core 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 Core 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 Core 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:

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 Core 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.
- `HTH_ACCOUNT_KEY` = Account key for an admin bot account, see Bot settings.
- `VERIFY_SSL` = Verification of the SSL certificate for TeamHub if running in SSL mode. Enabled by default.

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

   chmod +x ./hth-trigger.pl

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

   ./hth-trigger.pl -o

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

7. As a Helix Core Server user with `super` privileges, edit the Helix Core 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 Core 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%"

Your search for returned results

Your search for returned results