Back to plugin list


The CloudQuery GitHub plugin extracts your GitHub API and loads it into any supported CloudQuery destination


Latest version




Date Published

Nov 16, 2023



Set up process

brew install cloudquery/tap/cloudquery

1. Download CLI and login

See installation options

2. Create source and destination configs

Plugin configuration

cloudquery sync github.yml postgresql.yml

3. Run the sync

CloudQuery sync


GitHub Source Plugin

The CloudQuery GitHub plugin extracts your GitHub API and loads it into any supported CloudQuery destination (e.g. PostgreSQL, BigQuery, Snowflake, and more).


The GitHub source plugin supports two authentication methods: Personal Access Token and App authentication. Which one you use is up to and the security requirements of your organization.
Keep in mind rate limits for GitHub Apps are higher than for personal access tokens. Review GitHub rate limits documentation for details.
CloudQuery requires only read permissions (we will never make any changes to your GitHub account or organizations), so, following the principle of least privilege, it's recommended to grant it read-only permissions to all the resources you wish to sync.

Personal Access Token

Follow this guide on how to create a personal access token for CloudQuery.

App authentication

For App authentication, you need to create a GitHub App and install it on your organization. Follow this guide and install the App into your organization(s). Give it all the permissions you need (read-only is recommended).
Every organization will have a unique installation ID. You can find it by going to the organization's settings page, and clicking on the "Installed GitHub Apps" tab. The installation ID is the number in the URL of the page.

Passing private_key as plaintext

You can use | to pass the multi-line private key as plaintext.
For example:
- org: cloudquery
  private_key: |
    -----END RSA PRIVATE KEY-----
  app_id: your_app_id

Referencing private_key as environment variable

When referencing the private_key as a string from environment variables, you will need to replace all the new lines in your PEM file with \n otherwise the new line and indent will prevent CloudQuery from reading the variable correctly.
For example:
- org: cloudquery
  private_key: "${GITHUB_PRI_KEY}"
  app_id: your_app_id


To configure CloudQuery to extract from GitHub, create a .yml file in your CloudQuery configuration directory.
The following configuration will extract all issues from the cloudquery/cloudquery repository:
kind: source
  # Source spec section
  name: github
  path: cloudquery/github
  registry: cloudquery
  version: "v7.5.1"
  tables: ["github_issues"]
  destinations: ["postgresql"]
    access_token: <YOUR_ACCESS_TOKEN_HERE> # Personal Access Token, required if not using App Authentication.
    ## App Authentication (one per org):
    # app_auth:
    # - org: cloudquery
    #   private_key: <PRIVATE_KEY> # Private key as a string
    #   private_key_path: <PATH_TO_PRIVATE_KEY> # Path to private key file
    #   app_id: <YOUR_APP_ID> # App ID, required for App Authentication.
    #   installation_id: <ORG_INSTALLATION_ID> # Installation ID for this org
    orgs: [] # Optional. List of organizations to sync from
    repos: ["cloudquery/cloudquery"] # Optional. List of repositories to sync from
    ## GitHub Enterprise
    # In order to enable GHE you have to provide two urls, the base url of the server and the upload url.
    # Quote from GitHub's client:
    #   If the base URL does not have the suffix "/api/v3/", it will be added automatically. If the upload URL does not have the suffix "/api/uploads", it will be added automatically.
    #   Another important thing is that by default, the GitHub Enterprise URL format should be http(s)://[hostname]/api/v3/ or you will always receive the 406 status code. The upload URL format should be http(s)://[hostname]/api/uploads/"
    # If you are not configuring against an enterprise server please omit the enterprise stanza bellow
        base_url: "http(s)://[your-ghe-hostname]/api/v3/"
        upload_url: "http(s)://[your-ghe-hostname]/api/uploads/"
    # Optional parameters
    # concurrency: 1000 0# Optional. Number of concurrent requests to GitHub API. Default is 10000.
    # discovery_concurrency: 1 # Optional. Number of concurrent requests to GitHub API during discovery phase. Default 1.
See tables for a full list of available tables.
You must specify either orgs or repos in the configuration. If a repository is specified in both orgs and repos, it will be extracted only once, and other repositories from that organization will be ignored.
You can define either private_key or private_key_path in the configuration, but not both.
It is recommended that you use environment variable expansion for the access token in production. For example, if the access token is stored in an environment variable called GITHUB_ACCESS_TOKEN:
  access_token: ${GITHUB_ACCESS_TOKEN}

GitHub Spec

This is the (nested) spec used by GitHub Source Plugin
  • repos ([]string, optional. Default: empty): List of repositories to sync from. The format is owner/repo (e.g. cloudquery/cloudquery). You must specify either orgs or repos in the configuration.
  • orgs ([]string, optional. Default: empty): List of organizations to sync from. You must specify either orgs or repos in the configuration.
  • concurrency (int, optional, default: 10000): A best effort maximum number of Go routines to use. Lower this number to reduce memory usage.
  • discovery_concurrency (int) (default: 1)
    During initialization the GitHub source plugin discovers all repositories under the organizations configured in orgs, to be used later on during the sync process. By default the plugin discovers repositories one organization at a time. You can increase discovery_concurrency to discover multiple organizations in parallel, or use a negative value to discover all organizations in parallel. Please note that it's possible to hit GitHub API rate limits when using a high value for discovery_concurrency.

Subscribe to product updates

Be the first to know about new features.