Creating hook scripts for Git integration

Hook scripts are required to integrate Git with Perforce ALM. For example, a commit script is used to verify items exist in the 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. See External source control provider API.

External source control provider API

The Perforce ALM source control provider API collects data in JSON format and passes values to the 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 ALM. See Adding Git and other source control providers.

attachmentList

Required list of files to attach to the ALM item.

attachment

File to attach to the ALM item. Attachment objects include the following members: attachmentMessage, attachmentAuthor, branchName, toAttachList, toAttach, fileList, file, and custom user-defined parameters.

attachmentMessage

Attachment description. Displayed with file lists on the Source Files tab in ALM items. Required to attach file lists to items. Not used for individual files.

attachmentAuthor

Optional name for user attaching the file.

branchName

Optional branch name the attachment was added from.

toAttachList

Required list of toAttach objects to include the attachment in.

toAttach

Object for the Perforce ALM item to attach files to. Includes the following members: objectType and number.

objectType

Required ALM item type to attach files to. Must be issue, test case, manual test run, requirement, or document.

number

ALM item number to attach files to.

fileList

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.

file

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

Filename with changes. Required if attaching files as part of a file list.

changeType

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

{

}

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>

{

}

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

• commit-msg
• post-receive

3. Open each script in a text editor and change the following configuration variables.

• URL—URL for the 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 ALM project.
• ISSUE_TAG, TEST_CASE_TAG, and REQUIREMENT_TAG—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.