Introduction:

If GitHub notified you that a repository webhook secret may have been exposed in HTTP headers, you need a new secret on the webhook CircleCI uses for GitHub OAuth pipelines. CircleCI registers that webhook with GitHub. You rotate it by removing and recreating the GitHub trigger for your GitHub OAuth pipeline. This article walks through those steps in the CircleCI web app.

A reference script is also available to automate this rotation using our API.

Prerequisites:

• Your project uses the GitHub OAuth app integration. Confirm this by checking that your project slug starts with github/.
• Your project has a GitHub OAuth trigger. You can check this under the GitHub OAuth pipeline in Project Settings → Project Setup, in the CircleCI web app.
• IMPORTANT: You have admin permissions on the GitHub repository your CircleCI project is connected to.

Instructions:

1. Note the current webhook hook ID in GitHub

   In your GitHub repository, go to Settings → Webhooks. Find the CircleCI webhook and click Edit — the hook ID is the number at the end of the URL (e.g., .../settings/hooks/<id>). This should match the ID referenced in GitHub's notification. Note it down so you can confirm it changes after rotation.
    

2. Open the Project Setup page for your project

   In the CircleCI web app, go to your project → Project Settings → Project Setup.
    

3. Locate the GitHub OAuth trigger

   Scroll to the GitHub OAuth pipeline card, and expand the Trigger featuring a GitHub icon.
    

4. Document the current trigger before deleting

   Before you delete the trigger, note the event name for your trigger so you can recreate the same behavior after rotation.
    

5. Delete the existing GitHub OAuth trigger

   Remove the OAuth trigger. This removes the associated webhook configuration in GitHub. 

   CircleCI manages webhook registration, so deleting the trigger is how you invalidate the old hook and secret.
    

6. Re-add the default OAuth trigger (or recreate your configuration)

   After deletion, the UI displays a link to re-add the default OAuth trigger ("To re-add the default OAuth trigger click here"). Use this link to recreate your trigger with the same configuration you documented in step 4.

   Recreating the trigger creates a new webhook registration in GitHub with a new secret.

   If you run into issues recreating the trigger, please report this through the feedback widget on the right of the screen. 
    

7. Confirm the new webhook in GitHub

   Go back to Settings → Webhooks in your GitHub repository and click Edit on the CircleCI webhook. The hook ID should be different from the one you noted in step 1, confirming the old webhook has been replaced.
    

8. Verify pipelines still run

   Push a small commit to confirm a new pipeline is created in CircleCI.

Reference script for API automated rotation:

A reference shell script has been created that demonstrates how our API can be used to accomplish the same webhook secret rotation without requiring manual action in our UI.

Outcome:

GitHub shows a new repository webhook (new URL path / hook id) for CircleCI, with a new secret. Pipelines should trigger as before once events match your recreated trigger configuration.

Additional Resources:

• Github gist: Reference script for automatic trigger recreation via API
• Docs: Set up triggers
• Docs: GitHub trigger event options
• Docs: Triggers overview
• Docs: Version control system integration overview
• GitHub: Editing webhooks
• GitHub: Validating webhook deliveries