export type GitHubIntegrationConfig = {
  enabled: boolean;
  prComments: {
    enabled: boolean;
    mode: "summary" | "detailed";
    updateExistingComment: boolean;
  };
  checks: {
    enabled: boolean;
    failOnStalePublicDocs: boolean;
    failOnReviewRequired: boolean;
  };
  annotations: {
    enabled: boolean;
    maxAnnotations: number;
  };
  artifacts: {
    uploadReports: boolean;
    uploadReviewArtifacts: boolean;
  };
  updates: {
    enabled: boolean;
    strategy: "none" | "commitToPrBranch" | "separateBranch" | "separatePullRequest";
    applySafeOnly: boolean;
    branchPrefix: string;
  };
  privacy: {
    exposeSourcePaths: boolean;
    exposeEvidenceExcerpts: boolean;
    redactInternalArtifacts: boolean;
  };
};

{
  "github": {
    "enabled": true,
    "prComments": {
      "enabled": true,
      "mode": "summary",
      "updateExistingComment": true
    },
    "checks": {
      "enabled": true,
      "failOnStalePublicDocs": false,
      "failOnReviewRequired": false
    },
    "annotations": {
      "enabled": true,
      "maxAnnotations": 20
    },
    "updates": {
      "enabled": false,
      "strategy": "none",
      "applySafeOnly": true,
      "branchPrefix": "docforge/docs-update"
    }
  }
}

name: DocForge Docs

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - run: corepack enable
      - run: pnpm install --frozen-lockfile

      - run: pnpm docforge verify --strict
      - run: pnpm docforge update --since origin/${{ github.base_ref }} --dry-run --format json > docforge-update-report.json

      - uses: actions/upload-artifact@v4
        with:
          name: docforge-update-report
          path: docforge-update-report.json

docforge github comment --report docforge-update-report.json

git diff origin/main...HEAD

packages/github-integration/
  src/
    context.ts
    config.ts
    actions-env.ts
    reports/
      pr-comment.ts
      annotations.ts
      checks.ts
      artifacts.ts
    commands/
      github-comment.ts
      github-check.ts
      github-update-branch.ts
    update-branch.ts
    permissions.ts
    privacy.ts
    idempotency.ts
    __tests__/
      pr-comment.test.ts
      annotations.test.ts
      privacy.test.ts
      idempotency.test.ts

export type GitHubContext = {
  repository: {
    owner: string;
    name: string;
    fullName: string;
  };
  pullRequest?: {
    number: number;
    headRef: string;
    headSha: string;
    baseRef: string;
    baseSha?: string;
    isFork: boolean;
  };
  actor: string;
  eventName: string;
  runId?: string;
  serverUrl: string;
  apiUrl: string;
};

export function readGitHubActionsContext(env: NodeJS.ProcessEnv): GitHubContext | undefined {
  const repository = env.GITHUB_REPOSITORY;
  const eventName = env.GITHUB_EVENT_NAME;

  if (!repository || !eventName) return undefined;

  const [owner, name] = repository.split("/");

  return {
    repository: { owner, name, fullName: repository },
    actor: env.GITHUB_ACTOR ?? "",
    eventName,
    runId: env.GITHUB_RUN_ID,
    serverUrl: env.GITHUB_SERVER_URL ?? "https://github.com",
    apiUrl: env.GITHUB_API_URL ?? "https://api.github.com",
  };
}

export async function readGitHubEventPayload(env: NodeJS.ProcessEnv): Promise<unknown | undefined> {
  const path = env.GITHUB_EVENT_PATH;
  if (!path) return undefined;

  return JSON.parse(await fs.readFile(path, "utf8"));
}

export function parsePullRequestContext(payload: any): GitHubContext["pullRequest"] | undefined {
  const pr = payload.pull_request;
  if (!pr) return undefined;

  return {
    number: pr.number,
    headRef: pr.head.ref,
    headSha: pr.head.sha,
    baseRef: pr.base.ref,
    baseSha: pr.base.sha,
    isFork: pr.head.repo?.full_name !== pr.base.repo?.full_name,
  };
}

export function githubAutomationAllowed(ctx: GitHubContext, config: GitHubIntegrationConfig): GitHubAutomationPermissions {
  if (ctx.pullRequest?.isFork) {
    return {
      canComment: false,
      canPush: false,
      canCreatePr: false,
      canUploadSanitizedArtifacts: true,
    };
  }

  return {
    canComment: config.prComments.enabled,
    canPush: config.updates.enabled,
    canCreatePr: config.updates.strategy === "separatePullRequest",
    canUploadSanitizedArtifacts: true,
  };
}

<!-- docforge:pr-comment -->

## DocForge documentation report

Status: ⚠️ Review required

### Docs impact

| Source change | Affected docs | Action |
|---|---|---|
| `openapi/public.yaml` | `/api-reference/users/create-user` | Safe generated update |
| `src/commands/build.ts` | `/guides/build-docs` | Review required |

### Suggested next step

```bash
docforge update --since origin/main --apply

export async function upsertPrComment(
  client: GitHubClient,
  ctx: GitHubContext,
  body: string
): Promise<void> {
  const marker = "<!-- docforge:pr-comment -->";
  const comments = await client.listIssueComments(ctx.repository, ctx.pullRequest!.number);
  const existing = comments.find((comment) =>
    comment.body.includes(marker) && comment.user.type === "Bot"
  );

  if (existing) {
    await client.updateComment(existing.id, body);
  } else {
    await client.createIssueComment(ctx.repository, ctx.pullRequest!.number, body);
  }
}

export function renderPrComment(summary: PrSummaryModel, config: GitHubIntegrationConfig): string {
  return [
    "<!-- docforge:pr-comment -->",
    "",
    `## DocForge documentation report`,
    "",
    `Status: ${renderStatus(summary.status)}`,
    "",
    renderChangedDocsTable(summary),
    renderReviewRequired(summary),
    renderSuggestedCommands(summary),
    renderFooter(summary),
  ].join("\n");
}

export function sanitizePrSummary(
  summary: PrSummaryModel,
  policy: GitHubIntegrationConfig["privacy"]
): PrSummaryModel {
  // remove internal/private evidence, shorten paths, redact sensitive names
  return summary;
}

export type GitHubAnnotation = {
  path: string;
  startLine: number;
  endLine?: number;
  annotationLevel: "notice" | "warning" | "failure";
  message: string;
  title?: string;
  rawDetails?: string;
};

export function diagnosticToAnnotation(diagnostic: Diagnostic): GitHubAnnotation | undefined {
  if (!diagnostic.location?.path || !diagnostic.location?.line) {
    return undefined;
  }

  return {
    path: diagnostic.location.path,
    startLine: diagnostic.location.line,
    annotationLevel: severityToAnnotationLevel(diagnostic.severity),
    title: diagnostic.code,
    message: diagnostic.message,
  };
}

{
  "github": {
    "annotations": {
      "enabled": true,
      "maxAnnotations": 20
    }
  }
}

Only showing first 20 annotations. See full report artifact.

DocForge found 2 affected documentation pages.

- 1 safe generated update is available.
- 1 manual page requires review.

.docforge/reports/ci-docs-report.json
.docforge/reports/update-dry-run-report.json
.docforge/reports/provenance-report.json
.docforge/reviews/**

docforge workflow export-reports --out .docforge/reports

- uses: actions/upload-artifact@v4
  with:
    name: docforge-reports
    path: .docforge/reports

docforge/docs-update/pr-123

export type UpdateBranchPlan = {
  branchName: string;
  baseRef: string;
  commitMessage: string;
  changedFiles: string[];
  prTitle?: string;
  prBody?: string;
};

docforge/docs-update/pr-<number>
docforge/docs-update/<short-sha>

docs: update generated documentation for PR #123

<!-- docforge:update-pr -->

{
  "github": {
    "updates": {
      "allowedPaths": [
        "docs/**",
        "openapi/generated-docs/**",
        "docforge.lock.json"
      ]
    }
  }
}

docforge.lock.json

<!-- docforge:update-pr -->

# DocForge generated docs update

This PR updates generated documentation affected by source changes.

## Source changes

- OpenAPI operation changed: `POST /users`
- Config field default changed: `search.enabled`

## Updated docs

- `/api-reference/users/create-user`
- `/reference/configuration`

## Validation

- MDX compile: passed
- Link check: passed
- Provenance: updated

export type InlineReviewComment = {
  path: string;
  line: number;
  body: string;
  severity: "warning" | "error";
};

## DocForge documentation report

Status: ✅ No docs updates needed

No public documentation impact was detected for this PR.

## DocForge documentation report

Status: ⚠️ Generated docs update available

DocForge found 2 generated API reference pages that can be updated safely.

Run locally:

```bash
docforge update --since origin/main --apply --only api

## DocForge documentation report

Status: ❌ Failed

Docs verification failed.

Errors:
- Broken link in `/quickstart`
- Unsupported claim in generated block `build-output`

See workflow artifacts for the full report.

- run: pnpm docforge verify --strict

- run: pnpm docforge update --since origin/${{ github.base_ref }} --dry-run --format json > report.json
- run: pnpm docforge github comment --report report.json

- run: pnpm docforge update --since origin/${{ github.base_ref }} --apply --generated-only
- run: pnpm docforge verify --strict
- run: pnpm docforge github update-pr

{
  "github": {
    "forks": {
      "allowComments": false,
      "allowUpdates": false,
      "allowCustomPlugins": false
    }
  }
}

docforge github summary --report report.json >> "$GITHUB_STEP_SUMMARY"

export type GitHubClientConfig = {
  token?: string;
  apiUrl: string;
};

warning github.token.missing
Cannot post PR comment because GitHub token is unavailable.

export type GitHubClient = {
  listIssueComments(repo: RepoRef, issueNumber: number): Promise<GitHubComment[]>;
  createIssueComment(repo: RepoRef, issueNumber: number, body: string): Promise<void>;
  updateComment(commentId: number, body: string): Promise<void>;
  createCheckRun?(input: CreateCheckRunInput): Promise<void>;
  createOrUpdateBranch?(plan: UpdateBranchPlan): Promise<void>;
  createPullRequest?(input: CreatePullRequestInput): Promise<void>;
};

warning github.comment.failed
DocForge completed docs analysis but failed to update PR comment.

type Diagnostic = {
  code: string;
  severity: "info" | "warning" | "error";
  message: string;
  location?: {
    path?: string;
    line?: number;
    column?: number;
  };
};

export function severityToAnnotationLevel(severity: DiagnosticSeverity): "notice" | "warning" | "failure" {
  switch (severity) {
    case "error": return "failure";
    case "warning": return "warning";
    default: return "notice";
  }
}

export type ChangedLineMap = Map<string, Set<number>>;

export function isDiagnosticOnChangedLine(
  diagnostic: Diagnostic,
  changedLines: ChangedLineMap
): boolean {
  const path = diagnostic.location?.path;
  const line = diagnostic.location?.line;

  if (!path || !line) return false;

  return changedLines.get(path)?.has(line) ?? false;
}

<details>
<summary>Show diagnostics</summary>

...
</details>

export function escapeMarkdownTableCell(value: string): string {
  return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
}

export function suppressMentions(text: string): string {
  return text.replace(/@/g, "@\u200B");
}

docforge github comment --report .docforge/reports/ci-docs-report.json
docforge github summary --report .docforge/reports/ci-docs-report.json
docforge github annotations --report .docforge/reports/ci-docs-report.json
docforge github update-pr --report .docforge/reports/update-dry-run-report.json
docforge github doctor

GitHub integration doctor

Context:
  repository: acme/docforge
  event: pull_request
  PR: #123
  fork: false

Permissions:
  comments: available
  checks: available
  push updates: disabled by config

Git:
  base ref: origin/main available
  head ref: HEAD

Reports:
  .docforge/reports/ci-docs-report.json found

Not running inside GitHub Actions.

export function validateChangedFilesAllowed(
  changedFiles: string[],
  allowedGlobs: string[]
): Diagnostic[] {
  return changedFiles.flatMap((file) => {
    if (matchesAny(file, allowedGlobs)) return [];

    return [{
      code: "github.updateBranch.unexpectedFileChange",
      severity: "error",
      category: "github",
      message: `Update branch modified disallowed file: ${file}.`,
    }];
  });
}

DocForge Bot <docforge-bot@example.com>

docs: update generated docs

Generated by DocForge.
Source PR: #123

<!-- docforge:update-pr source-pr=123 -->

# Generated documentation update for PR #123
...

export function isDocForgeBotBranch(branch: string, prefix: string): boolean {
  return branch.startsWith(prefix);
}

if: ${{ !startsWith(github.head_ref, 'docforge/docs-update') }}

Generated docs update PR: #456

This PR updates generated API/config reference affected by the current changes.

{
  "github": {
    "updates": {
      "cleanupOnSourcePrClose": true
    }
  }
}

export function githubSourceUrl(ctx: GitHubContext, path: string, ref: string, line?: number): string {
  const base = `${ctx.serverUrl}/${ctx.repository.fullName}/blob/${ref}/${encodeURI(path)}`;
  return line ? `${base}#L${line}` : base;
}

| Source | Docs | Why |
|---|---|---|
| `openapi/public.yaml` | `/api-reference/users/create-user` | OpenAPI operation changed |

| Source | Docs | Why |
|---|---|---|
| OpenAPI spec | `/api-reference/users/create-user` | API operation changed |

DocForge / Verify
DocForge / Docs Drift
DocForge / Build

strategy:
  matrix:
    docs-project: [public-docs, internal-docs]

steps:
  - run: pnpm docforge verify --project ${{ matrix.docs-project }}

DocForge found 143 affected generated API pages.

Showing top 10. Full report is available as workflow artifact.

git checkout $BRANCH

await execFile("git", ["checkout", branchName], { cwd });

export type TrustedAutomationMode = "trusted" | "untrustedFork" | "restricted";

it("renders idempotent PR comment marker", () => {
  const body = renderPrComment(summary, config);

  expect(body).toContain("<!-- docforge:pr-comment -->");
});

it("redacts evidence excerpts in public mode", () => {
  const safe = sanitizePrSummary(summaryWithEvidence, publicPolicy);

  expect(JSON.stringify(safe)).not.toContain("internalImplementationDetail");
});

it("limits annotations", () => {
  const annotations = diagnosticsToAnnotations(manyDiagnostics, { maxAnnotations: 10 });

  expect(annotations).toHaveLength(10);
});

it("disables updates for fork PRs", () => {
  const permissions = githubAutomationAllowed(forkContext, config);

  expect(permissions.canPush).toBe(false);
});

it("updates existing PR comment", async () => {
  const client = new FakeGitHubClient({
    comments: [{ id: 1, body: "<!-- docforge:pr-comment --> old", user: { type: "Bot" } }],
  });

  await upsertPrComment(client, ctx, "new body");

  expect(client.updatedComments[0].id).toBe(1);
});

docforge verify --strict
docforge build

docforge update --since origin/main --dry-run --format json