Linking GitHub as a source

The GitHub connector syncs your repository data – issues, pull requests, commits, and more – into PostHog, so you can analyze engineering activity alongside your product data.

Prerequisites

You need access to the GitHub repository you want to sync. You can authenticate using OAuth (recommended), which connects your GitHub account automatically, or with a personal access token.

Adding a data source

In PostHog, go to the Sources tab of the data pipeline section.
Click + New source and click Link next to this source.
Enter your credentials (see Configuration below) and click Next.
Select the tables you want to sync, choose a sync method and frequency, then click Import.

Once the syncs are complete, you can start querying this data in PostHog.

When linking GitHub, choose an Authentication type:

OAuth (GitHub App) – the default and recommended method. Select your GitHub account and follow the prompts to connect it. This handles authentication automatically.
Personal access token – create a token in your GitHub Settings under Developer settings > Personal access tokens, then paste it into PostHog.

Then enter the Repository you want to sync in the format owner/repo (e.g. posthog/posthog).

Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
Incremental – only new or updated rows are synced on each run, using a cursor field (such as an updated_at timestamp). Cheaper than a full refresh, but deletes aren't captured.
Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See sync methods for a full explanation of how each mode works and how to choose between them.

Webhooks

The workflow runs and workflow jobs tables can be kept up to date in real time using a GitHub webhook, rather than re-polling. PostHog attempts to create the webhook automatically. If automatic creation fails, your token needs webhook permissions – the admin:repo_hook scope on a classic token, or Repository webhooks: read and write on a fine-grained token – or you can set the webhook up manually:

Go to your repository's Settings > Webhooks on GitHub
Click Add webhook
Paste the webhook URL shown during setup into the Payload URL field
Set Content type to application/json
Enter a Secret and add the same value to the Signing secret field in PostHog
Under Which events would you like to trigger this webhook?, choose Let me select individual events and tick Workflow jobs and Workflow runs
Click Add webhook

Configuration

Option	Type	Required
`Authentication type`	select	Yes
`Repository`	text	Yes

Supported tables

Table	Description	Sync method	Incremental field	Primary key
`issues`	An issue in the repository — a task, bug report, or feature request (pull requests are also returned here).	Incremental, Full refresh	updated_at, created_at	—
`pull_requests`	A request to merge changes from one branch into another in the repository.	Incremental, Full refresh	updated_at, created_at	—
`commits`	A commit in the repository's history.	Incremental, Full refresh	created_at	—
`stargazers`	A user who has starred the repository.	Full refresh	—	—
`releases`	A published release of the repository, tied to a git tag.	Full refresh	—	—
`workflow_runs`	A single execution of a GitHub Actions workflow.	Webhook, Incremental, Full refresh	created_at	—
`workflow_jobs`	A single job within a GitHub Actions workflow run.	Webhook only	created_at	—

Troubleshooting

If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.