Configuring commit hooks

The incremental indexing process causes FishEye 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 FishEye.
A high load on the FishEye 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 FishEye only runs the indexing process when necessary, and allows automatic polling to be disabled. Commits will appear sooner in FishEye, and the server load will be reduced.

To set up commit hooks you:

Set the REST API token in FishEye/Crucible.
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 FishEye scanning when your repository is updated.

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

echo Triggerring FishEye scan
/usr/bin/curl -X POST -H "X-Api-Key: YOUR-API-TOKEN-HERE"  http://SERVER:PORT/CONTEXT/rest-service-fecru/admin/repositories-v1/REPOSITORY-NAME/scan

Try running the script; if everything is fine, it will output "[]", and will trigger scanning in FishEye. 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 FishEye.

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

Checkout the CVSROOT module of your cvs repository:
```
cvs co CVSROOT
```
Edit the CVSROOT/loginfo file.

Add the following line to the file:

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

Commit your changes:
```
cvs commit CVSROOT/loginfo
```

SVN

Log into your svn server, go to the repository directory, find the hooks subdirectory there:
```
cd /var/www/svn/hooks
```
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
```
Make sure the file starts with the following shebang line, pointing to your shell:
```
#!/bin/sh
```

Add the following to the post-commit file:

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

You can find more details about svn hooks here.

Perforce

As a Perforce administrator execute the following command:
```
p4 triggers
```
The trigger table form will be presented.

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 http://SERVER:PORT/CONTEXT/rest-service-fecru/admin/repositories-v1/PERFORCE-REPOSITORY-NAME/scan

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

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.
Go to the hooks subdirectory of your repository:
```
cd /var/www/git/project/hooks
```
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
```
Make sure the file starts with the following line, pointing to your shell:
```
#!/bin/sh
```

Add the following to the post-receive file:

/usr/bin/curl -X POST -H "X-Api-Key: YOUR-API-KEY-HERE" -m 20 http://SERVER:PORT/CONTEXT/rest-service-fecru/admin/repositories-v1/GIT-REPOSITORY-NAME/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

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.
Go to the .hg subdirectory of your repository:
```
cd /var/www/hg/project/.hg
```
If it doesn't exist create a file named hgrc:
```
touch ./hgrc
```

Add the following to the hgrc file:

[hooks]
changegroup = /usr/bin/curl -X POST -H "X-Api-Key: YOUR-API-KEY-HERE" -m 20 http://SERVER:PORT/CONTEXT/rest-service-fecru/admin/repositories-v1/HG-REPOSITORY-NAME/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 FishEye 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 FishEye. This will decrease the server load, but allow FishEye to still ocassionally check for changes, and update the repository if needed. Note that after changing the polling frequency, FishEye will need to be restarted.

Child pages