Skip to content

The open alternative to Salesforce, designed for AI.

ci: add app-docs drift check agent (#22696)

martmull57fb39ba00f8
diff --git a/.github/workflows/ci-app-docs-drift.yaml b/.github/workflows/ci-app-docs-drift.yaml
new file mode 100644
index 00000000000..84130ad6993
--- /dev/null
+++ b/.github/workflows/ci-app-docs-drift.yaml
@@ -0,0 +1,131 @@
+name: CI App Docs Drift
+
+# When a PR changes the app-development surface (twenty-sdk, create-twenty-app,
+# twenty-client-sdk, or the shared manifest types), an agent checks whether the
+# app documentation under packages/twenty-docs/developers/extend/apps is
+# impacted and posts a single sticky comment with its findings.
+
+on:
+ pull_request:
+
+permissions:
+ contents: read
+ id-token: write
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ changed-files-check:
+ uses: ./.github/workflows/changed-files.yaml
+ with:
+ files: |
+ packages/twenty-sdk/**
+ packages/create-twenty-app/**
+ packages/twenty-client-sdk/**
+ packages/twenty-shared/src/application/**
+ packages/twenty-shared/src/types/**
+
+ docs-drift-check:
+ needs: changed-files-check
+ # Secrets are unavailable on fork PRs; skip there and on bot PRs.
+ if: >-
+ needs.changed-files-check.outputs.any_changed == 'true' &&
+ github.event.pull_request.head.repo.full_name == github.repository &&
+ github.event.pull_request.user.type != 'Bot'
+ timeout-minutes: 30
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write
+ id-token: write
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+ with:
+ fetch-depth: 0
+
+ - name: Run docs drift agent
+ uses: anthropics/claude-code-action@ac7e24bf2938964b8ab203e417a2773802392ddd # v1.0.146
+ with:
+ claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+ claude_args: '--max-turns 60 --allowedTools "Bash(git diff *),Bash(git log *),Bash(git show *),Bash(grep *),Bash(cat *),Bash(ls *),Bash(find *),Bash(head *),Bash(tail *),Bash(gh pr comment *)"'
+ prompt: |
+ You are the app-documentation drift checker for the twenty repository.
+
+ A pull request changed files in the app-development platform. Your job is to
+ decide whether the documentation under
+ `packages/twenty-docs/developers/extend/apps/` (English pages only — ignore
+ `packages/twenty-docs/l/`) is impacted, and report your findings as ONE pull
+ request comment.
+
+ ## Step 1 — Understand the change
+
+ The PR branch is checked out with full history; the base branch is
+ `origin/${{ github.base_ref }}`. Inspect what the PR changes however you
+ see fit. Only these kinds of changes are documentation-relevant:
+
+ - CLI commands, subcommands, flags, defaults, or help text
+ (`packages/twenty-sdk/src/cli/commands/**`)
+ - `define*` function signatures, config properties, validation rules,
+ or their warnings (`packages/twenty-sdk/src/sdk/define/**`)
+ - Enum / string-union values and manifest types
+ (`packages/twenty-shared/src/application/**`, `packages/twenty-shared/src/types/**`)
+ - Exports added/removed/renamed in the `exports` maps of `twenty-sdk` or
+ `twenty-client-sdk` package.json, or in their public entry points
+ - Front-component runtime hooks and host API
+ (`packages/twenty-sdk/src/sdk/front-component/**`)
+ - The scaffold template (`packages/create-twenty-app/src/constants/template/**`)
+ and scaffolder flags/prompts (`packages/create-twenty-app/src/cli.ts`,
+ `create-app.command.ts`)
+ - Environment variables injected into logic functions or front components
+ - Error codes surfaced to app developers
+
+ Internal refactors, tests, and implementation-only changes are NOT relevant —
+ if the changes contain only those, say so and stop.
+
+ ## Step 2 — Map to documentation
+
+ Use this mapping to know which pages to check (read the actual pages):
+
+ | Source area | Docs pages |
+ |---|---|
+ | CLI commands (`src/cli/commands`) | `operations/cli.mdx`, `getting-started/quick-start.mdx`, `operations/sync-and-recovery.mdx`, `getting-started/local-server.mdx`, `getting-started/scaffolding.mdx` |
+ | `defineObject`/`defineField`/relations/indexes | `data/*.mdx` |
+ | `defineApplication`/roles/install hooks/variables | `config/*.mdx` |
+ | Logic functions, triggers, connections, agents/skills | `logic/*.mdx` |
+ | Views, navigation, page layouts, front components, command menu | `layout/*.mdx` |
+ | Publish/install/deploy, versioning, engines | `operations/publishing.mdx`, `operations/sync-and-recovery.mdx` |
+ | Testing APIs (`twenty-sdk/cli` operations) | `operations/testing.mdx` |
+ | Scaffold template | `getting-started/project-structure.mdx`, `getting-started/quick-start.mdx`, `operations/testing.mdx`, `operations/publishing.mdx` |
+ | client SDK (`core`/`metadata`/`rest`/`generate`) | `logic/logic-functions.mdx`, `layout/front-components.mdx`, `operations/cli.mdx` |
+ | Enum value sets (FieldType, ViewType, availabilityType, NavigationMenuItemType, ...) | the page documenting that value set (search for the enum name) |
+
+ Also check whether the PR already updates the impacted docs pages — if it
+ does, verify the update matches the code change.
+
+ ## Step 3 — Report
+
+ Post exactly one comment on PR #${{ github.event.pull_request.number }} with:
+ `gh pr comment ${{ github.event.pull_request.number }} --edit-last --create-if-none --body ...`
+ (this updates the previous drift-check comment in place on subsequent runs).
+ Start the comment body with the marker `<!-- app-docs-drift-check -->`.
+
+ Comment format:
+ - Title line: `### App docs drift check`
+ - If no documentation impact: one sentence saying so and why.
+ - If impacted: a table with columns **Change** (what changed in the code),
+ **Docs page** (repo-relative path), **Status** (`✅ already updated in this PR`
+ / `⚠️ needs update`), and **Suggested fix** (one concrete sentence, e.g. the
+ exact value to add to a table).
+ - Be terse. No preamble, no sign-off. Only report genuine drift — if unsure
+ whether something is user-facing, say it's uncertain rather than asserting.
+
+ Environment: GH_TOKEN is available for `gh`. The PR branch is checked out.
+ settings: |
+ {
+ "env": {
+ "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
+ }
+ }