Claude Code Action 原始碼解讀：GitHub Action 中的雙模式架構與 MCP 整合設計

claude-code-action/
├── action.yml                    # Composite action 定義，串接所有步驟
├── src/
│   ├── entrypoints/              # Action 進入點（Phase 1）
│   │   ├── prepare.ts            # 主要準備邏輯：認證、驗證、觸發偵測
│   │   ├── update-comment-link.ts # 執行後更新 comment
│   │   ├── format-turns.ts       # 對話格式化
│   │   ├── cleanup-ssh-signing.ts # SSH 金鑰清理
│   │   └── collect-inputs.ts     # 收集 action inputs
│   ├── modes/                    # 模式系統
│   │   ├── detector.ts           # 自動模式偵測
│   │   ├── registry.ts           # 模式註冊表
│   │   ├── types.ts              # Mode interface 定義
│   │   ├── tag/index.ts          # Tag 模式實作
│   │   └── agent/index.ts        # Agent 模式實作
│   ├── github/                   # GitHub 整合層
│   │   ├── context.ts            # 統一的事件上下文解析
│   │   ├── token.ts              # OIDC token 交換與認證
│   │   ├── api/                  # REST/GraphQL client
│   │   ├── data/                 # 資料擷取與格式化
│   │   ├── validation/           # 權限與觸發驗證
│   │   ├── operations/           # 分支、留言、Git 操作
│   │   └── utils/                # 清潔、圖片下載
│   ├── mcp/                      # MCP Server 實作
│   │   ├── install-mcp-server.ts # MCP 配置組裝
│   │   ├── github-comment-server.ts    # 留言操作
│   │   ├── github-file-ops-server.ts   # 檔案操作（commit signing）
│   │   ├── github-actions-server.ts    # CI/CD 存取
│   │   └── github-inline-comment-server.ts # PR inline comment
│   ├── create-prompt/            # Prompt 生成
│   └── prepare/                  # 準備階段編排
├── base-action/                  # Phase 2：Claude Code 執行核心
│   └── src/
│       ├── index.ts              # base-action 進入點
│       ├── run-claude-sdk.ts     # Claude Agent SDK 呼叫
│       ├── run-claude.ts         # CLI 執行邏輯
│       ├── prepare-prompt.ts     # Prompt 檔案處理
│       └── setup-claude-code-settings.ts # 設定管理
└── test/                         # 測試
Code language: PHP (php)

steps:
  - name: Prepare action
    id: prepare
    shell: bash
    run: bun run ${GITHUB_ACTION_PATH}/src/entrypoints/prepare.ts

  - name: Run Claude Code
    id: claude-code
    if: steps.prepare.outputs.contains_trigger == 'true'
    shell: bash
    run: bun run ${GITHUB_ACTION_PATH}/base-action/src/index.ts
Code language: JavaScript (javascript)

async function run() {
  collectActionInputsPresence();
  const context = parseGitHubContext();
  const mode = getMode(context);
  const githubToken = await setupGitHubToken();
  const octokit = createOctokit(githubToken);

  if (isEntityContext(context)) {
    const hasWritePermissions = await checkWritePermissions(
      octokit.rest, context, context.inputs.allowedNonWriteUsers, githubTokenProvided,
    );
    if (!hasWritePermissions) {
      throw new Error("Actor does not have write permissions to the repository");
    }
  }

  const containsTrigger = mode.shouldTrigger(context);
  core.setOutput("contains_trigger", containsTrigger.toString());

  if (!containsTrigger) {
    console.log("No trigger found, skipping remaining steps");
    return;
  }

  const result = await prepare({ context, octokit, mode, githubToken });
}
Code language: JavaScript (javascript)

export type Mode = {
  name: ModeName;
  description: string;
  shouldTrigger(context: GitHubContext): boolean;
  prepareContext(context: GitHubContext, data?: ModeData): ModeContext;
  getAllowedTools(): string[];
  getDisallowedTools(): string[];
  shouldCreateTrackingComment(): boolean;
  generatePrompt(context: PreparedContext, githubData: FetchDataResult, useCommitSigning: boolean): string;
  prepare(options: ModeOptions): Promise<ModeResult>;
  getSystemPrompt?(context: ModeContext): string | undefined;
};
Code language: JavaScript (javascript)

const modes = {
  tag: tagMode,
  agent: agentMode,
} as const satisfies Record<AutoDetectedMode, Mode>;

export function getMode(context: GitHubContext): Mode {
  const modeName = detectMode(context);
  const mode = modes[modeName];
  if (!mode) {
    throw new Error(`Mode '${modeName}' not found.`);
  }
  return mode;
}
Code language: JavaScript (javascript)

export function detectMode(context: GitHubContext): AutoDetectedMode {
  if (context.inputs.trackProgress) {
    validateTrackProgressEvent(context);
  }

  // 如果設定了 track_progress，強制使用 tag 模式
  if (context.inputs.trackProgress && isEntityContext(context)) {
    if (isPullRequestEvent(context) || isIssuesEvent(context) || ...) {
      return "tag";
    }
  }

  // Comment 事件：有 prompt 就用 agent，有 @claude 就用 tag
  if (isEntityContext(context)) {
    if (isIssueCommentEvent(context) || isPullRequestReviewCommentEvent(context) || ...) {
      if (context.inputs.prompt) return "agent";
      if (checkContainsTrigger(context)) return "tag";
    }
  }

  // 預設回到 agent 模式
  return "agent";
}
Code language: JavaScript (javascript)

type EntityEventName = "issues" | "issue_comment" | "pull_request"
  | "pull_request_review" | "pull_request_review_comment";
type AutomationEventName = "workflow_dispatch" | "repository_dispatch"
  | "schedule" | "workflow_run";

export type ParsedGitHubContext = BaseContext & {
  eventName: EntityEventName;
  payload: IssuesEvent | IssueCommentEvent | PullRequestEvent | ...;
  entityNumber: number;
  isPR: boolean;
};

export type AutomationContext = BaseContext & {
  eventName: AutomationEventName;
  payload: WorkflowDispatchEvent | RepositoryDispatchEvent | ...;
};

export type GitHubContext = ParsedGitHubContext | AutomationContext;
Code language: JavaScript (javascript)

export function isEntityContext(context: GitHubContext): context is ParsedGitHubContext {
  return ENTITY_EVENT_NAMES.includes(context.eventName as EntityEventName);
}

export function isIssueCommentEvent(context: GitHubContext):
  context is ParsedGitHubContext & { payload: IssueCommentEvent } {
  return context.eventName === "issue_comment";
}
Code language: JavaScript (javascript)

export async function prepareMcpConfig(params: PrepareConfigParams): Promise<string> {
  const baseMcpConfig: { mcpServers: Record<string, unknown> } = { mcpServers: {} };

  // Comment server：tag 模式必備，agent 模式只在明確要求時啟用
  const shouldIncludeCommentServer = !isAgentMode || hasGitHubCommentTools;
  if (shouldIncludeCommentServer) {
    baseMcpConfig.mcpServers.github_comment = { /* ... */ };
  }

  // File ops server：只有啟用 commit signing 時才啟用
  if (context.inputs.useCommitSigning) {
    baseMcpConfig.mcpServers.github_file_ops = { /* ... */ };
  }

  // Inline comment server：只對 PR 且明確要求時啟用
  if (isEntityContext(context) && context.isPR && (hasGitHubMcpTools || hasInlineCommentTools)) {
    baseMcpConfig.mcpServers.github_inline_comment = { /* ... */ };
  }

  // CI server：需要額外權限檢查
  if (shouldIncludeCIServer) {
    const actuallyHasPermission = await checkActionsReadPermission(
      process.env.DEFAULT_WORKFLOW_TOKEN || "", owner, repo
    );
    if (actuallyHasPermission) {
      baseMcpConfig.mcpServers.github_ci = { /* ... */ };
    }
  }

  return JSON.stringify(baseMcpConfig, null, 2);
}
Code language: JavaScript (javascript)

export async function checkHumanActor(octokit: Octokit, githubContext: GitHubContext) {
  const { data: userData } = await octokit.users.getByUsername({
    username: githubContext.actor,
  });

  if (actorType !== "User") {
    const allowedBots = githubContext.inputs.allowedBots;
    if (allowedBots.trim() === "*") return;  // 允許所有 bot
    // 檢查特定 bot 白名單...
    throw new Error(`Workflow initiated by non-human actor: ${botName}`);
  }
}
Code language: JavaScript (javascript)

export async function checkWritePermissions(
  octokit: Octokit, context: ParsedGitHubContext,
  allowedNonWriteUsers?: string, githubTokenProvided?: boolean
): Promise<boolean> {
  // 如果設定了 allowedNonWriteUsers 且提供了自訂 token，可以繞過
  if (allowedNonWriteUsers && githubTokenProvided) {
    core.warning(`SECURITY WARNING: Bypassing write permission check...`);
    return true;
  }

  const response = await octokit.repos.getCollaboratorPermissionLevel({
    owner: repository.owner, repo: repository.repo, username: actor
  });
  return permissionLevel === "admin" || permissionLevel === "write";
}
Code language: JavaScript (javascript)

export function filterCommentsToTriggerTime<
  T extends { createdAt: string; updatedAt?: string; lastEditedAt?: string }
>(comments: T[], triggerTime: string | undefined): T[] {
  if (!triggerTime) return comments;
  const triggerTimestamp = new Date(triggerTime).getTime();

  return comments.filter((comment) => {
    const createdTimestamp = new Date(comment.createdAt).getTime();
    if (createdTimestamp >= triggerTimestamp) return false;

    const lastEditTime = comment.lastEditedAt || comment.updatedAt;
    if (lastEditTime) {
      const lastEditTimestamp = new Date(lastEditTime).getTime();
      if (lastEditTimestamp >= triggerTimestamp) return false;
    }
    return true;
  });
}
Code language: JavaScript (javascript)

export function sanitizeContent(content: string): string {
  content = stripHtmlComments(content);          // 移除 HTML 註解（常見注入向量）
  content = stripInvisibleCharacters(content);    // 移除零寬字元
  content = stripMarkdownImageAltText(content);   // 清除圖片 alt text
  content = stripMarkdownLinkTitles(content);     // 清除連結 title
  content = stripHiddenAttributes(content);       // 清除 data-* 等隱藏屬性
  content = normalizeHtmlEntities(content);       // 正規化 HTML entities
  content = redactGitHubTokens(content);          // 遮蔽 GitHub tokens
  return content;
}
Code language: JavaScript (javascript)

export function validateBranchName(branchName: string): void {
  if (branchName.startsWith("-")) {
    throw new Error(`Branch names cannot start with a dash.`);  // 防止 option injection
  }
  if (/[\x00-\x1F\x7F ~^:?*[\]\\]/.test(branchName)) {
    throw new Error(`Branch names cannot contain control characters...`);
  }
  const validPattern = /^[a-zA-Z0-9][a-zA-Z0-9/_.-]*$/;
  if (!validPattern.test(branchName)) {
    throw new Error(`Branch names must start with alphanumeric...`);
  }
  // 還有更多檢查：..、.lock、@{、連續 //...
}

// 使用 execFileSync 而非 shell 執行 git 命令
function execGit(args: string[]): void {
  execFileSync("git", args, { stdio: "inherit" });
}
Code language: JavaScript (javascript)

const tagModeTools = [
  "Edit", "MultiEdit", "Glob", "Grep", "LS", "Read", "Write",
  "mcp__github_comment__update_claude_comment",
  "mcp__github_ci__get_ci_status",
  "mcp__github_ci__get_workflow_run_details",
  "mcp__github_ci__download_job_log",
  ...userAllowedMCPTools,
];

// 根據 commit signing 策略加入不同工具
if (!useApiCommitSigning) {
  tagModeTools.push(
    "Bash(git add:*)", "Bash(git commit:*)", "Bash(git push:*)",
    "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git rm:*)",
  );
} else {
  tagModeTools.push(
    "mcp__github_file_ops__commit_files",
    "mcp__github_file_ops__delete_files",
  );
}
Code language: JavaScript (javascript)

export const agentMode: Mode = {
  name: "agent",
  shouldTrigger(context) {
    return !!context.inputs?.prompt;  // 只在有明確 prompt 時觸發
  },
  shouldCreateTrackingComment() {
    return false;  // 不建立 tracking comment
  },
  async prepare({ context, octokit, githubToken }) {
    // 直接寫入使用者的 prompt 到檔案
    const promptContent = context.inputs.prompt ||
      `Repository: ${context.repository.owner}/${context.repository.repo}`;
    await writeFile(`${RUNNER_TEMP}/claude-prompts/claude-prompt.txt`, promptContent);
    // 不需要 fetchGitHubData、不需要建立分支...
  },
};
Code language: JavaScript (javascript)

export async function setupGitHubToken(): Promise<string> {
  // 如果提供了自訂 token，直接使用
  const providedToken = process.env.OVERRIDE_GITHUB_TOKEN;
  if (providedToken) {
    core.setOutput("GITHUB_TOKEN", providedToken);
    return providedToken;
  }

  // 否則走 OIDC 流程
  const oidcToken = await retryWithBackoff(() => getOidcToken());
  const permissions = parseAdditionalPermissions();
  const appToken = await retryWithBackoff(() => exchangeForAppToken(oidcToken, permissions));
  return appToken;
}
Code language: JavaScript (javascript)

const DEFAULT_PERMISSIONS: Record<string, string> = {
  contents: "write",
  pull_requests: "write",
  issues: "write",
};
Code language: JavaScript (javascript)

let promptContent = `You are Claude, an AI assistant...

<formatted_context>
${formattedContext}
</formatted_context>

<pr_or_issue_body>
${formattedBody}
</pr_or_issue_body>

<comments>
${formattedComments || "No comments"}
</comments>

<event_type>${eventType}</event_type>
<trigger_comment>
${sanitizeContent(eventData.commentBody)}
</trigger_comment>
`;
Code language: HTML, XML (xml)

generatePrompt(context, githubData, useCommitSigning): string {
  const defaultPrompt = generateDefaultPrompt(context, githubData, useCommitSigning);
  if (context.githubContext?.inputs?.prompt) {
    return defaultPrompt + `\n\n<custom_instructions>\n${context.githubContext.inputs.prompt}\n</custom_instructions>`;
  }
  return defaultPrompt;
}
Code language: JavaScript (javascript)

// Tag 模式中的工具配置
if (!useApiCommitSigning) {
  tagModeTools.push(
    "Bash(git add:*)", "Bash(git commit:*)", "Bash(git push:*)", ...
  );
}
Code language: JavaScript (javascript)

server.tool("commit_files", "Commit one or more files...", {
  files: z.array(z.string()),
  message: z.string(),
}, async ({ files, message }) => {
  // 1. 取得或建立分支 reference
  const baseSha = await getOrCreateBranchRef(owner, repo, branch, githubToken);
  // 2. 取得 base commit
  // 3. 建立 tree entries（支援 binary 和 text 檔案）
  // 4. 建立新 tree
  // 5. 建立新 commit
  // 6. 更新 reference（含 retry 機制）
  await retryWithBackoff(async () => {
    const updateRefResponse = await fetch(updateRefUrl, { /* ... */ });
    if (updateRefResponse.status === 403) {
      throw new Error(`Permission denied: Unable to push commits to branch...`);
    }
  }, { maxAttempts: 3, initialDelayMs: 1000, backoffFactor: 2 });
});
Code language: JavaScript (javascript)