Creating hook scripts for Git integration
Hook scripts are required to integrate Git with Helix ALM. For example, a commit script is used to verify items exist in the Helix ALM project when committing changes to the local repository and a post receive script is used to attach files to items when changes are pushed to the Git server.
Use the external source control provider API to create scripts.
External source control provider API
The Helix ALM source control provider API collects data in JSON format and passes values to the Helix ALM source control CGI (ttextpro.exe) to confirm that items exist in the project and attach files to items. Use the following JSON property names when creating custom integration scripts.
providerKey
Required key for the provider. Automatically generated when you add the provider to Helix ALM. See Adding Git and other source control providers.
attachmentList
Required list of files to attach to the Helix ALM item.
attachment
File to attach to the Helix ALM item. Attachment objects include the following members: attachmentMessage, attachmentAuthor, branchName, toAttachList, toAttach, fileList, file, and custom user-defined parameters.
Attachment description. Displayed with file lists on the Source Files tab in Helix ALM items. Required to attach file lists to items. Not used for individual files.
Optional name for user attaching the file.
Optional branch name the attachment was added from.
Required list of toAttach objects to include the attachment in.
Object for the Helix ALM item to attach files to. Includes the following members: objectType and number.
Required Helix ALM item type to attach files to. Must be issue, test case, manual test run, requirement, or document.
Helix ALM item number to attach files to.
Optional list of changed file objects. If a file list without files in it is provided, the list is not attached to the item. If any file in a file list is missing the filename, the list is not attached to the item.
Object for the changed files as part of the attachment or an individual file to attach. If used to specify a group of files with changes, include the following members: fileName, changeType, and custom user-defined parameters.
Filename with changes. Required if attaching files as part of a file list.
Optional change action performed on the file (e.g., added, modified, removed).
Additional user-defined parameters
If you configured a custom commit or file URL for a Git or Other provider in Helix ALM, include all parameters specified in the URL. See Adding Git and other source control providers.
Examples
Commit URL
The following example shows expected JSON for the following sample commit URL:
http://myGitServer.internal.com/gitweb/?p=testRepo/.git;a=commit;h=<commitHash>
{
"providerKey" : "{12345678-9abc-01d2-3456-78e901fg2345}:{67890123-4567-4662-890h-i1j23k456lm7}",
"attachmentList" : [
{
"attachmentMessage" : "Fixed typo in error message IS-15",
"attachmentAuthor" : "aadams",
"branchName" : "master",
"toAttachList" : [
{
"objectType" : "issue",
"number" : 15
}
],
"commitHash" : "2c98532e2702828e0cfee8d02934c00e6dcfaa55",
"fileList" : [
{
"fileName" : "testDirectory/file.js",
"changeType" : "added"
},
{
"fileName" : "testOtherDirectory/otherFile.js",
"changeType" : "removed"
}
]
}
]
}
File URL
The following example shows expected JSON values for the following sample file URL:
http://myGitServer.internal.com/gitweb/?p=testRepo/.git;a=blobdiff;f=<fileName>;h=<fileHash>;hp=<fileParentHash>;hb=<commitHash>;hpb=<commitHashParent>
{
"providerKey" : "{12345678-9abc-01d2-3456-78e901fg2345}:{67890123-4567-4662-890h-i1j23k456lm7}",
"attachmentList" : [
{
"attachmentMessage" : "Fixed typo in error message IS-15",
"attachmentAuthor" : "aadams",
"toAttachList" : [
{
"objectType" : "issue",
"number" : 15
}
],
"commitHash" : "2c985322702828e0cfee8d029300e6dcfaa55",
"fileList" : [
{
"fileName" : "testDirectory/file.js",
"changeType" : "added",
"fileHash" : "0aa3a75ba5225a05b8c92d9c6cc2a5062137",
"fileParentHash" : "c54e179d613b406cf33604da9e5c700524c3",
"commitHash" : "2c98532e2702828e0cfee8d02934c00e6dc5",
"commitHashParent" : "457d902e537ddad68e27a1d6586630be52a3"
},
{
"fileName" : "someOtherDirectory/otherFile.js",
"changeType" : "removed",
"fileHash" : "082cef8d13634356990ae6b64b822f4c955d",
"fileParentHash" : "8d9771be943826d62b3c644dcc5b935a1543",
"commitHash" : "2c98532e2702828e0cfee8d02934c00e6dc5",
"commitHashParent" : "457d902e537ddad68e27a1d6586630be52a3"
}
]
}
]
}
Sample Git scripts
Sample Git integration scripts are available for download. These scripts are configured for Linux with Python and GitWeb, but you can use them as a reference to create your own custom scripts.
Perform the following steps to use the sample scripts.
1. In Helix ALM, add a Git provider with the following commit and file URLs. Replace the GitServer value with the address for your Git server. See Adding Git and other source control providers.
- Commit URL—http://yourGitServer/gitweb/?p=.git;a=commit;h=<commitHash>
- File URL—http://yourGitServer/gitweb/?p=.git;a=blobdiff;f=<fileName>;h=<fileHash>;hp=<commitHash>;hb=<fileParentHash>;hpb=<commitParentHash>
2. Download and unzip the sample scripts.
3. Open each script in a text editor and change the following configuration variables.
- URL—URL for the Helix ALM source control CGI on your web server (e.g., http://localhost/cgi-bin/ttextpro.exe).
- PROVIDER_KEY—Key from the Git provider configured in the Helix ALM project.
- ISSUE_TAG, TEST_CASE_TAG, and REQUIREMENT_TAG—Helix ALM item abbreviations that identify which items to attach source files to. You can use the default tags or specify different tags if item types are renamed in the project. For example, if you changed the Issue type field label to Defect in the project, you may want to set the ISSUE_TAG value to DF.
4. Install the post-receive script in the .git/hooks directory in the central repository on the Git server. If the repository is a bare repository, install the script in the hooks directory. If a post-receive hook script is already configured, you must integrate the scripts.
5. Install the commit-msg script in the .git/hooks directory in the local Git repository. If a commit-msg hook script is already configured, you must integrate the scripts.