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

Personal Access Token authentication

Generate a token

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

7. Click Generate token and copy the token value.

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

Create the integration with PAT

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

2. Choose a name for your integration and set up the YAML configuration with PAT authentication:

kind: source
spec:
  name: github
  path: cloudquery/github
  registry: cloudquery
  version: "v15.1.2"
  tables:
    - github_repositories
    - github_issues
    - github_pull_requests
  spec:
    access_token: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
    repos:
      - "<YOUR_ORG>/<YOUR_REPO>"

3. Add a new secret with Key GITHUB_PERSONAL_ACCESS_TOKEN and paste your token as the Value.

4. Click Test Connection 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.

1. Go to your Organization Settings → Developer settings → GitHub Apps → New GitHub App
2. 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)
3. Click Create GitHub App
4. On the app settings page, note the App ID
5. Scroll down to Private keys and click Generate a private key. This downloads a .pem file.
6. 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

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

2. Choose a name and set up the YAML configuration with App authentication:

kind: source
spec:
  name: github
  path: cloudquery/github
  registry: cloudquery
  version: "v15.1.2"
  tables:
    - github_repositories
    - github_issues
    - github_pull_requests
  spec:
    app_auth:
      - org: <YOUR_ORGANIZATION>
        app_id: "<YOUR_APP_ID>"
        installation_id: "<YOUR_INSTALLATION_ID>"
        private_key: |
          ${GITHUB_APP_PRIVATE_KEY}

3. Add a new secret with Key GITHUB_APP_PRIVATE_KEY and paste the entire contents of the .pem file as the Value.

4. Click Test Connection to verify the setup.

What gets synced

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

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

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

Related resources

• GitHub personal access token documentation
• GitHub App registration documentation
• GitHub App rate limits
• GitHub App permissions reference
• CloudQuery GitHub integration on Hub