GitIntegration package

Installing the GitIntegration package

Install the GitIntegration package by completing the following steps:

Open the Compass Designer.
Log in to the desired repository.
Right-click the reposority in the left sidebar and click Install Package.
In the Install Package Wizard, expand the GitIntegration package and choose version 1.0 of the package.
After the installation completes, click Finish, then OK.
In the left sidebar, expand to the desired repository and right-click on the schema that you want to apply the package to. Navigate into Packages, then click Apply Packages.
Expand the GitIntegration packages and choose version 1.0 of the package, then click Next.
Checkmark the record types to apply the package to, then click Finish. After the operation succeeds, click OK.
Check in the new version of the schema by right-clicking the version in the left sidebar and navigating to Revision Control, and then Checkin.
Upgrade the desired database with the new schema version by clicking the repository in the left sidebar where the package was installed and applied. Navigate to the Compass Database Admin tab at the bottom center of the Compass Designer. A Git tab is added to each of the selected record types in order to track Git events associated with them.
Right-click the database to upgrade with the new schema version and click Upgrade Database. Click the desired schema version and click OK.

Using an administrator account, create a record of type GIT_MasterConfig. Provide a list of user groups that should be allowed to create GIT_Config records. It is recommended, but not required, to create a group specifically for users with access to create GIT_Config records.
Create a GIT_Config record. This record configures GitHub events to be associated with a record type. Provide a name of the configuration, a secret to be used when the GitHub webhook is setup, and, optionally, a description. In the Enabled Record field, choose from a list of record types that the GitIntegration package is enabled for. References to GitHub events will be added to a Git tab within records of this type when they occur.
Using any API client, such as Postman or the command line, create an HTTP POST request to the REST API servers hookSetup endpoint. This enables the server for use with the GitIntegration package by creating a system use that can execute the necessary actions in Compass. The credentials that you provide in the payload should belong to a user that has permission to create users. API calls to the hookSetup endpoint can only be executed by a user with User Maintenance privileges.
Example URL: https://localhost:8190/ccmweb/rest/hookSetup
Example payload:
```
{
	"username": "admin",
	"password": "",
	"repo": "TestRepo",
	"db": "SAMPL"
}
```

In GitHub, a webhook must be created. Perform the following steps to create a webhook:

Click the Settings tab at the top of the repository that you want to connect to Compass.
Navigate to the Hooks tab and click the Add Webhook button.
In the Payload URL, provide the hostname and port of the Compass REST API server, combined with the following endpoint (with the applicable information filled in):
```
/ccmweb/rest/dbsets/{dbset name}/dbs/{db name}/services/webhooks/{GIT_Config name}
```
Example payload URL:
```
https://192.168.1.7:8190/ccmweb/rest/dbsets/2.0.1/dbs/SAMPL/services/webhooks/SampleConfig
```
Change the content type to application/json.
Provide the same secret value from the GIT_Config created earlier.
Choose the GitHub events that you would like to have sent to Compass. Currently, Compass supports the following events: push, pull request, branch creation, and branch deletion. The ping event is also supported in order for GirHub to verify the server status, if necessary.

After the initial setup is complete, using the GitIntegration package is simple.

Push: To connect a push event to a record in Compass, you must prefix the commit messages with the record ID. For example:
```
git commit -m "SAMPL00000001 Fixed the bug"
```
Branch creation and deletion: To connect a branch to a record in Compass, the branch name should match the desired Compass record. For example:
```
git checkout -b SAMPL00000001
```
You would then push this branch to the GitHub repository.
Deleting a branch that is connected to an Compass record will mark the branch accordingly in the records Git tab.
Pull requests: To connect a pull request to a record in Compass, the pull request must be made on a topic branch that is connected to an Compass record.
If you want record SAMPL00000001 to track pull requests, you must have a branch named SAMPL00000001. Then, create a pull request to merge the changes of that branch into the master branch. The pull request will then be listed in the records Git tab.