When a developer uses a GitHub webhook to create a branch from an item, P4 Plan can automatically link every commit and pull request on that branch to the item. This requires an administrator to set up incoming webhooks.
For information on installing and setting up incoming webhooks, see Installing incoming webhooks.
To set up automatic linking, you will need the following:
- P4 Plan Web [release version] or later, with the Integrations service running.
- A GitHub webhook in P4 Plan with a green status. See GitHub webhooks.
- A public hostname that GitHub can reach. For example:
plan-webhooks.example.com. - One open port. The examples use
8443. - A certificate for the port. By default it's the web client certificate. See .
Updating GitHub webhook settings for automatic linking
To enable incoming webhooks, you need to create a new webhook or edit an existing one, using the following steps:
1. Make sure that the Repository URL uses this format: https://github.com/<owner>/<repo>.
Replace <owner> and <repo> to match the desired URL.
2. If you are creating a new webhook, select Activate 2-way sync.
3. Enter a GitHub Webhook Secret.
If you want to keep the current secret, you can leave this field empty.
4. Use a long random value, for example openssl rand -hex 32.
You'll enter the same value in GitHub.
5. Make sure Active is selected.
Updating GitHub app settings for automatic linking
To enable incoming webhooks, you need to configure your GitHub app using the following settings.
In GitHub, go to Settings > Developer settings > GitHub Apps > your app. Then apply the following settings:
| Setting | Value |
|---|---|
| Webhook → Active | Selected |
| Webhook URL | https://<your-public-hostname>:8443/incoming-webhooks/github
|
| Webhook secret |
The same as GitHub Webhook Secret in P4 Plan. The Webhook secret field, not a client secret. A GitHub App has one webhook secret. If you use the same app for several repositories, use the same secret on all their webhooks in P4 Plan.
|
| SSL verification | Keep it enabled if your certificate is publicly trusted. Select Disable for self-signed or internal certificates. |
| Subscribe to events | Push and Pull request only. Other events fail with 401. |
| Credentials → Key pairs | The private key you pasted in P4 Plan. P4 Plan doesn't use Client secrets, you can leave that tab empty. |
| Install App | On the repositories you use in P4 Plan. |
Testing GitHub incoming webhooks
When you have configured everything, you can use the following steps to test that it works:
1. From outside your network, check that the port is reachable:
curl -k -X POST https://<your-public-hostname>:8443/incoming-webhooks/github -d '{}'You should get 401. That means the request reached P4 Plan and was rejected because it isn't signed, which is correct. 404 means the feature isn't turned on.
2. Create a branch from an item with Create branch, push a commit to it, and check the item's Links tab.
The commit should show up within a few seconds.
3. Open GitHub, and access your app.
4. Go to Advanced > Recent Deliveries.
The push should have a green check. You can select it and choose Redeliver to test again.