GitHub token setup

This guide explains how to create a GitHub Personal Access Token (PAT) for use with glance and kickstart when you’re not using GitHub CLI or browser auth. Set the GITHUB_TOKEN environment variable with your token.

Recommendation: Prefer fine-grained PATs over classic tokens: they are scoped to specific repositories and permissions, reducing risk if the token is exposed.

When to use a PAT

For normal use, prefer GitHub CLI (gh auth login) or browser auth (dn auth); no PAT or env var needed. Use a PAT when:

Running in CI (e.g. GitHub Actions: GITHUB_TOKEN is provided automatically)
Running in scripts or headless environments
You cannot use gh or browser login

When you do use a PAT, fine-grained tokens are recommended: they limit access to specific repositories and permissions.

Why a GitHub token is needed

The glance and kickstart tools interact with the GitHub API to:

Fetch repository information
Retrieve issues and commits
Create pull requests

These operations require authentication. Personal Access Tokens are supported as a fallback when GitHub CLI or browser auth are not available.

Creating a Personal Access Token

Fine-grained PATs (recommended): Scoped to specific repos and permissions. Create a fine-grained token → choose Repository access (only the repos you need) → under Permissions, set Contents (Read and write), Pull requests (Read and write), Metadata (Read-only). For org repos, add Organization permissions → Members (Read-only) if needed.

Classic PATs: Broader access. Use only when fine-grained tokens don’t fit (e.g. some CI setups).

Step 1: Navigate to GitHub Settings

Go to GitHub.com and sign in
Click your profile picture in the top right corner
Select Settings from the dropdown menu

Step 2: Access Developer Settings

In the left sidebar, scroll down and click Developer settings
Click Personal access tokens in the left sidebar
Prefer Fine-grained tokens (recommended); or Tokens (classic) if needed

Step 3: Generate New Token

Fine-grained: Use Generate new token → Generate new token (fine-grained). Set resource owner, repository access, and permissions (Contents, Pull requests, Metadata; add org Members read if needed).

Classic: Use Generate new token → Generate new token (classic). Set:

Name (e.g. “dn-kickstart”)
Expiration (e.g. 90 days)
Scopes: repo (or public_repo) and read:org for organization repos

Step 4: Copy and Save Token

IMPORTANT: GitHub will only show the token once. Copy it immediately and store it securely.

Copy the generated token (it starts with ghp_)
Store it securely (password manager, encrypted file, etc.)
Never commit this token to version control

Setting the environment variable

Set GITHUB_TOKEN with your token. (dn also accepts the legacy DANGEROUS_GITHUB_TOKEN for backward compatibility.)

macOS/Linux (bash/zsh)

Add to your ~/.zshrc or ~/.bashrc:

export GITHUB_TOKEN="ghp_your_token_here"

Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

Windows (PowerShell)

$env:GITHUB_TOKEN="ghp_your_token_here"

To make it persistent, add to your PowerShell profile:

[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token_here", "User")

Verify token is set

echo $GITHUB_TOKEN  # macOS/Linux
echo $env:GITHUB_TOKEN  # Windows PowerShell

Required scopes / permissions

Fine-grained PATs: Repository permissions: Contents (Read and write), Pull requests (Read and write), Metadata (Read-only). For org repos, add Organization permissions → Members (Read-only) if needed.

Classic PATs:

Scope	Description	Required for
`repo`	Full control of private repositories	Private repositories, creating PRs
`public_repo`	Access public repositories	Public repositories only
`read:org`	Read org and team membership	Organization repositories

Recommendation: Prefer fine-grained PATs; for classic, minimum is repo (or public_repo) and read:org for org repos.

Security best practices

Best practices:

Never commit tokens to version control — Use environment variables; add GITHUB_TOKEN to .gitignore if storing in a file.
Use token expiration — Set tokens to expire (30–90 days); rotate regularly.
Limit scope — Prefer fine-grained PATs scoped to specific repositories.
Revoke unused tokens — Review and revoke in GitHub Settings.
Use separate tokens — Different tokens for different tools/environments.
Monitor usage — Check GitHub’s security log for unexpected API usage.

Troubleshooting

”No GitHub token found” or token not used

Verify the token is set: echo $GITHUB_TOKEN (or echo $env:GITHUB_TOKEN on Windows)
Make sure you’ve reloaded your shell after setting the variable
dn accepts GITHUB_TOKEN (preferred) or the legacy DANGEROUS_GITHUB_TOKEN

”Repository not found or access denied”

Verify your token has the correct scopes (repo for private repos)
Check that you have access to the repository
Ensure the token hasn’t expired

”Failed to verify repository”

Verify the remote URL is correct: git remote get-url origin or sl paths default
Ensure the repository exists and you have access
Check that your token has the necessary permissions