GitHub Integration

Overview

Interact with GitHub repositories through simple bash scripts. All scripts handle REST API authentication and requests internally - you just provide repository details and arguments.

Core principle: Agents can manage GitHub issues and PRs without learning API endpoints or authentication flows.

When to Use

• Creating issues from conversations or bug reports
• Managing pull requests
• Updating issue labels or states
• Searching code across repositories
• Closing or reopening issues

Quick Reference

Environment Setup

Required variable (set in /experiments/skills/.env):

GITHUB_TOKEN=ghp_xxx

Scripts automatically source the .env file from parent directory.

Common Operations

Create Issue

# Simple issue
scripts/gh-create-issue.sh \
  --owner myorg \
  --repo myrepo \
  --title "Fix login bug"

# With description and labels
scripts/gh-create-issue.sh \
  --owner myorg \
  --repo myrepo \
  --title "Add feature" \
  --body "Feature details here" \
  --labels "enhancement,priority"

# Assign to users
scripts/gh-create-issue.sh \
  --owner myorg \
  --repo myrepo \
  --title "Task" \
  --assignees "username1,username2"

List Issues

# All open issues
scripts/gh-list-issues.sh --owner myorg --repo myrepo

# All issues (open and closed)
scripts/gh-list-issues.sh \
  --owner myorg \
  --repo myrepo \
  --state all \
  --limit 50

# Filter by label and assignee
scripts/gh-list-issues.sh \
  --owner myorg \
  --repo myrepo \
  --labels "bug" \
  --assignee "username"

Update Issue

# Change title
scripts/gh-update-issue.sh \
  --owner myorg \
  --repo myrepo \
  --number 42 \
  --title "Updated title"

# Close issue
scripts/gh-update-issue.sh \
  --owner myorg \
  --repo myrepo \
  --number 42 \
  --state closed

# Update labels (replaces existing)
scripts/gh-update-issue.sh \
  --owner myorg \
  --repo myrepo \
  --number 42 \
  --labels "bug,priority,in-progress"

Create Pull Request

# Simple PR
scripts/gh-create-pr.sh \
  --owner myorg \
  --repo myrepo \
  --title "Fix bug" \
  --head feature-branch

# With description and custom base
scripts/gh-create-pr.sh \
  --owner myorg \
  --repo myrepo \
  --title "New feature" \
  --head feat-branch \
  --base develop \
  --body "Feature description"

# Draft PR
scripts/gh-create-pr.sh \
  --owner myorg \
  --repo myrepo \
  --title "WIP: Feature" \
  --head feat-branch \
  --draft

Search Code

# Search across all repos
scripts/gh-search-code.sh --query "function authenticate"

# Search in specific organization
scripts/gh-search-code.sh \
  --query "class User" \
  --owner myorg

# Search in specific repo
scripts/gh-search-code.sh \
  --query "TODO" \
  --owner myorg \
  --repo myrepo \
  --limit 10

Output Format

All scripts return JSON with relevant data:

{
  "id": 123456,
  "number": 42,
  "title": "Issue title",
  "state": "open",
  "url": "https://github.com/owner/repo/issues/42",
  "api_url": "https://api.github.com/repos/owner/repo/issues/42"
}

Common Mistakes

Missing owner or repo

• ❌ GitHub token alone isn't enough
• ✅ Always specify --owner and --repo for repository operations

Using gh CLI syntax

• ❌ Don't: gh issue create --title "Title"
• ✅ Do: gh-create-issue.sh --owner org --repo repo --title "Title"

Forgetting issue numbers are not IDs

• Use --number (the visible number like #42)
• Don't use the internal id field from API responses

Labels replace instead of append

• --labels "bug,new" replaces all existing labels
• To preserve labels, fetch current labels first and include them

Personal access token permissions

• Token needs repo scope for private repositories
• Token needs public_repo scope for public repositories
• Error "Not Found" often means insufficient permissions

Script Location

Scripts are located in the scripts/ directory within this skill. They can be called from any directory as they auto-source the parent .env file.