Setting up a GitHub Integration

The GitHub integration supports two authentication methods: Personal Access Token (PAT) and GitHub App. Choose the method that best aligns with your organization’s security requirements.

Prerequisites

A CloudQuery Platform account with admin access
A GitHub account with access to the repositories or organizations you want to sync
For GitHub App authentication: organization admin access to create and install apps

GitHub Apps have higher rate limits than personal access tokens. For organizations with many repositories, GitHub App authentication is recommended.

Personal Access Token authentication

Generate a token

Go to your GitHub account Settings
Navigate to Developer settings → Personal access tokens → Tokens (classic)
Click Generate new token and select Generate new token (classic)
Name your token (e.g. cloudquery-readonly)
Set an expiration period
Select the following scopes based on the data you want to sync:

Scope	Required for
`repo` (read-only)	Repository metadata, issues, pull requests, commits
`read:org`	Organization members, teams, settings
`read:user`	User profile information
`read:project`	GitHub Projects data
`read:packages`	GitHub Packages metadata

Click Generate token and copy the token value.

For detailed instructions, see the GitHub personal access token documentation.

Create the integration with PAT

In CloudQuery Platform, go to Data Pipelines → Integrations. Click Create Integration and type GitHub to find the GitHub integration.

Find GitHub Integration

Choose a name for your integration. Under Select authentication type, choose Access Token, then enter your personal access token in the Access Token field.
Under Configuration, select Organizations or Repositories and enter the relevant names.
Click Continue to select the tables you want to sync.
Click Test and Continue to verify the setup.

GitHub App authentication

Create a GitHub App

GitHub App authentication provides higher rate limits and fine-grained permissions. For detailed setup instructions, see the GitHub App registration documentation.

Go to your Organization Settings → Developer settings → GitHub Apps → New GitHub App
Configure the app:
- Set a name (e.g. CloudQuery Integration)
- Set the homepage URL to your organization’s URL
- Deselect Webhook (not needed)
- Under Permissions, grant read-only access to the resources you want to sync (e.g., Repository: Contents, Issues, Pull requests, Metadata; Organization: Members)
Click Create GitHub App
On the app settings page, note the App ID
Scroll down to Private keys and click Generate a private key. This downloads a .pem file.
Go to Install App in the left sidebar and install it on your organization. Note the Installation ID from the URL (e.g., https://github.com/settings/installations/<INSTALLATION_ID>)

For a full list of permissions required per resource type, see the GitHub App permissions reference.

Create the integration with GitHub App

In CloudQuery Platform, go to Data Pipelines → Integrations. Click Create Integration and type GitHub to find the GitHub integration.
Choose a name for your integration. Github app authentication is selected by default. Enter your App ID, Installation ID, and Private Key in the fields provided. Paste the entire contents of the .pem file into the Private Key field.
Under Configuration, select Organizations or Repositories and enter the relevant names.
Click Continue to select the tables you want to sync.
Click Test and Continue to verify the setup.

What gets synced

The GitHub integration syncs repository, organization, and security data. Some of the most commonly used tables include:

Category	Tables	Description
Repositories	`github_repositories`	Repository metadata, settings, visibility
Issues & PRs	`github_issues`, `github_pull_requests`	Issues, pull requests, and their metadata
CI/CD	`github_workflow_runs`	GitHub Actions workflow run history
Security	`github_code_scanning_alerts`, `github_secret_scanning_alerts`	Code scanning and secret scanning findings
Organization	`github_organization_members_with_role`	Org members and their roles

See the full GitHub table list for all available tables.

Verify the integration

After your first sync completes, open the SQL Console and run these queries to confirm data arrived:


-- Count synced repositories
SELECT count(*) FROM github_repositories


-- List synced organizations
SELECT DISTINCT org FROM github_repositories


-- View recent issues
SELECT repository_full_name, title, state, created_at
FROM github_issues
ORDER BY created_at DESC
LIMIT 10


-- Check pull request activity
SELECT repository_full_name, title, state, created_at
FROM github_pull_requests
ORDER BY created_at DESC
LIMIT 10

You can also browse your GitHub resources in the Asset Inventory.

Troubleshooting

Issue	Cause	Fix
`401 Unauthorized`	Invalid or expired token	Generate a new PAT or rotate the GitHub App private key. Verify the secret value in CloudQuery Platform matches.
`403 Forbidden`	Insufficient token scopes	Check that the PAT has the required scopes (see the scopes table above). For GitHub Apps, verify the app has the necessary permissions.
Rate limit exceeded	Too many API requests	GitHub Apps have higher rate limits than PATs. Consider switching to GitHub App authentication. You can also reduce the number of tables or repositories synced.
`404 Not Found`	Repository or organization not accessible	Verify the Repositories or Organizations values in the form match existing repositories/organizations that the token or app has access to.
No data after sync	Empty repositories or organizations list	Verify that at least one Repository is entered in `owner/repo` format, or switch to Organizations and enter at least one organization name.

Next steps

Set up a sync to schedule when your GitHub data is fetched
Browse synced resources in the Asset Inventory
Run advanced queries in the SQL Console
See the GitHub integration documentation for full configuration options and table reference

Was this page helpful?

Last updated on April 7, 2026