Skip to main content

How to authenticate StackQL to GitHub

StackQL authenticates to GitHub with basic authentication: your GitHub username and a personal access token (PAT), supplied as STACKQL_GITHUB_USERNAME and STACKQL_GITHUB_PASSWORD. Public data is queryable without any credentials at GitHub's unauthenticated rate limits.

Steps​

  1. Create a personal access token in GitHub (Settings -> Developer settings). Grant only the scopes your queries need - none for public data at higher rate limits, repo for private repositories.

  2. Export the credentials:

export STACKQL_GITHUB_USERNAME=yourghuser
export STACKQL_GITHUB_PASSWORD=ghp_yourgithubpersonalaccesstoken
  1. Pull the GitHub provider (first use only):
REGISTRY PULL github;
  1. Verify with a query:
SELECT name, description, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';

The org predicate selects the list_for_org access method; WHERE username = '...' selects list_for_user instead. SHOW METHODS IN github.repos.repos lists every method and its required parameters, including the mutation methods (create_in_org, update, delete).

Unauthenticated access​

The query above works without credentials because the stackql organization is public - useful for evaluation and for agents exploring the query model before credentials are provisioned. GitHub's unauthenticated rate limit is low (60 requests per hour per IP), so any sustained use should authenticate.