Configuring commit hooks

The incremental indexing process causes Crucible to poll all repositories at the specified interval to check for new commits, even though there might not be any new information to index. If you have a large number of repositories (> 100), this can lead to:

  • A time lag between a commit being made and it appearing in Crucible.
  • A high load on the Crucible server, and on the SCM.

Commit hooks allow you to set up your SCM so that indexing of a repository is triggered by a commit to the repository itself. This means that Crucible only runs the indexing process when necessary, and allows automatic polling to be disabled. Commits will appear sooner in Crucible, and the server load will be reduced.

To set up commit hooks you:

  1. Set the REST API token in Fisheye or Crucible. See the Fisheye-Crucible REST API developer documentation.
  2. Integrate the commit hook with your SCM.

On this page:

Triggering scanning remotely

Once you've set your REST API token you can use it to trigger scanning when your repository is updated.

The basic way to do this is set up a shell script similar to:

echo Triggerring scan
/usr/bin/curl -X POST -H "X-Api-Key: <YOUR-API-KEY-HERE>"  <URL>:<PORT></optional CONTEXT>/rest-service-fecru/admin/repositories-v1/<REPOSITORY-NAME>/scan

e.g.

echo Triggerring scan
/usr/bin/curl -X POST -H "X-Api-Key: abcdefg123456" http://atlas:8060/fecru/rest-service-fecru/admin/repositories-v1/widget/scan

Try running the script; if everything is fine, it will output "[]", and will trigger scanning in Crucible. If there are problems, curl will show an appropriate message.

If you're running on Windows, you'll need curl or a similar program. You can download the Windows version of curl here. You'll need to save the script as a batch file (with the .bat extension).

Note: be sure to specify the full path to the curl binary on your system.

Integrating with your SCM

BItbucket and GitHub

Both of these hosting services provide service hooks that can be used to trigger repository indexing in Crucible.

Bitbucket

In Bitbucket, go to the admin page for your repository, click Hooks and choose Fisheye.

See the Bitbucket documentation for more information about setting up a Bitbucket service hook.

GitHub

In GitHub, go to the admin page for your repository, click Service Hooks and choose Fisheye from the available hooks.

CVS

  1. Checkout the CVSROOT module of your cvs repository:

    cvs co CVSROOT
  2. Edit the CVSROOT/loginfo file.

  3. Add the following line to the file:

    ALL /usr/bin/curl -X POST -H "X-Api-Key: <YOUR-API-KEY-HERE>" -m 20 <URL>:<PORT></optional CONTEXT>/rest-service-fecru/admin/repositories-v1/<CVS-REPOSITORY-NAME>/scan > /dev/null 2>&1 &

    e.g.

    ALL /usr/bin/curl -X POST -H "X-Api-Key: abcdefg123456" http://atlas:8060/fecru/rest-service-fecru/admin/repositories-v1/cvs_widget/scan > /dev/null 2>&1 &
  4. Commit your changes:

    cvs commit CVSROOT/loginfo

SVN

  1. Log into your svn server, go to the repository directory, find the hooks subdirectory there:

    cd /var/www/svn/hooks
  2. If it doesn't exist, create a new file called post-commit ( or post-commit.bat on Windows), make sure it's executable by the user that the svn process runs as:

    touch ./post-commit
    chmod 755 ./post-commit
  3. Make sure the file starts with the following shebang line, pointing to your shell:

    #!/bin/sh
  4. Add the following to the post-commit file:

    /usr/bin/curl -X POST -H "X-Api-Key: <YOUR-API-KEY-HERE>" -m 20 <URL>:<PORT></optional CONTEXT>/rest-service-fecru/admin/repositories-v1/<SVN-REPOSITORY-NAME>/scan > /dev/null 2>&1 &

    e.g.

    /usr/bin/curl -X POST -H "X-Api-Key: abcdefg123456" http://atlas:8060/fecru/rest-service-fecru/admin/repositories-v1/svn_widget/scan > /dev/null 2>&1 &

    You can find more details about svn hooks here.

Perforce

  1. As a Perforce administrator execute the following command:

    p4 triggers
  2. The trigger table form will be presented.
  3. Add a field value for the field 'Triggers', named trigger-X, where X is the next number available for the trigger:

    trigger-04 change-commit //... "/usr/bin/curl -s -o /dev/null -X POST -H X-Api-Key:<YOUR-API-KEY-HERE> -m 20 <URL>:<PORT></optional CONTEXT>/rest-service-fecru/admin/repositories-v1/<PERFORCE-REPOSITORY-NAME>/scan

    e.g.

    trigger-04 change-commit //... "/usr/bin/curl -s -o /dev/null -X POST -H "X-Api-Key: abcdefg123456" http://atlas:8060/fecru/rest-service-fecru/admin/repositories-v1/perforce_widget/scan
  4. You can customize the trigger to run only for a specific depot or directory, by replacing the //... above (which causes the trigger to be executed for every file) by a standard Perforce file pattern syntax.

You can find more details about Perforce triggers in the Perforce System Administrator's guide.

Git

  1. Choose the repository you want to trigger the scans from. Usually this is the repository that all of your developers push to, and that you run CI from. Note that hooks are not propagated when cloning repositories.

  2. Go to the hooks subdirectory of your repository:

    cd /var/www/git/project/hooks
  3. If it doesn't exist, create a new file called post-receive. Make sure it's executable by the Git server process.

    touch ./post-receive
    chmod 755 ./post-receive
  4. Make sure the file starts with the following line, pointing to your shell:

    #!/bin/sh
  5. Add the following to the post-receive file:

    /usr/bin/curl -X POST -H "X-Api-Key: <YOUR-API-KEY-HERE>" -m 20 <URL>:<PORT></optional CONTEXT>/rest-service-fecru/admin/repositories-v1/<GIT-REPOSITORY-NAME>/scan > /dev/null 2>&1 &

    e.g.

    /usr/bin/curl -X POST -H "X-Api-Key: abcdefg123456" http://atlas:8060/fecru/rest-service-fecru/admin/repositories-v1/git_widget/scan > /dev/null 2>&1 &

NOTE: Not all methods of serving a Git repository support commit hooks - if serving over http, you need to use smart-http (either using git-httpd-backend or a dedicated repository manager like gitolite). You can find more information about smart http here. Serving the repository over ssh or git-daemon should allow you to run commit hooks as well.

Mercurial

  1. Choose the repository you want to trigger the scans from. Usually this is the repository that all of your developers push to, and that you run CI from. Note that hooks are not propagated when cloning repositories.
  2. Go to the .hg subdirectory of your repository:

    cd /var/www/hg/project/.hg
  3. If it doesn't exist create a file named hgrc:

     

    touch ./hgrc
  4. Add the following to the hgrc file:

    [hooks]
    changegroup = /usr/bin/curl -X POST -H "X-Api-Key: <YOUR-API-KEY-HERE>" -m 20 <URL>:<PORT></optional CONTEXT>/rest-service-fecru/admin/repositories-v1/<HG-REPOSITORY-NAME>/scan > /dev/null 2>&1 &

    e.g.

    [hooks]
    changegroup = /usr/bin/curl -X POST -H "X-Api-Key: abcdefg123456" http://atlas:8060/fecru/rest-service-fecru/admin/repositories-v1/hg_widget/scan > /dev/null 2>&1 &

NOTE: Not all methods of serving a Mercurial repository support commit hooks - if serving over http, you can't use static-http serving.

Decreasing polling frequency

Once your commit hook is set up and successfully notifying Crucible about new commits to your repository, you can decrease the polling frequency on your repository (for example to 1 or 2 hours, instead of the default 1 minute).

With commit hooks configured, scheduled polling is only useful if the hook fails,for example because of connectivity issues to the server hosting Crucible. This will decrease the server load, but allow Crucible to still occasionally check for changes, and update the repository if needed. Note that after changing the polling frequency, Crucible will need to be restarted.

 

trigger-04 change-commit //... "/usr/bin/curl -s -o /dev/null -X POST -H X-Api-Key:YOUR-API-KEY-HERE -m 20 http://SERVER:PORT/CONTEXT/rest-service-fecru/admin/repositories-v1/PERFORCE-REPOSITORY-NAME/scan
Last modified on Jul 31, 2018

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.