Skill: byungkyu/github-api (version 1.0.6)

--- name: github description: | GitHub API integration with managed OAuth. Access repositories, issues, pull requests, commits, branches, and users. Use this skill when users want to interact with GitHub repositories, manage issues and PRs, search code, or automate workflows. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY --- # GitHub Access the GitHub REST API with managed OAuth authentication. Manage repositories, issues, pull requests, commits, branches, users, and more. ## Quick Start **CLI:** ```bash maton github repo list --sort updated ``` ```bash maton api '/github/user/repos?sort=updated&per_page=10' ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/github/user/repos?sort=updated&per_page=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://api.maton.ai/github/{native-api-path} ``` Maton proxies requests to `api.github.com` and automatically injects your OAuth token. ## Installation **NPM:** ```bash npm install -g @maton-ai/cli ``` **Homebrew:** ```bash brew install maton-ai/cli/maton ``` ## Authentication **CLI:** ```bash maton login # Opens browser for API key maton login --interactive # Skip browser, paste API key directly maton whoami # Show current auth state ``` **Manual:** 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key 4. Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ## Connection Management Manage your GitHub OAuth connections at `https://api.maton.ai`. ### List Connections **CLI:** ```bash maton connection list github --status ACTIVE ``` ```bash maton api -X GET /connections -f app=github -f status=ACTIVE ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections?app=github&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection **CLI:** ```bash maton connection create github ``` ```bash maton api /connections -f app=github ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'github'}).encode() req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection **CLI:** ```bash maton connection view {connection_id} ``` ```bash maton api /connections/{connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection **CLI:** ```bash maton connection delete {connection_id} ``` ```bash maton api -X DELETE /connections/{connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple GitHub connections, specify which one to use: **CLI:** ```bash maton github user --connection {connection_id} ``` ```bash maton api /github/user --connection {connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/github/user') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '{connection_id}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If you have multiple connections, always specify the connection to ensure requests go to the intended account. ## Security & Permissions - Access is scoped to repositories, issues, pull requests, commits, branches, and users within the connected GitHub account. - **All write operations require explicit user approval.** Before executing any create, update, or delete call: 1. Confirm the exact target (owner/repo, issue number, branch name) with the user. 2. Verify the correct connection ID when multiple connections exist. 3. State whether the action is reversible or destructive. - **Irreversible / high-risk operations** (require extra caution): - Deleting repositories, branches, or releases - Force-pushing or rewriting history - Merging pull requests (cannot be unmerged) - Removing collaborators or transferring ownership - **Scope boundaries:** - Only operate on repositories the user explicitly names. Never enumerate or modify repositories outside the current task context. - Organization-level actions (creating repos, managing members) require the user to confirm the target organization. - Do not request or use OAuth scopes beyond what the current task requires. ## API Reference ### Users #### Get Authenticated User ```bash GET /github/user ``` Example: ```bash maton github whoami ``` #### Get User by Username ```bash GET /github/users/{username} ``` #### List Users ```bash GET /github/users?since={user_id}&per_page=30 ``` ### Repositories #### List User Repositories ```bash GET /github/user/repos?per_page=30&sort=updated ``` Query parameters: `type` (all, owner, public, private, member), `sort` (created, updated, pushed, full_name), `direction` (asc, desc), `per_page`, `page` Example: ```bash maton github repo list --sort updated ``` #### List Organization Repositories ```bash GET /github/orgs/{org}/repos?per_page=30 ``` Example: ```bash maton github repo list {org} ``` #### Get Repository ```bash GET /github/repos/{owner}/{repo} ``` Example: ```bash maton github repo view --repo {owner}/{repo} ``` #### Create Repository (User) ```bash POST /github/user/repos Content-Type: application/json { "name": "my-new-repo", "description": "A new repository", "private": true, "auto_init": true } ``` Example: ```bash maton github repo create my-new-repo --description "A new repository" --visibility private ``` #### Create Repository (Organization) ```bash POST /github/orgs/{org}/repos Content-Type: application/json { "name": "my-new-repo", "description": "A new repository", "private": true } ``` Example: ```bash maton github repo create {org}/my-new-repo --visibility private ``` #### Update Repository ```bash PATCH /github/repos/{owner}/{repo} Content-Type: application/json { "description": "Updated description", "has_issues": true, "has_wiki": false } ``` Example: ```bash maton github repo edit --repo {owner}/{repo} --description "Updated description" --enable-issues --enable-wiki=false ``` ### Repository Contents #### List Contents ```bash GET /github/repos/{owner}/{repo}/contents/{path} ``` #### Get File Contents ```bash GET /github/repos/{owner}/{repo}/contents/{path}?ref={branch} ``` #### Create or Update File ```bash PUT /github/repos/{owner}/{repo}/contents/{path} Content-Type: application/json { "message": "Create new file", "content": "SGVsbG8gV29ybGQh", "branch": "main" } ``` Note: `content` must be Base64 encoded. #### Delete File ```bash DELETE /github/repos/{owner}/{repo}/contents/{path} Content-Type: application/json { "message": "Delete file", "sha": "{file_sha}", "branch": "main" } ``` ### Branches #### List Branches ```bash GET /github/repos/{owner}/{repo}/branches?per_page=30 ``` #### Get Branch ```bash GET /github/repos/{owner}/{repo}/branches/{branch} ``` #### Rename Branch ```bash POST /github/repos/{owner}/{repo}/branches/{branch}/rename Content-Type: application/json { "new_name": "new-branch-name" } ``` #### Merge Branches ```bash POST /github/repos/{owner}/{repo}/merges Content-Type: application/json { "base": "main", "head": "feature-branch", "commit_message": "Merge feature branch" } ``` ### Commits #### List Commits ```bash GET /github/repos/{owner}/{repo}/commits?per_page=30 ``` Query parameters: `sha` (branch name or commit SHA), `path` (file path), `author`, `committer`, `since`, `until`, `per_page`, `page` #### Get Commit ```bash GET /github/repos/{owner}/{repo}/commits/{ref} ``` #### Compare Two Commits ```bash GET /github/repos/{owner}/{repo}/compare/{base}...{head} ``` ### Issues #### List Repository Issues ```bash GET /github/repos/{owner}/{repo}/issues?state=open&per_page=30 ``` Query parameters: `state` (open, closed, all), `labels`, `assignee`, `creator`, `mentioned`, `sort`, `direction`, `since`, `per_page`, `page` Example: ```bash maton github issue list --repo {owner}/{repo} --state open ``` #### Get Issue ```bash GET /github/repos/{owner}/{repo}/issues/{issue_number} ``` Example: ```bash maton github issue view {issue_number} --repo {owner}/{repo} ``` #### Create Issue ```bash POST /github/repos/{owner}/{repo}/issues Content-Type: application/json { "title": "Found a bug", "body": "Bug description here", "labels": ["bug"], "assignees": ["username"] } ``` Example: ```bash maton github issue create --repo {owner}/{repo} --title "Found a bug" --body "Bug description here" --label bug --assignee username ``` #### Update Issue ```bash PATCH /github/repos/{owner}/{repo}/issues/{issue_number} Content-Type: application/json { "state": "closed", "state_reason": "completed" } ``` Example: ```bash maton github issue close {issue_number} --repo {owner}/{repo} --reason completed ``` #### Lock Issue ```bash PUT /github/repos/{owner}/{repo}/issues/{issue_number}/lock Content-Type: application/json { "lock_reason": "resolved" } ``` Example: ```bash maton github issue lock {issue_number} --repo {owner}/{repo} --reason resolved ``` #### Unlock Issue ```bash DELETE /github/repos/{owner}/{repo}/issues/{issue_number}/lock ``` Example: ```bash maton github issue unlock {issue_number} --repo {owner}/{repo} ``` ### Issue Comments #### List Issue Comments ```bash GET /github/repos/{owner}/{repo}/issues/{issue_number}/comments?per_page=30 ``` Example: ```bash maton github issue view {issue_number} --repo {owner}/{repo} --comments ``` #### Create Issue Comment ```bash POST /github/repos/{owner}/{repo}/issues/{issue_number}/comments Content-Type: application/json { "body": "This is a comment" } ``` Example: ```bash maton github issue comment {issue_number} --repo {owner}/{repo} --body "This is a comment" ``` #### Update Issue Comment ```bash PATCH /github/repos/{owner}/{repo}/issues/comments/{comment_id} Content-Type: application/json { "body": "Updated comment" } ``` #### Delete Issue Comment ```bash DELETE /github/repos/{owner}/{repo}/issues/comments/{comment_id} ``` ### Labels #### List Labels ```bash GET /github/repos/{owner}/{repo}/labels?per_page=30 ``` Example: ```bash maton github label list --repo {owner}/{repo} ``` #### Create Label ```bash POST /github/repos/{owner}/{repo}/labels Content-Type: application/json { "name": "priority:high", "color": "ff0000", "description": "High priority issues" } ``` Example: ```bash maton github label create "priority:high" --repo {owner}/{repo} --color ff0000 --description "High priority issues" ``` ### Milestones #### List Milestones ```bash GET /github/repos/{owner}/{repo}/milestones?state=open&per_page=30 ``` #### Create Milestone ```bash POST /github/repos/{owner}/{repo}/milestones Content-Type: application/json { "title": "v1.0", "state": "open", "description": "First release", "due_on": "2026-03-01T00:00:00Z" } ``` ### Pull Requests #### List Pull Requests ```bash GET /github/repos/{owner}/{repo}/pulls?state=open&per_page=30 ``` Query parameters: `state` (open, closed, all), `head`, `base`, `sort`, `direction`, `per_page`, `page` Example: ```bash maton github pr list --repo {owner}/{repo} --state open ``` #### Get Pull Request ```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number} ``` Example: ```bash maton github pr view {pull_number} --repo {owner}/{repo} ``` #### Create Pull Request ```bash POST /github/repos/{owner}/{repo}/pulls Content-Type: application/json { "title": "New feature", "body": "Description of changes", "head": "feature-branch", "base": "main", "draft": false } ``` Example: ```bash maton github pr create --repo {owner}/{repo} --base main --head feature-branch --title "New feature" --body "Description of changes" ``` #### Update Pull Request ```bash PATCH /github/repos/{owner}/{repo}/pulls/{pull_number} Content-Type: application/json { "title": "Updated title", "state": "closed" } ``` Example: ```bash maton github pr edit {pull_number} --repo {owner}/{repo} --title "Updated title" ``` #### List Pull Request Commits ```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/commits?per_page=30 ``` #### List Pull Request Files ```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/files?per_page=30 ``` Example: ```bash maton github pr diff {pull_number} --repo {owner}/{repo} ``` #### Check If Merged ```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/merge ``` #### Merge Pull Request ```bash PUT /github/repos/{owner}/{repo}/pulls/{pull_number}/merge Content-Type: application/json { "commit_title": "Merge pull request", "merge_method": "squash" } ``` Merge methods: `merge`, `squash`, `rebase` Example: ```bash maton github pr merge {pull_number} --repo {owner}/{repo} --squash --delete-branch ``` ### Pull Request Reviews #### List Reviews ```bash GET /github/repos/{owner}/{repo}/pulls/{pull_number}/reviews?per_page=30 ``` #### Create Review ```bash POST /github/repos/{owner}/{repo}/pulls/{pull_number}/reviews Content-Type: application/json { "body": "Looks good!", "event": "APPROVE" } ``` Events: `APPROVE`, `REQUEST_CHANGES`, `COMMENT` Example: ```bash maton github pr review {pull_number} --repo {owner}/{repo} --approve --body "Looks good!" ``` Note: GitHub does not allow approving your own pull requests; `--approve` returns `422 Can not approve your own pull request` in that case. Use `--comment` or `--request-changes` instead. ### Search #### Search Repositories ```bash GET /github/search/repositories?q={query}&per_page=30 ``` Example queries: - `tetris+language:python` - Repositories with "tetris" in Python - `react+stars:>10000` - Repositories with "react" and 10k+ stars Example: ```bash maton github repo search tetris --language python ``` #### Search Issues ```bash GET /github/search/issues?q={query}&per_page=30 ``` Example queries: - `bug+is:open+is:issue` - Open issues containing "bug" - `author:username+is:pr` - Pull requests by author Example: ```bash maton github issue search "bug" --state open ``` #### Search Code ```bash GET /github/search/code?q={query}&per_page=30 ``` Example queries: - `addClass+repo:facebook/react` - Search for "addClass" in a specific repo - `function+extension:js` - JavaScript functions Note: Code search may timeout on broad queries. #### Search Users ```bash GET /github/search/users?q={query}&per_page=30 ``` ### Organizations #### List User Organizations ```bash GET /github/user/orgs?per_page=30 ``` Note: Requires `read:org` scope. #### Get Organization ```bash GET /github/orgs/{org} ``` #### List Organization Members ```bash GET /github/orgs/{org}/members?per_page=30 ``` ### Rate Limit #### Get Rate Limit ```bash GET /github/rate_limit ``` ## Pagination GitHub uses page-based pagination. The CLI automatically paginates with '--paginate'. Example: ```bash maton github repo list --paginate ``` ## Code Examples ### CLI ```bash # Get repos as JSON (full objects) maton github repo list --json # Project specific fields with jq maton github repo list --json --jq '.[] | {name, full_name, private}' # Filter — e.g., only public repos maton github repo list --json --jq '.[] | select(.private == false) | .name' # Extract a single field maton github issue list --repo owner/repo --json --jq '.[].title' ``` ### JavaScript ```javascript const response = await fetch( 'https://api.maton.ai/github/repos/owner/repo/issues?state=open&per_page=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const issues = await response.json(); ``` ### Python ```python import os import requests response = requests.get( 'https://api.maton.ai/github/repos/owner/repo/issues', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'state': 'open', 'per_page': 10} ) issues = response.json() ``` ## Notes - Repository names are case-insensitive but the API preserves case - Issue numbers and PR numbers share the same sequence per repository - Content must be Base64 encoded when creating/updating files - Rate limits: 5000 requests/hour for authenticated users, 30 searches/minute - Search queries may timeout on very broad patterns - Some endpoints require specific OAuth scopes (e.g., `read:org` for organization operations). If you receive a scope error, contact Maton support at [REDACTED_SECRET] with the specific operations/APIs you need and your use-case - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing GitHub connection | | 401 | Invalid or missing Maton API key | | 403 | Forbidden - insufficient permissions or scope | | 404 | Resource not found | | 408 | Request timeout (common for complex searches) | | 422 | Validation failed | | 429 | Rate limited | | 4xx/5xx | Passthrough error from GitHub API | ### Troubleshooting: API Key Issues **CLI:** 1. Check your auth state: ```bash maton whoami ``` 2. Verify the API key is valid by listing connections: ```bash maton connection list ``` **Manual:** 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Troubleshooting: Invalid App Name 1. Ensure your URL path starts with `github`. For example: - Correct: `https://api.maton.ai/github/user` - Incorrect: `https://api.maton.ai/api.github.com/user` ## Resources - [GitHub REST API Documentation](https://docs.github.com/en/rest) - [Repositories API](https://docs.github.com/en/rest/repos/repos) - [Issues API](https://docs.github.com/en/rest/issues/issues) - [Pull Requests API](https://docs.github.com/en/rest/pulls/pulls) - [Search API](https://docs.github.com/en/rest/search/search) - [Rate Limits](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) - [Maton CLI Manual](https://cli.maton.ai/manual) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[REDACTED_SECRET])


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)