GitHub
Contents
The PostHog GitHub App connects your GitHub organization or account to PostHog. Several products build on it:
- Self-driving and PostHog Desktop run agents against your repositories, open pull requests, and post review comments.
- Error tracking creates GitHub issues from errors and links pull requests back to them.
- Data warehouse syncs issues, pull requests, and commits from your repositories as tables.
You can connect GitHub from the PostHog web app or from PostHog Desktop. Both use the same installation, so a connection made in one shows up in the other. Pick where you're connecting from:
Where GitHub lives in the web app
- Settings → Integrations → GitHub integration holds the project connection. Anyone on the project can use it, and project admins manage it.
- Settings → Personal integrations → GitHub holds your personal connection, which agents use to act as you.
Connect the app
- Go to Settings → Integrations → GitHub integration and click Connect account.
- GitHub asks which organization or account to install the app on, and which repositories it can access.
- After you approve, GitHub sends you back to PostHog. The integration card shows the account name and its repository access.
Connecting as a project admin also links your personal account to the same installation, so you don't need to connect twice.
To add a personal connection on its own, go to Settings → Personal integrations → GitHub and click Connect GitHub (or Add account/organization if you already have one).
If the app is already installed on GitHub
The app installs once per organization, so a second PostHog project can't install it again. When PostHog can see an existing installation on one of your GitHub accounts, the integration card says so and offers Connect to [project]. That links the installation without leaving PostHog.
If the card doesn't offer it, connect your GitHub account under Personal integrations first so PostHog can find the installation.
If you're not an organization owner
GitHub only lets organization owners install apps. If you're a member, GitHub records an install request and notifies the owners instead of installing.
Back in PostHog, the GitHub integration card shows a notice that GitHub sent your request to your organization owners, with Copy message for your org owner so you can nudge one. Once an owner approves, the notice changes and you click Finish connecting to link the installation to your project.
If you're not a project admin
Connecting GitHub for a project needs admin access. Without it, the GitHub integration page shows a short form instead of a connect button. Write why your team needs it and click Request GitHub. Your project admins get an email and can connect it for you.
Disconnect
- Project: on the GitHub integration card, click Disconnect next to the connection.
- Personal: under Personal integrations → GitHub, click the disconnect icon on the account row.
Read What disconnecting does before you confirm.
Where GitHub lives in PostHog Desktop
Open Settings → GitHub. The page has two sections:
- Project connection is the installation this project uses for Self-driving and cloud tasks. Project admins manage it.
- Your GitHub account lists the personal installations linked to your PostHog user, which agents use to act as you.
Advanced settings in PostHog at the bottom of the page opens the same integration in the web app.
Connect the app
- Under Project connection, click Connect GitHub.
- GitHub asks which organization or account to install the app on, and which repositories it can access.
- After you approve, GitHub sends you back to PostHog Desktop. The row shows the account name and its repository access, and Manage opens the installation on GitHub.
Connecting as a project admin also links your personal account to the same installation, so you don't need to connect twice.
To add a personal connection on its own, click Connect GitHub in the Your GitHub account section. Members who aren't project admins only get a personal connection this way. The project stays unconnected until an admin connects it.
If the app is already installed on GitHub
The app installs once per organization, so a second PostHog project can't install it again. Click Advanced settings in PostHog to open the web app, where the integration card offers Connect to [project] for an installation PostHog can already see.
If you're not an organization owner
GitHub only lets organization owners install apps. If you're a member, GitHub records an install request and notifies the owners instead of installing.
Back in PostHog Desktop, the Project connection section shows a notice that GitHub sent your request to your organization owners, with Copy message for your org owner so you can nudge one. Once an owner approves, the notice changes and you click Finish connecting to link the installation to your project.
If you're not a project admin
Connecting GitHub for a project needs admin access. Without it, the Project connection section shows a short form instead of a connect button. Write why you need it and click Ask a project admin. Your project admins get an email and can connect it for you.
Disconnect
Each connection row has a Disconnect button, in both the Project connection and Your GitHub account sections. Read What disconnecting does before you confirm.
All repositories or selected repositories
GitHub asks whether the app can see all repositories in the account or only select repositories. PostHog shows which one you picked:
- With all repositories, PostHog shows the total count instead of listing every repository. New repositories are visible to PostHog automatically.
- With selected repositories, PostHog lists the repositories you picked.
To change the selection later, open the installation on GitHub (Manage on GitHub in the web app, Manage in PostHog Desktop). PostHog picks up the change on the next refresh.
The app requests read access to metadata and read and write access to code, issues, and pull requests. GitHub shows the exact list on the install screen.
Project connection and personal connection
A GitHub installation can be linked to PostHog in two ways:
| Connection | Scope | Used for |
|---|---|---|
| Project connection | One PostHog project | Self-driving, cloud tasks, error tracking issues, data warehouse GitHub source. Anyone on the project can use it, and project admins manage it. |
| Your GitHub account | Your PostHog user, across projects | Agents acting as you: commits, pull requests, and review comments attributed to your GitHub login. |
Connecting a project as an admin links your personal account to the same installation at the same time.
What disconnecting does
Disconnect removes the connection from PostHog. What happens on GitHub depends on whether anything else still uses the installation:
- If other PostHog projects or personal accounts still use the installation, the app stays installed on GitHub and only this project (or your account) stops using it.
- If this was the last connection to the installation, PostHog also uninstalls the app from the GitHub organization or account and removes every personal link to it.
The confirmation dialog tells you which case applies before you confirm.
If you uninstall the app directly on GitHub instead, PostHog notices and marks the connection Removed from GitHub. Remove the connection to clear it, then connect again if you still need it.
Troubleshooting
The connection shows a number instead of the account name. GitHub didn't return the account details when the app was installed. PostHog retries in the background and replaces the number with the account name. If it doesn't, disconnect and connect again.
Repositories look out of date. PostHog caches the repository list for an hour. Click Refresh repositories in the repository picker, or open the installation on GitHub to check its access.
"Your GitHub account isn't authorized for this installation". Your GitHub login isn't a member of the organization the app is installed on. Ask an owner to add you, or connect a different GitHub account.