GitHub Authentication Guide¶

Configure a GitHub Personal Access Token (PAT) to improve API rate limits when working with GitHub sources and private repositories.

Why Use a PAT?¶

GitHub API requests are rate-limited based on authentication status:

Auth Type	Rate Limit	Use Case
None (unauthenticated)	60 req/hr	Light usage, public repos only
PAT (authenticated)	5,000 req/hr	Marketplace scanning, private repos, heavy usage

Using a PAT allows SkillMeat to: - Scan marketplace repositories more efficiently - Access private GitHub repositories - Avoid rate limit errors during bulk operations - Use GitHub Actions and other integrations

Setup via Web UI¶

Navigate to Settings in the web interface sidebar
Scroll to GitHub Authentication section
Enter your GitHub Personal Access Token in the input field
Click Set Token
The system validates your token against GitHub API
On success, you'll see your GitHub username and a masked token display

Your token is now securely stored and will be used for all GitHub API requests.

Setup via Environment Variable¶

Set the GITHUB_TOKEN or SKILLMEAT_GITHUB_TOKEN environment variable:

# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Or for a single command:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx skillmeat list

Environment variables take precedence over stored tokens, allowing you to override settings for specific operations.

Setup via CLI¶

Use the configuration command to set your token:

skillmeat config set github-token ghp_xxxxxxxxxxxxxxxxxxxx

View your stored token status:

skillmeat config get github-token

Token Resolution Order¶

When SkillMeat accesses a GitHub repository (e.g., during artifact scanning), it resolves authentication using a layered fallback chain:

Priority	Token Source	Scope	Edition
1	Per-connection token	Single repository connection	Enterprise
2	Personal developer token	Per-user credential	Enterprise
3	Organization/team token	Shared team credential	Enterprise
4	Global GitHub token	All requests (from Settings)	Both
5	Unauthenticated	Public repos only (60 req/hr)	Both

On the Local edition, only priorities 4 and 5 apply. Configure your global token via Settings → GitHub Authentication.

On the Enterprise edition, the Token Management panel on each git connection lets you set per-connection and personal tokens. Organization tokens are managed by admins.

Creating a GitHub PAT¶

Classic Token (Recommended for simplicity)¶

Go to github.com/settings/tokens
Click Generate new token (classic)
Give it a descriptive name (e.g., "SkillMeat API Access")
Select expiration (90 days recommended for security)
Select scopes:
Check repo for full repository access
Optionally check read:user for user profile access
Click Generate token
Copy the token immediately (shown only once)

Fine-Grained Token (More secure, newer option)¶

Go to github.com/settings/tokens?type=beta
Click Generate new token (fine-grained)
Give it a descriptive name (e.g., "SkillMeat API Access")
Set expiration (90 days recommended)
Select Repository access:
Choose "All repositories" for broad access
Or select specific repositories for narrower scope
Under Permissions, select:
Contents: Read (for reading artifact code)
Metadata: Read (required by GitHub API)
Click Generate token
Copy the token immediately (shown only once)

Token Format¶

SkillMeat accepts both token formats:

Classic tokens: Start with ghp_ (example: ghp_xxxxxxxxxxxxxxxxxxxx)
Fine-grained tokens: Start with github_pat_ (example: github_pat_xxxxxxxxxxxxxxxxxxxx)

Verifying Your Token¶

Check that your token is properly configured and valid:

# View token status
skillmeat config get github-token

# Test token validity
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

In the web UI, go to Settings → GitHub Authentication to see your username and masked token status.

Clearing Your Token¶

Via Web UI¶

Go to Settings → GitHub Authentication
Click Clear Token button
Confirm the action

Via CLI¶

skillmeat config delete github-token

Or clear all configuration:

skillmeat config reset

Via Environment¶

Unset the environment variable:

unset GITHUB_TOKEN
unset SKILLMEAT_GITHUB_TOKEN

Security Best Practices¶

Use Fine-Grained Tokens: They provide more granular control and are more secure than classic tokens
Limit Scope: Grant only the permissions SkillMeat actually needs
Set Expiration: Use short expiration periods (30-90 days) and rotate regularly
Secure Storage:
Tokens stored in ~/.skillmeat/config.toml with 0600 file permissions
Never commit tokens to version control
Don't share token values with others
Rotate Regularly: Create new tokens periodically and delete old ones
Monitor Activity: Check GitHub's security log for token usage patterns

Troubleshooting¶

"Invalid token format" Error¶

The token must start with ghp_ (classic) or github_pat_ (fine-grained). Common issues:

Token was copied incorrectly (copy again from GitHub settings)
Token was truncated
Token contains extra whitespace

"Token validation failed" Error¶

The token is valid format but doesn't work with GitHub API. Check:

Token hasn't expired (classic tokens have max 1-year expiration)
Token wasn't revoked from GitHub settings
Your GitHub account has API access enabled
You have internet connectivity

Rate Limiting Still Occurs¶

If you're still hitting rate limits:

Verify token is actually being used: skillmeat config get github-token
Check environment variables aren't being overridden: echo $GITHUB_TOKEN
Some GitHub API endpoints have additional rate limiting rules
Consider batching operations or adding delays between requests

"Insufficient permissions" Error¶

Your token needs the required scopes. For classic tokens: - Ensure repo scope is selected

For fine-grained tokens: - Ensure Contents: Read permission is granted for target repositories

Examples¶

Access Private Repository¶

# Set token first
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Now you can add from private repos
skillmeat add skill myorg/private-repo/skills/my-skill

Scan Marketplace Sources Efficiently¶

With a PAT, marketplace scanning uses 5,000 req/hr instead of 60:

# Much faster with authenticated requests
skillmeat marketplace sources add https://github.com/anthropics/skillmeat-marketplace
skillmeat marketplace sources rescan

Batch Operations with Elevated Rate Limit¶

# Import multiple artifacts without hitting rate limits
skillmeat marketplace sources import --source my-github-source --bulk

Advanced: Using with GitHub Actions¶

If you're using SkillMeat in CI/CD workflows with GitHub Actions:

- name: Configure GitHub Token
  run: |
    skillmeat config set github-token ${{ secrets.GITHUB_TOKEN }}

- name: Sync artifacts
  run: |
    skillmeat sync pull

Store your token as a repository secret (Settings → Secrets and variables → Actions).

Developer Notes¶

For developers integrating GitHub API calls into SkillMeat:

Using GitHubClient Wrapper¶

All GitHub operations must use the centralized GitHubClient wrapper at skillmeat/core/github_client.py:

from skillmeat.core.github_client import get_github_client

# Get singleton client - token is resolved automatically
client = get_github_client()

# Common operations
metadata = client.get_repo_metadata("owner/repo")
content = client.get_file_content("owner/repo", "path/to/file")
sha = client.resolve_version("owner/repo", "latest")

Token Resolution Priority¶

The wrapper automatically resolves tokens in this order:

ConfigManager: Stored in ~/.skillmeat/config.toml (settings.github-token)
SKILLMEAT_GITHUB_TOKEN env var
GITHUB_TOKEN env var
Unauthenticated: 60 req/hr fallback

Exception Handling¶

from skillmeat.core.github_client import (
    GitHubAuthError,
    GitHubRateLimitError,
    GitHubNotFoundError,
)

try:
    content = client.get_file_content("owner/repo", "path")
except GitHubAuthError:
    # Invalid/missing token
except GitHubRateLimitError as e:
    # Check e.reset_at to retry after limit resets
except GitHubNotFoundError:
    # Repository or file not found

Never use PyGithub directly - always go through the GitHubClient wrapper for consistent error handling, logging, and token management.