Back to Details

github-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LIBRARY-FIRST PROTOCOL (MANDATORY)

优先使用库的协议（强制性）

Before writing ANY code, you MUST check:
在编写任何代码之前，你必须检查：

Step 1: Library Catalog

步骤1：库目录

  • Location: 
    .claude/library/catalog.json
  • If match >70%: REUSE or ADAPT
  • 位置：
    .claude/library/catalog.json
  • 如果匹配度>70%：复用或适配

Step 2: Patterns Guide

步骤2：模式指南

  • Location: 
    .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
  • If pattern exists: FOLLOW documented approach
  • 位置：
    .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
  • 如果模式已存在：遵循文档记录的方法

Step 3: Existing Projects

步骤3：现有项目

  • Location: 
    D:\Projects\*
  • If found: EXTRACT and adapt
  • 位置：
    D:\Projects\*
  • 如果找到：提取并适配

Decision Matrix

决策矩阵

MatchAction
Library >90%REUSE directly
Library 70-90%ADAPT minimally
Pattern existsFOLLOW pattern
In projectEXTRACT
No matchBUILD (add to library after)
匹配度操作
库匹配度>90%直接复用
库匹配度70-90%最小程度适配
模式已存在遵循模式
存在于现有项目中提取
无匹配项构建（完成后添加到库中）

STANDARD OPERATING PROCEDURE

标准操作流程

Purpose

目的

Design and implement GitHub-centric integrations (API, Apps, webhooks) with secure auth, observability, and rollback-ready automation.
设计并实现以GitHub为中心的集成（API、应用、Webhook），具备安全认证、可观测性和可回滚的自动化能力。

Trigger Conditions

触发条件

  • Positive: Need GitHub automation or webhook bridge; Integrating GitHub with external systems; Auditable GitHub API usage across repos
  • Negative: Release orchestration (route to github-release-management); Cross-repo campaign (route to github-multi-repo); Project board design (route to github-project-management)
  • 正向触发：需要GitHub自动化或Webhook桥接；将GitHub与外部系统集成；跨仓库的可审计GitHub API使用
  • 反向触发（需转至其他流程）：发布编排（转至github-release-management）；跨仓库活动（转至github-multi-repo）；项目看板设计（转至github-project-management）

Guardrails

防护规则

  • Structure-first: keep SKILL.md aligned with examples/, tests/, and any resources/references so downstream agents always have scaffolding.
  • Adversarial validation is mandatory: cover boundary cases, failure paths, and rollback drills before declaring the SOP complete.
  • Prompt hygiene: separate hard vs. soft vs. inferred constraints and confirm inferred constraints before acting.
  • Explicit confidence ceilings: format as 'Confidence: X.XX (ceiling: TYPE Y.YY)' and never exceed the ceiling for the claim type.
  • MCP traceability: tag sessions WHO=operations-{name}-{session_id}, WHY=skill-execution, and capture evidence links in outputs.
  • Avoid anti-patterns: undocumented changes, missing rollback paths, skipped tests, or unbounded automation without approvals.
  • 优先结构化：保持SKILL.md与examples/、tests/及任何资源/参考文档一致，确保下游Agent始终有可用的脚手架。
  • 必须进行对抗性验证：在宣布SOP完成前，覆盖边界案例、故障路径和回滚演练。
  • 提示规范：区分硬约束、软约束和推断约束，并在行动前确认推断约束。
  • 明确置信度上限：格式为'置信度：X.XX（上限：类型 Y.YY）'，且绝不超过声明类型的置信度上限。
  • MCP可追溯性：为会话标记WHO=operations-{name}-{session_id}、WHY=skill-execution，并在输出中捕获证据链接。
  • 避免反模式：未记录的变更、缺失的回滚路径、跳过测试，或无审批的无限制自动化。

Required Artifacts

必需工件

  • SKILL.md (this SOP)
  • readme.md with usage examples
  • examples/ for integration flows
  • tests/ for scripts/actions
  • resources/ and shared-scripts/ for reuse
  • references/ with API constraints
  • SKILL.md（本标准操作流程）
  • 包含使用示例的readme.md
  • 用于集成流程的examples/目录
  • 用于脚本/操作的tests/目录
  • 用于复用的resources/和shared-scripts/目录
  • 包含API约束的references/目录

Execution Phases

执行阶段

  1. Assess integration surface
    • Map repos, events, and permissions required
    • Confirm auth model (GitHub App, PAT, OIDC) and rotation plan
    • Identify rate limits and audit requirements
  2. Design event and API flows
    • Define webhook payload handling, retries, and signature validation
    • Specify idempotency, deduplication, and backoff policies
    • Plan data mapping and error handling between systems
  3. Implement automation
    • Build or reuse scripts/actions with least privilege
    • Add logging/metrics and sandbox tests
    • Gate production rollout with dry runs and approvals
  4. Validate and operate
    • Run integration tests and failure-injection scenarios
    • Set up monitoring, alerts, and dashboards
    • Document runbooks, fallbacks, and support contacts
  1. 评估集成范围
    • 映射所需的仓库、事件和权限
    • 确认认证模型（GitHub App、PAT、OIDC）和轮换计划
    • 识别速率限制和审计要求
  2. 设计事件与API流程
    • 定义Webhook负载处理、重试和签名验证逻辑
    • 制定幂等性、去重和退避策略
    • 规划系统间的数据映射和错误处理
  3. 实现自动化
    • 以最小权限原则构建或复用脚本/操作
    • 添加日志/指标并进行沙箱测试
    • 通过试运行和审批机制管控生产环境部署
  4. 验证与运维
    • 运行集成测试和故障注入场景
    • 设置监控、告警和仪表盘
    • 记录运行手册、回退方案和支持联系人

Output Format

输出格式

  • Integration design doc with events, permissions, and rate-limit posture
  • Auth and secret management plan with rotation cadence
  • Implemented automation artifacts (scripts/actions) with test evidence
  • Monitoring and alert plan with dashboards/links
  • Runbook with rollback/disablement steps and owners
  • 包含事件、权限和速率限制策略的集成设计文档
  • 包含轮换周期的认证与密钥管理计划
  • 附带测试证据的已实现自动化工件（脚本/操作）
  • 包含仪表盘/链接的监控与告警计划
  • 包含回滚/禁用步骤及负责人的运行手册

Validation Checklist

验证清单

  • Tokens/keys scoped to least privilege and rotated
  • Webhook verification, retries, and idempotency tested
  • Integration tested in staging or dry-run mode
  • Audit trail and observability hooks enabled
  • Confidence ceiling stated for go-live
Confidence: 0.70 (ceiling: inference 0.70) - GitHub integration steps follow validated automation guardrails
  • 令牌/密钥已按最小权限原则划分范围并设置轮换
  • Webhook验证、重试和幂等性已测试
  • 集成已在预发布环境或试运行模式下测试
  • 审计追踪和可观测性钩子已启用
  • 已声明上线的置信度上限
置信度：0.70（上限：推断 0.70）- GitHub集成步骤遵循已验证的自动化防护规则