Export from GitHub to Azure Blob Storage

CloudQuery is an open-source data integration platform that allows you to export data from any source to any destination.

The CloudQuery GitHub plugin allows you to sync data from GitHub to any destination, including Azure Blob Storage. It's free, open source, requires no account, and takes only minutes to get started.

Ready? Let's dive right in!

Step 1. Install the CloudQuery CLI

The CloudQuery CLI is a command-line tool that runs the sync. It supports MacOS, Linux and Windows.

brew install cloudquery/tap/cloudquery

Step 2. Configure the GitHub source plugin

Create a configuration file for the GitHub plugin and set up authentication.

Configuration

Create a file called github.yaml and add the following contents:

To configure CloudQuery to extract from GitHub, create a .yml file in your CloudQuery configuration directory. The following configuration will extract information from the cloudquery/cloudquery repository:

kind: source
spec:
  # Source spec section
  name: github
  path: cloudquery/github
  version: "v5.2.0"
  tables: ["*"]
  destinations: ["azblob"]
  spec:
    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_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 extract from
    repos: ["cloudquery/cloudquery"] # Optional. List of repositories to extract 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
    enterprise:
        base_url: "http(s)://[your-ghe-hostname]/api/v3/"
        upload_url: "http(s)://[your-ghe-hostname]/api/uploads/"

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.

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:

spec:
  access_token: ${GITHUB_ACCESS_TOKEN}

Fine-tune this configuration to match your needs. For more information, see the GitHub Plugin ↗ page in the docs.

Authentication

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.

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 (opens in a new tab) 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 (opens in a new tab) 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.

Step 3. Configure the Azure Blob Storage destination plugin

Create a configuration file for the Azure Blob Storage plugin and set up authentication.

Configuration

Create a file called azblob.yaml and add the following contents:

kind: destination
spec:
  name: "azblob"
  path: "cloudquery/azblob"
  version: "v3.2.0"
  write_mode: "append" # this plugin only supports 'append' mode
  # batch_size: 10000 # optional
  # batch_size_bytes: 5242880 # optional
  spec:
    storage_account: "cqdestinationazblob"
    container: "test"
    path: "path/to/files"
    format: "parquet" # options: parquet, json, csv

Fine-tune this configuration to match your needs. For more information, see the Azure Blob Storage Plugin ↗ page in the docs.

Authentication

The plugin needs to be authenticated with your Azure account in order to fetch information about your cloud setup.

You can either authenticate with az login (when running locally), or by using a "service principal" and exporting environment variables (appropriate for automated deployments).

You can find out more about authentication with Azure at Azure's documentation (opens in a new tab) for the Go SDK.

Step 4. Start the Sync

Run the following command in your terminal to start the sync

cloudquery sync github.yaml azblob.yaml

And away we go! 🚀 The sync will run until completion, fetching all selected tables from GitHub. Any errors will be logged to a file called cloudquery.log.

kind: source spec: # Source spec section name: github path: cloudquery/github version: "v5.2.0" tables: ["*"] destinations: ["azblob"] spec: 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_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 extract from repos: ["cloudquery/cloudquery"] # Optional. List of repositories to extract 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 enterprise: base_url: "http(s)://[your-ghe-hostname]/api/v3/" upload_url: "http(s)://[your-ghe-hostname]/api/uploads/"

Export from GitHub to Azure Blob Storage

Step 1. Install the CloudQuery CLI

Step 2. Configure the GitHub source plugin

Configuration

Authentication

Personal Access Token

App authentication

Step 3. Configure the Azure Blob Storage destination plugin

Configuration

Authentication

Step 4. Start the Sync

Further Reading

Personal Access Token

App authentication