How to Configure Teamscale to use Post-Commit Hooks

By default, Teamscale uses a poll mechanism to regularly check for new revisions on the server. Depending on the polling interval you configured, this can lead to a large delay between the actual commit and the update of the data in Teamscale, or to a very high load on your version control system server (especially with many projects).

One solution to this problem are post-commit hooks, which are supported by many version control systems.

TIP

If you want to connect to a code collaboration platform like GitHub or Azure DevOps, you can use the dedicated code connector for that platform. This will automatically setup the post-commit hooks for you. Moreover, you can get even tighter integration by allowing Teamscale to vote and comment on merge requests.

• Post-Commit Hooks for Subversion
• Post-Commit Hooks for Azure DevOps / Team Foundation Server
  • Azure DevOps Service Hooks
  • Legacy Team Foundation Server Alerts
• Code Collaboration Platforms
  • Disable Automatic Webhook Creation
  • Decrease Polling Interval for Merge Request Changes

In general, you configure the Teamscale project with a large polling interval. Polling will still happen from time to time as a fallback if the post-commit hook failed for some reason. Then you have to configure your version control system to call the following URL after each commit:

http://teamscale.company.com/api/post-commit-hook?repository=REPOSITORY

Here the part http://teamscale.company.com/ is the URL of your teamscale server. Authentication happens via HTTP Basic Authentication and requires a user name and the user's access key (not the password). The REPOSITORY is the URL of the repository as configured in Teamscale. For example, if you have a project reading from the Subversion repository http://svn.company.com/project1/trunk/foo , the URL may be http://svn.company.com/project1/trunk/foo or any prefix, such as http://svn.company.com/project1/ or even http://svn.company.com/ . Note that all projects for which the prefix matches will be checked for updates, so a more specific prefix can help to reduce the server load. However, being too specific does not work. If you pass http://svn.company.com/project1/trunk/foo/some/file as repository parameter, the prefix match will fail and no update is triggered.

You can use POST requests to call the URL.

Post-Commit Hooks for Subversion

Subversion supports the execution of arbitrary (shell) scripts for various hooks. The hook that should be used is called post-commit. To access the URL you can use the tools wget or curl. See the SVN book for more details on configuration of commit hooks.

Post-Commit Hooks for Azure DevOps / Team Foundation Server

In Azure DevOps users can configure commit hooks with custom alerts and service hooks (version 2015+). Both are available via the admin settings for a team project (gear icon in the top loft corner).

For both methods the REPOSITORY parameter of the URL to the Teamscale commit hook service (as described above) is TFS_URL/TEAM_COLLECTION/FOLDER_PATH , e.g.
http://yourcompany.com/tfs/DefaultCollection/$

/MyProject/Dev/Source .

Azure DevOps Service Hooks

Service Hooks are the successor of Alerts and available in Visual Studio Team Services and Team Foundation Server 2015 onwards. They are easier to set-up and provide debug information if a request fails.

Switch to the Service Hooks tab, create a new subscription and select Web Hooks as type of service. Change the trigger type to Code checked in and enter the TFS repository path you want to monitor for changes:

If you are hosting a Git repository via Team Foundation Server you have to select Code pushed as event type and simply select the repository you want to monitor for changes. Optionally you can restrict the event to only be fired if a specific branch is pushed.

After clicking Next you have to enter the URL of the commit hook:

All other fields can be left empty and it is not required to send any further data to teamscale at all.

The user who creates the subscription needs to have the TFS permission Edit subscriptions and View subscriptions. See https://docs.microsoft.com/en-us/azure/devops/service-hooks/overview?view=azure-devops for further information.

Legacy Team Foundation Server Alerts

Deprecation

Service Hooks (available since Azure DevOps version 2015 onwards) are the successor of Alerts and should be used if possible..

Switch to the alerts tab and create a new alert of type A file is checked in under a specified path:

Then alter the following fields as shown here:

• Name: Alter the name to something that reminds you this is the commit hook for Teamscale.

• Send To: The commit hook url.

• Format: Change to SOAP.

• Filter Value: Change from $/ to the folder path used in the commit hook, e.g.$/MyProject/Dev/Source .

If you are hosting a Git repository via Team Foundation Server you have to select the alert type Push > A commit is pushed to a specified repository. The Send To and Format fields have to specified in the same way as described above.

If you receive an error on save saying that the user needs the right Create a SOAP subscription, an administrator has to issue the following command (e.g., from VisualStudio Command Prompt):

tfssecurity.exe /a+ EventSubscription $SUBSCRIPTION:CREATE_SOAP_SUBSCRIPTION n:DOMAIN\USERNAME ALLOW
/collection:TFS_URL/TEAM_COLLECTION

Ensure to substitute DOMAIN and USERNAME with the login of the account you want to create the alert for and TFS_URL/TEAM_COLLECTION with the url to your TFS Team Collection.

Code Collaboration Platforms

Connectors to code collaboration platforms create hooks automatically upon creation of a project in Teamscale. The hooks are used to determine whenever new code has been pushed or merge requests have been created or changed. However, this only works if:

• The Teamscale server is reachable from the code collaboration platform
• The user account Teamscale uses to access the code collaboration platform has sufficient privileges to create hooks

Disable Automatic Webhook Creation

If any of the above conditions do not meet, you should disable the automatic creation of webhooks. This can be done by setting the corresponding expert option in the repository connector.

You may also adjust the default value for this option globally for your instance by passing the following JVM argument on the start of Teamscale:

-Dcom.teamscale.mergerequest.disable-automatic-webhook-creation-default=true

WARNING

This value can be overridden by project-specific settings.

In case of missing privileges, you can manually create the needed webhooks instead. Please refer to the documentation of the specific code collaboration platform connector for the concrete URL and which events need to be processed.

Otherwise, you should decrease the Polling interval of the code connector to e.g. 600 or 60 seconds.

Decrease Polling Interval for Merge Request Changes

Besides polling for code changes, Teamscale also polls the code collaboration platform for changes regarding merge requests, e.g., whether a merge request has been newly created, merged or deleted. This polling mechanism only acts as a safety net when a webhook from the code collaboration platform is missed. Hence, it is only executed once a day.

If the code collaboration platform cannot reach Teamscale via a web hook at all, you should decrease the polling interval. This can be done by passing the following JVM argument on the start of Teamscale:

-Dcom.teamscale.mergerequest.polling_interval_seconds=600

WARNING

After you have changed this value, Teamscale projects using a connector to a code collaboration platforms need to be reanalyzed in order for the setting to take effect.