Back to Details

github-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub API Orchestration Skill

GitHub API编排技能

Comprehensive skill for working with the GitHub API across all services and operations. This skill provides intelligent routing to focused resource files covering both REST API v3 and GraphQL API v4.
一款可用于所有服务和操作的GitHub API综合技能。该技能可智能路由至涵盖REST API v3和GraphQL API v4的针对性资源文件。

Quick Reference: When to Load Which Resource

快速参考：何时加载对应资源

Use CaseLoad ResourceKey Concepts
Setting up authentication, checking rate limits, handling errors, pagination
resources/rest-api-basics.md
Auth methods, rate limits, error codes, ETags, conditional requests
Creating/managing repos, branches, commits, releases, tags, Git objects
resources/repositories.md
Repo CRUD, branch protection, file operations, releases, Git data
Working with issues, PRs, reviews, comments, labels, milestones
resources/issues-pull-requests.md
Issue tracking, code review, approvals, merging, reactions
Managing users, organizations, teams, permissions, membership
resources/users-organizations-teams.md
User profiles, org operations, team management, collaborators
Automating workflows, CI/CD runs, artifacts, secrets, runners
resources/workflows-actions.md
Workflow triggers, run management, artifacts, env secrets, runners
Searching repositories, code, issues, commits, users
resources/search-content.md
Repository discovery, code search, issue search, user lookup
Security scanning, packages, webhooks, notifications, gists, projects, apps
resources/security-webhooks.md
Dependabot, code scanning, packages, webhooks, notifications, apps
使用场景加载资源核心概念
设置身份验证、检查速率限制、处理错误、分页
resources/rest-api-basics.md
身份验证方法、速率限制、错误代码、ETag、条件请求
创建/管理仓库、分支、提交、发布、标签、Git对象
resources/repositories.md
仓库增删改查、分支保护、文件操作、发布、Git数据
处理议题、拉取请求、评审、评论、标签、里程碑
resources/issues-pull-requests.md
议题追踪、代码评审、审批、合并、反应
管理用户、组织、团队、权限、成员资格
resources/users-organizations-teams.md
用户资料、组织操作、团队管理、协作者
自动化工作流、CI/CD运行、制品、密钥、运行器
resources/workflows-actions.md
工作流触发器、运行管理、制品、环境密钥、运行器
搜索仓库、代码、议题、提交、用户
resources/search-content.md
仓库发现、代码搜索、议题搜索、用户查找
安全扫描、包、Webhook、通知、Gist、项目、应用
resources/security-webhooks.md
Dependabot、代码扫描、包、Webhook、通知、应用

Orchestration Protocol

编排协议

Phase 1: Identify Your Task

阶段1：识别任务

Before loading a resource, classify your GitHub API needs:
Task Type Indicators:
  • Setting up: Authentication, testing credentials → Load 
    rest-api-basics.md
  • Repository work: Creating, configuring, managing repos and branches → Load 
    repositories.md
  • Collaboration: Issues, PRs, code reviews → Load 
    issues-pull-requests.md
  • Automation: Workflows, CI/CD, runners → Load 
    workflows-actions.md
  • Organization: Users, teams, permissions → Load 
    users-organizations-teams.md
  • Discovery: Finding repositories or code → Load 
    search-content.md
  • Advanced: Security features, webhooks, packages → Load 
    security-webhooks.md
Complexity Patterns:
  • Single operation: Load one resource file
  • Multi-step workflow: May need 2-3 related resources (e.g., search + repository + workflows)
  • Complex integration: Combine foundational + specialized resources
加载资源前，请对您的GitHub API需求进行分类：
任务类型标识：
  • 设置类：身份验证、测试凭证 → 加载
    rest-api-basics.md
  • 仓库操作：创建、配置、管理仓库和分支 → 加载
    repositories.md
  • 协作类：议题、拉取请求、代码评审 → 加载
    issues-pull-requests.md
  • 自动化类：工作流、CI/CD、运行器 → 加载
    workflows-actions.md
  • 组织管理：用户、团队、权限 → 加载
    users-organizations-teams.md
  • 发现类：查找仓库或代码 → 加载
    search-content.md
  • 进阶类：安全功能、Webhook、包 → 加载
    security-webhooks.md
复杂度模式：
  • 单一操作：加载一个资源文件
  • 多步骤工作流：可能需要2-3个相关资源（例如：搜索 + 仓库 + 工作流）
  • 复杂集成：结合基础资源与专用资源

Phase 2: Load and Execute

阶段2：加载与执行

  1. Load the appropriate resource file(s)
  2. Find the specific API operation or pattern you need
  3. Adapt the example to your use case
  4. Execute with appropriate authentication
  1. 加载对应的资源文件
  2. 找到您需要的特定API操作或模式
  3. 根据您的用例调整示例
  4. 使用合适的身份验证执行操作

Phase 3: Validate & Monitor

阶段3：验证与监控

  • Verify API responses are successful
  • Check rate limit headers if making multiple calls
  • Handle errors according to error handling patterns in 
    rest-api-basics.md
  • 验证API响应是否成功
  • 若进行多次调用，请检查速率限制头信息
  • 根据
    rest-api-basics.md
    中的错误处理模式处理错误

API Endpoints Overview

API端点概述

REST API v3

REST API v3

  • Base URL: 
    https://api.github.com
  • Authentication: Token, PAT, GitHub Apps
  • Rate Limit: 5,000 requests/hour (authenticated)
  • Use for: Straightforward CRUD operations on resources
  • 基础URL：
    https://api.github.com
  • 身份验证：Token、PAT、GitHub Apps
  • 速率限制：5000次请求/小时（已认证）
  • 适用场景：资源的简单增删改查操作

GraphQL API v4

GraphQL API v4

  • Endpoint: 
    https://api.github.com/graphql
  • Authentication: Bearer token
  • Rate Limit: 5,000 points/hour (query-dependent)
  • Use for: Complex queries combining multiple data types, mutations
  • 端点：
    https://api.github.com/graphql
  • 身份验证：Bearer token
  • 速率限制：5000点数/小时（取决于查询）
  • 适用场景：组合多种数据类型的复杂查询、变更操作

Most Common Operations

最常用操作

Quick Command Reference

快速命令参考

bash
undefined
bash
undefined

Repository operations

Repository operations

gh repo create NAME gh repo view owner/repo gh repo clone owner/repo
gh repo create NAME gh repo view owner/repo gh repo clone owner/repo

Issues

Issues

gh issue list gh issue create gh issue close NUMBER
gh issue list gh issue create gh issue close NUMBER

Pull requests

Pull requests

gh pr list gh pr create gh pr merge NUMBER
gh pr list gh pr create gh pr merge NUMBER

Actions

Actions

gh workflow run WORKFLOW gh run list gh run view RUN_ID
gh workflow run WORKFLOW gh run list gh run view RUN_ID

Search

Search

gh api search/repositories -f q="QUERY" gh api search/code -f q="QUERY" gh api search/issues -f q="QUERY"
gh api search/repositories -f q="QUERY" gh api search/code -f q="QUERY" gh api search/issues -f q="QUERY"

Authentication

Authentication

gh auth login gh auth status gh auth token
undefined
gh auth login gh auth status gh auth token
undefined

Authentication Guide (Quick Start)

身份验证指南（快速开始）

GitHub CLI (Recommended)

GitHub CLI（推荐）

bash
gh auth login
gh api /user  # Test authentication
bash
gh auth login
gh api /user  # Test authentication

Personal Access Token

个人访问令牌（Personal Access Token）

bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user
→ See 
resources/rest-api-basics.md
for complete auth details
bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user
→ 完整身份验证详情请查看
resources/rest-api-basics.md

Common Patterns

常见模式

Bulk Repository Operations

批量仓库操作

bash
undefined
bash
undefined

Add label to multiple issues

Add label to multiple issues

for issue in 1 2 3; do gh api repos/owner/repo/issues/$issue/labels -X POST -f labels[]=bug sleep 1 # Rate limiting done
undefined
for issue in 1 2 3; do gh api repos/owner/repo/issues/$issue/labels -X POST -f labels[]=bug sleep 1 # Rate limiting done
undefined

Workflow Integration

工作流集成

bash
undefined
bash
undefined

Trigger workflow with inputs

Trigger workflow with inputs

gh workflow run build.yml -f environment=production
gh workflow run build.yml -f environment=production

Monitor run status

Monitor run status

gh api repos/owner/repo/actions/runs -f per_page=1
--jq '.workflow_runs[0].conclusion'
undefined
gh api repos/owner/repo/actions/runs -f per_page=1
--jq '.workflow_runs[0].conclusion'
undefined

Error Handling

错误处理

bash
undefined
bash
undefined

Check response status

Check response status

response=$(gh api repos/owner/repo -i 2>&1) if echo "$response" | grep -q "HTTP/2 404"; then echo "Not found" fi

→ See `resources/rest-api-basics.md` for comprehensive error handling
response=$(gh api repos/owner/repo -i 2>&1) if echo "$response" | grep -q "HTTP/2 404"; then echo "Not found" fi

→ 完整错误处理请查看`resources/rest-api-basics.md`

Resource File Summaries

资源文件摘要

  • rest-api-basics.md (369 lines): Authentication, rate limiting, pagination, error handling, best practices
  • repositories.md (231 lines): Repo CRUD, branches, protection, commits, releases, Git data
  • issues-pull-requests.md (272 lines): Issue tracking, PR management, reviews, approvals, code comments
  • users-organizations-teams.md (162 lines): User operations, org management, teams, membership
  • workflows-actions.md (211 lines): Workflow management, runs, artifacts, secrets, runners
  • search-content.md (150 lines): Repository search, code search, issue/PR search, user/commit search
  • security-webhooks.md (386 lines): Dependabot, code scanning, packages, webhooks, notifications, gists, apps, projects
  • rest-api-basics.md（369行）：身份验证、速率限制、分页、错误处理、最佳实践
  • repositories.md（231行）：仓库增删改查、分支、保护、提交、发布、Git数据
  • issues-pull-requests.md（272行）：议题追踪、拉取请求管理、评审、审批、代码评论
  • users-organizations-teams.md（162行）：用户操作、组织管理、团队、成员资格
  • workflows-actions.md（211行）：工作流管理、运行、制品、密钥、运行器
  • search-content.md（150行）：仓库搜索、代码搜索、议题/拉取请求搜索、用户/提交搜索
  • security-webhooks.md（386行）：Dependabot、代码扫描、包、Webhook、通知、Gist、应用、项目

Best Practices Summary

最佳实践摘要

1. Rate Limiting

1. 速率限制

  • Use conditional requests with ETags to avoid counting against limits
  • Implement exponential backoff when hitting limits
  • Use GraphQL for complex multi-resource queries
  • Check 
    rate_limit
    endpoint before batch operations
  • 使用带ETag的条件请求，避免占用限制额度
  • 触发限制时实现指数退避机制
  • 复杂多资源查询使用GraphQL
  • 批量操作前检查
    rate_limit
    端点

2. Authentication

2. 身份验证

  • Use fine-grained PATs with minimal scopes
  • Prefer GitHub Apps for integrations
  • Use 
    gh
    CLI when available
  • Never commit tokens to version control
  • 使用权限范围最小的细粒度PAT
  • 集成场景优先使用GitHub Apps
  • 尽可能使用
    gh
    CLI
  • 切勿将令牌提交至版本控制系统

3. Error Handling

3. 错误处理

  • Implement retry logic with exponential backoff
  • Validate input before sending requests
  • Check rate limits before making requests
  • Log errors with context
  • 实现带指数退避的重试逻辑
  • 发送请求前验证输入
  • 发起请求前检查速率限制
  • 附带上下文记录错误

4. Performance

4. 性能

  • Use GraphQL for complex data requirements combining multiple resources
  • Implement pagination properly
  • Cache responses when appropriate
  • Use webhooks instead of polling
→ See 
resources/rest-api-basics.md
for detailed patterns
  • 复杂多资源数据需求使用GraphQL
  • 正确实现分页
  • 适当缓存响应
  • 使用Webhook替代轮询
→ 详细模式请查看
resources/rest-api-basics.md

GraphQL vs REST Decision Tree

GraphQL与REST决策树

Use GraphQL API v4 when:
  • Querying multiple related resources (e.g., repo + issues + PRs in one call)
  • Complex filtering or sorting requirements
  • Need precise field selection (bandwidth optimization)
  • Working with Projects V2
Use REST API v3 when:
  • Simple, straightforward resource operations
  • Comfort with REST patterns
  • Legacy integrations
  • Bulk operations (GitHub CLI integration)
当以下情况时使用GraphQL API v4：
  • 查询多个相关资源（例如：一次调用获取仓库 + 议题 + 拉取请求）
  • 复杂过滤或排序需求
  • 需要精确字段选择（带宽优化）
  • 处理Projects V2
当以下情况时使用REST API v3：
  • 简单直接的资源操作
  • 熟悉REST模式
  • 遗留集成
  • 批量操作（GitHub CLI集成）

Troubleshooting Quick Links

故障排除快速链接

ProblemResourceSection
"403 rate limited"rest-api-basics.mdRate Limiting
"401 unauthorized"rest-api-basics.mdAuthentication Methods
"422 validation failed"rest-api-basics.mdError Response Format
Cannot push to branchrepositories.mdBranch Protection
Merge conflicts in PRissues-pull-requests.mdMerging
Workflow not triggeringworkflows-actions.mdWorkflow Management
Results not searchable yetsearch-content.mdSearch Code/Repositories
问题资源章节
"403 rate limited"rest-api-basics.md速率限制
"401 unauthorized"rest-api-basics.md身份验证方法
"422 validation failed"rest-api-basics.md错误响应格式
无法推送到分支repositories.md分支保护
拉取请求中存在合并冲突issues-pull-requests.md合并
工作流未触发workflows-actions.md工作流管理
结果无法被搜索到search-content.md搜索代码/仓库

External Resources

外部资源

Remember: This is a modular reference organized by service area. Load only the resource files relevant to your current task. All major GitHub API operations are covered; use the quick reference table to find the right starting point.
提示：这是按服务领域划分的模块化参考。仅加载与当前任务相关的资源文件。所有主要GitHub API操作均已覆盖；请使用快速参考表找到合适的起始点。