Connect GitHub

To let the IDP trigger GitHub Actions workflows and receive their status, you connect a GitHub App. This is the mechanism used by the Deploy Stack (GitHub Actions) and Full-Stack Release workflows in the demo.

1. Create a GitHub App

In GitHub: Settings → Developer settings → GitHub Apps → New GitHub App (create it under your GitHub organization, e.g. idpnextdemo).

Configure:

• Webhook URL: https://<your-idp-domain>/api/v1/github/webhook
• Webhook secret: generate a random string — you'll give the same value to the IDP.
• Repository permissions:
  • Actions: Read and write (to dispatch workflow_dispatch runs)
  • Contents: Read-only
  • Metadata: Read-only
• Subscribe to events: tick Workflow run ⚠️

Don't skip the "Workflow run" event

If Subscribe to events → Workflow run is not ticked, GitHub sends zero webhooks and workflow steps in the IDP only complete via slow reconciliation polling. This is the single most common misconfiguration.

Then Install the App on your organization (all repositories, or at least the ones your workflows will dispatch to), and collect:

• App ID (e.g. 4299268 in the demo)
• Private key (.pem file, downloaded from the App page)
• Installation ID (visible in the installation URL)

2. Register the App in the IDP

Set the credentials in the backend environment (e.g. docker-compose.override.yml on the server):

services:
  backend:
    environment:
      - GITHUB_APP_ID=4299268
      - GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
      - GITHUB_WEBHOOK_SECRET=<the webhook secret from step 1>

GITHUB_WEBHOOK_SECRET must be non-empty

The GitHub integration does not initialize without a webhook secret, and unsigned webhook deliveries are rejected.

Then register the installation via the API (or the /github/setup page):

curl -X POST "https://<your-idp-domain>/api/v1/github/setup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"installationId": 146607536}'

This creates a github integration config visible under Admin → Data sources.

3. Verify

1. Open Admin → Data sources — the GitHub integration should be listed.
2. Later, when you run a workflow with a GitHub step (Part 5), the run log shows GitHub workflow run #<id> within seconds and the step completes when the Actions run finishes.

Alternative: credentials per step from a Secret

Instead of the global environment credentials, individual workflow steps can use a stored secret of type GitHub App (see Secrets & Step Credentials). The demo's release-full-stack workflow uses this:

"credentials": {
  "source": "secret",
  "version": "latest",
  "secretIdentifier": "idpnetxdemo-github-app"
}

Next: ingest your catalog with Ocean →