Set up GitHub integration

Set up the integration with GitHub that enables Perforce Unified Compliance to access resource files for optimization in a deployment.

Deployments are single-tenant: you create and own a GitHub App used exclusively by your CDS instance. Because your CDS instance runs behind a firewall, GitHub cannot deliver webhook events to it directly. CDS polls GitHub for new events on a schedule instead. This requires a different setup from the SaaS integration.

The setup consists of two tasks:

• Register a GitHub App in GitHub.

• Enter the app credentials in the CDS VCS settings page, then restart the service.

Register the GitHub App

1. In GitHub, go to Organization Settings > Developer settings > GitHub Apps, then select New GitHub App.

2. Enter a name and a homepage URL for the app. Any valid URL for your organization is acceptable.

3. Under Webhook, leave Active selected, and enter a placeholder URL in the Webhook URL field — for example, https://placeholder.example.com/webhook. GitHub requires a URL to register the app, but CDS uses polling rather than webhook delivery, so this URL is not called after registration.

4. Under Permissions, set the following repository permissions:

   • Contents: Read

   • Issues: Read and write

   • Pull requests: Read and write

5. Under Subscribe to events, select the following events:

   • Pull request

   • Push

6. Select Create GitHub App.

Generate the credentials

1. After creating the app, record the App ID and App name displayed on the app settings page. You need them in the next sections.

2. Under Private keys, click Generate a private key, which downloads a .pem file. Store it securely; it can't be re-downloaded, only regenerated.

Install the GitHub App

1. On the app's settings page in GitHub, select Install App.

2. Install the app in the organization or repositories that should connect to Perforce Unified Compliance.

Create a fine-grained personal access token

You must use a fine-grained PAT for this integration. Classic PATs do not support Copilot coding-agent assignment, regardless of scope, and do not work.

Under Repository access, select Only select repositories and choose only the repositories this CDS instance integrates with. Avoid All repositories because it grants the PAT access to every repository in the organization, which is broader than the integration needs.

When creating the PAT, grant the following permissions:

Permission	Access level
Metadata	Read
Issues	Read and write
Pull requests	Read and write

Enter credentials in CDS

1. In the CDS interface, go to Integrations > GitHub App.

2. Enter the App ID, App name, the fine-grained PAT you created, and the .pem file containing your Private Key.

3. Save the settings.

Restart the CDS service

After saving, restart the CDS service. The integration services start only when credentials are present at service startup. Saving credentials in the UI does not start polling, only a service restart does.

After the restart, Perforce Unified Compliance automatically discovers the app's installations. To verify the integration is active, make a change in a connected repository, such as a test commit or pull request. If polling is working, the change should appear in Perforce Unified Compliance within approximately 30 seconds.