diff --git a/.github/workflows/ci-app-docs-drift.yaml b/.github/workflows/ci-app-docs-drift.yaml new file mode 100644 index 0000000000..84130ad699 --- /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 ``. + + 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 }}" + } + }