github

GitHub Plugin

Sync GitHub repository data including repos, issues, pull requests, and workflow runs.

Installation

nself plugin install github

Configuration

Required

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Optional

GITHUB_WEBHOOK_SECRET=xxxxxxxxxxxx         # Webhook signature verification
GITHUB_ORG=your-organization               # Sync all org repos
GITHUB_REPOS=owner/repo1,owner/repo2       # Or specific repos only

Token Scopes

Required scopes when creating a Personal Access Token:

• repo - Full repository access
• read:org - Organization repository access (if syncing org repos)

Usage

Sync Data

# Full sync
nself plugin github sync

# Repos only
nself plugin github sync --repos-only

# Initial sync (runs automatically on install)
nself plugin github sync --initial

Repositories

# List repositories
nself plugin github repos list

# Filter by language
nself plugin github repos list --language TypeScript

# Filter by org
nself plugin github repos list --org myorg

# Repository statistics
nself plugin github repos stats

Issues

# List issues
nself plugin github issues list

# Open issues
nself plugin github issues open

# By repository
nself plugin github issues list --repo owner/repo

# By author
nself plugin github issues list --author username

# Statistics
nself plugin github issues stats

Pull Requests

# List PRs
nself plugin github prs list

# Open PRs
nself plugin github prs open

# Merged PRs
nself plugin github prs merged

# PR details
nself plugin github prs show 123

# Statistics
nself plugin github prs stats

GitHub Actions

# List workflow runs
nself plugin github actions list

# Failed runs
nself plugin github actions failed

# Filter by workflow
nself plugin github actions list --workflow "CI"

# Workflow statistics
nself plugin github actions stats

Webhooks

# List events
nself plugin github webhook list

# Filter by event type
nself plugin github webhook list --event push

# Pending events
nself plugin github webhook pending

# Retry event
nself plugin github webhook retry <event-id>

Webhook Setup

Repository Webhooks

1. Go to Repository > Settings > Webhooks
2. Add webhook:
   • URL: https://your-domain.com/webhooks/github
   • Content type: application/json
   • Secret: Your GITHUB_WEBHOOK_SECRET
3. Select events:
   • Push
   • Pull requests
   • Issues
   • Workflow runs
   • Releases

Organization Webhooks

For org-wide webhooks:

1. Go to Organization > Settings > Webhooks
2. Same configuration as repository webhooks

Database Schema

Tables

Table	Description
github_repositories	Repository metadata
github_issues	Issues with labels, assignees
github_pull_requests	PRs with merge info
github_commits	Commit history
github_releases	Release tags
github_workflow_runs	GitHub Actions runs
github_deployments	Deployment status
github_webhook_events	Webhook event log

Views

View	Description
github_open_items	Open issues/PRs by repo
github_recent_activity	Last 7 days activity
github_workflow_stats	Workflow success rates

Example Queries

-- Open issues by repository
SELECT
  r.full_name,
  COUNT(*) as open_issues
FROM github_issues i
JOIN github_repositories r ON i.repo_id = r.id
WHERE i.state = 'open'
GROUP BY r.full_name
ORDER BY open_issues DESC;

-- PR merge rate by author
SELECT
  user_login,
  COUNT(*) as total_prs,
  COUNT(*) FILTER (WHERE merged = true) as merged,
  ROUND(COUNT(*) FILTER (WHERE merged = true)::numeric / COUNT(*) * 100) as merge_rate
FROM github_pull_requests
GROUP BY user_login
ORDER BY total_prs DESC
LIMIT 20;

-- Workflow success rate
SELECT * FROM github_workflow_stats;

Environment Handling

Development

ENV=dev
GITHUB_TOKEN=ghp_dev_token
GITHUB_REPOS=myorg/dev-repo

Production

ENV=prod
GITHUB_TOKEN=ghp_prod_token
GITHUB_ORG=myorg

Use different tokens or sync different repos per environment.

Uninstall

# Remove plugin and data
nself plugin remove github

# Keep database tables
nself plugin remove github --keep-data

Troubleshooting

Authentication Errors

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

# Check scopes
curl -I -H "Authorization: Bearer ghp_xxx" https://api.github.com/user
# Look for X-OAuth-Scopes header

Rate Limiting

# Check rate limit
curl -H "Authorization: Bearer ghp_xxx" https://api.github.com/rate_limit

# Plugin uses 0.1s delay between requests to avoid limits

Webhook Issues

# Check recent deliveries in GitHub webhook settings
# Verify GITHUB_WEBHOOK_SECRET matches

# Check nginx logs
docker logs <project>_nginx | grep webhook

Related

• Plugin Command
• Database Command
• GitHub API Docs