GitHub OAuth Skill

A comprehensive GitHub integration demonstrating OAuth2 Device Flow authentication with the Skill Engine SDK. Provides secure, token-based access to GitHub repositories, issues, and pull requests without exposing credentials in configuration files.

Overview

This skill showcases modern OAuth2 authentication patterns for CLI tools, using GitHub's Device Flow (RFC 8628) which is ideal for command-line applications. All tokens are stored securely in your system keychain.

When to Use This Skill

Use this skill when you need to:

• Authenticate with GitHub without manually creating personal access tokens
• List and search your repositories or organization repos
• Manage issues (create, list, filter by labels/state)
• Work with pull requests (create, list, filter)
• Get information about your authenticated user
• Store credentials securely in system keychain

Prerequisites

1. GitHub Account: An active GitHub account with repository access
2. System Keychain: macOS Keychain, Windows Credential Manager, or Linux Secret Service

OAuth2 Device Flow Setup

The Device Flow allows you to authenticate without a local HTTP server:

1. Run the login command
2. A browser window opens with GitHub authorization page
3. Enter the provided device code
4. Authorize the application
5. Token is automatically stored in your system keychain

Required Scopes:

• repo - Full control of private repositories
• read:user - Read user profile data

Authentication

Initial Setup

# Authenticate with GitHub (opens browser)
skill auth login github --skill github-oauth-skill

# This will:
# 1. Display a URL and device code
# 2. Open GitHub authorization page in your browser
# 3. Prompt you to enter the code
# 4. Store the token securely in system keychain

Check Authentication Status

# View current auth status
skill auth status

# Test the connection
skill run github-oauth-skill whoami

# Log out (revokes token)
skill auth logout github

Tools

User Tools

whoami

Get information about the authenticated GitHub user.

Parameters: None

Returns: User login, name, email, public repos count, followers, following

Example:

skill run github-oauth-skill whoami

Repository Tools

list-repos

List repositories for the authenticated user or an organization.

Example:

# List your repositories
skill run github-oauth-skill list-repos

# List organization repos
skill run github-oauth-skill list-repos org=microsoft sort=created per_page=50

# Only show public repos
skill run github-oauth-skill list-repos type=public

get-repo

Get detailed information about a specific repository.

Example:

skill run github-oauth-skill get-repo repo=torvalds/linux
skill run github-oauth-skill get-repo repo=facebook/react

Issue Tools

list-issues

List issues in a repository with filtering options.

Example:

# List open issues
skill run github-oauth-skill list-issues repo=owner/repo

# List all closed issues
skill run github-oauth-skill list-issues repo=owner/repo state=closed

# Filter by labels
skill run github-oauth-skill list-issues repo=owner/repo labels=bug,high-priority

# Filter by assignee
skill run github-oauth-skill list-issues repo=owner/repo assignee=username

create-issue

Create a new issue in a repository.

Example:

# Basic issue
skill run github-oauth-skill create-issue \
  repo=owner/repo \
  title="Bug: Login fails on mobile"

# Issue with description and labels
skill run github-oauth-skill create-issue \
  repo=owner/repo \
  title="feat: Add dark mode" \
  body="## Description\nUsers have requested dark mode support.\n\n## Requirements\n- [ ] Dark theme\n- [ ] Theme switcher" \
  labels=enhancement,ui

# Assign to multiple people
skill run github-oauth-skill create-issue \
  repo=owner/repo \
  title="Critical: Data loss bug" \
  body="Users reporting data loss in version 2.1.0" \
  labels=bug,critical \
  assignees=dev1,dev2

Pull Request Tools

list-prs

List pull requests in a repository.

Example:

# List open PRs
skill run github-oauth-skill list-prs repo=owner/repo

# List all PRs (including closed)
skill run github-oauth-skill list-prs repo=owner/repo state=all

# Filter by branch
skill run github-oauth-skill list-prs repo=owner/repo head=feature/auth base=main

create-pr

Create a new pull request.

Example:

# Basic PR
skill run github-oauth-skill create-pr \
  repo=owner/repo \
  title="feat: Add user authentication" \
  head=feature/auth \
  base=main

# PR with description and draft mode
skill run github-oauth-skill create-pr \
  repo=owner/repo \
  title="WIP: Refactor database layer" \
  head=refactor/db \
  base=develop \
  body="## Changes\n- Extract query builders\n- Add connection pooling\n- Optimize migrations\n\n## TODO\n- [ ] Add tests\n- [ ] Update docs" \
  draft=true

# Cross-repository PR
skill run github-oauth-skill create-pr \
  repo=upstream/repo \
  title="fix: Correct typo in README" \
  head=myuser:patch-1 \
  base=main \
  body="Fixes typo in installation instructions."

Workflows

Repository Discovery Workflow

# Find interesting repos
skill run github-oauth-skill list-repos org=microsoft sort=updated per_page=10

# Get details on specific repo
skill run github-oauth-skill get-repo repo=microsoft/vscode

# Check open issues
skill run github-oauth-skill list-issues repo=microsoft/vscode state=open labels=bug

Issue Management Workflow

# Create a new issue
skill run github-oauth-skill create-issue \
  repo=myorg/myrepo \
  title="Bug: API timeout" \
  body="API endpoint /users times out after 30s" \
  labels=bug,api

# List issues assigned to you
skill run github-oauth-skill list-issues repo=myorg/myrepo assignee=myusername

# List high-priority bugs
skill run github-oauth-skill list-issues repo=myorg/myrepo labels=bug,high-priority

Pull Request Workflow

# After pushing commits to feature branch, create PR
skill run github-oauth-skill create-pr \
  repo=myorg/myrepo \
  title="feat: Implement caching layer" \
  head=feature/caching \
  base=main \
  body="## Summary\nAdds Redis caching for API responses\n\n## Performance\n- 80% reduction in database queries\n- 200ms average response time improvement"

# List your open PRs
skill run github-oauth-skill list-prs repo=myorg/myrepo state=open

# Check all recent PR activity
skill run github-oauth-skill list-prs repo=myorg/myrepo state=all per_page=20

Configuration

No manual configuration needed! Authentication is handled through OAuth2 Device Flow.

The skill automatically:

• Stores tokens securely in system keychain
• Refreshes tokens when needed (if supported by GitHub)
• Uses environment variables as fallback: GITHUB_TOKEN

Manual Token (Optional)

If you prefer to use a personal access token:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

SDK Features Demonstrated

This skill showcases advanced SDK capabilities:

1. OAuth2 Device Flow

import { defineSkill, createAuthenticatedClient } from '@skill-engine/sdk';

2. Type-Safe HTTP Client

const client = createAuthenticatedClient({
  baseUrl: 'https://api.github.com',
  authType: 'bearer',
  tokenKey: 'GITHUB_TOKEN',
});

3. Parameter Validation

{
  name: 'repo',
  paramType: 'string',
  validation: {
    pattern: '^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$',
  },
}

4. Structured Error Handling

if (response.status === 401) {
  return err('Auth failed', errors.auth());
}

Security Notes

• Token Storage: Tokens are stored in system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Automatic Refresh: Tokens are refreshed automatically when supported
• No Config Files: Credentials never written to configuration files
• Scope Limitation: Only requests minimal required scopes (repo, read:user)
• Revocation: Use skill auth logout github to revoke and remove tokens

Rate Limits

GitHub API rate limits:

• Authenticated: 5,000 requests/hour
• Search API: 30 requests/minute
• GraphQL API: 5,000 points/hour

Rate limit info is included in API responses. The skill automatically handles rate limit errors.

Troubleshooting

Common Issues

Browser doesn't open during auth:

# Manually open the URL displayed in terminal
# Then enter the device code shown

Token not found:

# Re-authenticate
skill auth login github --skill github-oauth-skill

Permission denied errors:

# Check token scopes - may need to re-authenticate with broader scopes
skill auth logout github
skill auth login github --skill github-oauth-skill

Resources

• GitHub REST API Documentation
• OAuth2 Device Flow (RFC 8628)
• GitHub Personal Access Tokens
• Skill Engine SDK Documentation

Contributing

This skill serves as a reference implementation for OAuth2 in Skill Engine. Contributions welcome:

• Additional GitHub API endpoints
• Improved error handling
• Support for GitHub Enterprise
• GraphQL API integration