GitHub Connector
The GitHub connector ingests data from a GitHub organization into the Catalog. It runs through the ibdm binary in one of two modes:
- Sync — pull-based: queries the GitHub REST API and exits.
- Run — push-based: exposes a webhook endpoint that receives GitHub organization events.
GitHub Enterprise Server is supported by overriding GITHUB_URL.
Commands
ibdm sync github --include-internal-mappings=all
ibdm run github --include-internal-mappings=all
The commands use every internal mapping of the source. To select only some of them, or to add mappings of your own, see Mappings.
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
GITHUB_TOKEN | Yes | (empty) | GitHub personal access token (classic) or fine-grained token with the required scopes. |
GITHUB_ORG | Yes | (empty) | GitHub organization to synchronize. |
GITHUB_URL | No | https://api.github.com | Base URL of the GitHub API. Override for GitHub Enterprise Server (e.g. https://github.example.com/api/v3). |
GITHUB_HTTP_TIMEOUT | No | 30s | HTTP request timeout (Go duration). |
GITHUB_PAGE_SIZE | No | 100 | Items per API page (1–100). |
GITHUB_WEBHOOK_SECRET | Run | (empty) | HMAC secret for webhook signature verification. |
GITHUB_WEBHOOK_PATH | No | /github/webhook | HTTP path for inbound webhook events. |
Authentication
- Personal Access Token (classic): required scopes
repoandread:org. - Fine-grained Personal Access Token: required permissions at organization level — Repository → Metadata: Read-only, Organization → Members: Read-only.
Supported data types
| Type | Sync | Webhook |
|---|---|---|
repository | ✅ | ✅ |
workflow_run | ✅ | ✅ |
personal_access_token_request | — | ✅ |
workflow_dispatch | — | ✅ |
Webhook actions per type
| Type | Actions → Upsert | Actions → Delete |
|---|---|---|
repository | created, edited, renamed, archived, unarchived, transferred, publicized, privatized | deleted |
workflow_run | requested, in_progress, completed | — |
personal_access_token_request | approved, created | cancelled, denied |
workflow_dispatch | (all — no action field) | — |
GitHub's push webhook event is also handled: it does not add a new data type, but re-upserts the corresponding repository item (refreshing repositoryLanguages). Subscribing only to the Repositories event, as in step 5 below, does not include push events — subscribe to Pushes as well if you want repository items refreshed on every push, not just on repository metadata changes.
Repository languages enrichment
Whenever a repository item is produced (sync or webhook), ibdm calls GET /repos/{owner}/{repo}/languages and adds a repositoryLanguages field to the mapping context — a JSON object mapping each language to its percentage share, rounded to two decimal places:
{ "Go": 97.50, "Makefile": 2.43, "Dockerfile": 0.07 }
If the languages call fails, the repository item is still emitted without repositoryLanguages.
Internal mappings
ibdm mappings list github prints the internal mappings of this source, and the Internal Mappings reference lists the Item Type each one writes.
| Internal mapping | Sync | Webhook | Its relationships point at |
|---|---|---|---|
repositories | ✅ | ✅ on repository and push events | — |
workflowruns | ✅ for every repository | ✅ on workflow_run events | repositories |
The sync lists the repositories of the organization as soon as either mapping is selected, and fetches the workflow runs of each repository while listing them. Selecting workflowruns alone works, but its items then relate to repository items that nothing creates: select repositories too.
personal_access_token_request and workflow_dispatch have no internal mapping. An external mapping for either type can only be produced by ibdm run github: declare it syncable: false.
Setting up a GitHub webhook
- Go to your GitHub organization's Settings → Webhooks → Add webhook.
- Set Payload URL to your public
ibdmURL followed byGITHUB_WEBHOOK_PATH(default/github/webhook). - Set Content type to
application/json. - Set Secret to the value of
GITHUB_WEBHOOK_SECRET. - Subscribe to the events that match the data types you want:
- Repositories →
repository - Workflow runs →
workflow_run - Personal access token requests →
personal_access_token_request - Workflow dispatches →
workflow_dispatch - Pushes (optional) → refreshes the corresponding
repositoryitem on every push, see note above
- Repositories →
See also
- Connectors Installation Overview
- GitLab Connector, Bitbucket Connector — sibling source-code hosting connectors.