{"schemaVersion":1,"title":"Maintain documentation automatically","url":"https://appgram.github.io/docsy/versions/current/fr/guides/tutorials/documentation-maintenance","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/fr/guides/tutorials/documentation-maintenance","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/fr/guides/tutorials/documentation-maintenance.json","version":"current","locale":"fr","markdown":"# Maintain documentation automatically\n\nTurn API and code changes into validated draft PRs with updated articles, corrected examples, and migration notes.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy can turn a committed API or code change into a draft documentation pull request. It compares source revisions, identifies likely affected articles and examples, asks a coding agent to update them, and validates the resulting site before opening the PR.\n\n## Enable the workflow\n\nNew Docsy projects include `.github/workflows/docsy-maintenance.yml` and the maintenance CLI. The workflow is disabled in YAML until you enable it:\n\n```yaml\nmaintenance:\n  enabled: true\n  watch:\n    - sources/**\n    - src/**\n  docs:\n    - content/**/*.md\n    - README.md\n  breakingChangesFile: content/maintenance/breaking-changes.md\n```\n\n`watch` selects source paths whose committed changes should trigger a review. `docs` limits the Markdown files the agent can edit. Both accept relative paths with `*`, `**`, and `?` wildcards. Use `ignore` to exclude generated or unrelated input paths.\n\nThe source code and documentation must be available in the checked-out repository. For an application monorepo, include the application paths under `watch`. For a separate docs repository, commit the relevant OpenAPI or SDK snapshots into `sources/`.\n\nIn GitHub repository settings:\n\n1. Add an Actions secret named `OPENAI_API_KEY` for the Codex GitHub Action.\n2. Under **Actions → General → Workflow permissions**, enable **Allow GitHub Actions to create and approve pull requests**. The workflow creates drafts; it never approves or merges them.\n3. Push a source change to the default branch, or run **Maintain documentation** manually with a comparison base ref.\n\nIf GitHub disables the pull-request setting for a repository, an organization owner must first allow it under the organization's **Settings → Actions → General** policy.\n\nThe workflow skips source comparisons that find no watched changes. If the API secret is missing, it reports the setup step instead of calling the agent.\n\n## What happens after a source change\n\n### Detect documentation impact\n\nThe planner compares the Git revisions and records changed source paths. For local OpenAPI JSON or YAML, it compares operations, inherited parameters, local schema references, request and response contracts, authentication, and server URLs. Swagger 2 inputs are supported too.\n\nRemoved endpoints and newly required parameters are marked as breaking changes. Contract changes that need interpretation are marked for review. Descriptions and reference metadata are kept separate from those findings.\n\nThe planner searches Markdown for endpoint paths, operation identifiers, changed code symbols, and source references. It flags examples that still call removed endpoints or may omit a newly required parameter. The agent inspects the source and relevant articles beyond that initial list.\n\n### Update articles and explain migrations\n\nThe agent receives the source diff, impact report, and project instructions. It updates guides and examples from source evidence and records unresolved questions for the reviewer.\n\nWhen changes break existing usage, it can add migration notes at `breakingChangesFile` and register that page in the YAML article list and navigation. Generated API and SDK reference content is rebuilt from the configured ingestion inputs.\n\nThe allowed changes are Markdown under `docs`, the breaking-changes article, and the YAML fields for article registration, navigation, and OpenAPI section mappings. Branding, theme, access policy, runtime source, dependencies, and workflows stay outside that edit scope.\n\n### Validate and open a draft PR\n\nA fresh GitHub job applies the proposed patch, checks its file scope and protected YAML settings, and runs:\n\n```bash\nnpm run validate\nnpm run build\n```\n\nOnly a successful update reaches the publishing job. That job opens a draft on a `codex/docs-maintenance-...` branch with a description of the source changes, documentation edits, breaking-change findings, corrected examples, validation, and unresolved questions. Repeated runs for the same source commit reuse an existing PR.\n\nReview the actual behavior, examples, and rendered pages before merging. Validation checks configuration, types, and the site build; it does not prove that every example works against a running API.\n\n## Execute selected examples and inspect the preview\n\nAdd trusted, local assertion commands to YAML when specific examples must actually run:\n\n```yaml\nmaintenance:\n  enabled: true\n  exampleChecks:\n    - name: API examples against a local fixture server\n      command: [node, tests/documented-requests.mjs]\n      timeoutMs: 30000\n```\n\nCommands are explicit argument arrays, not shell strings. They run after scope/configuration validation and before the production build, with a timeout; a failed check stops the update. Use offline assertions or local mock servers. Do not put production credentials in these commands. The agent cannot edit this configuration, executable test files, or dependency scripts in a maintenance update. Running a configured check is executing trusted project code, so review it like any CI test.\n\nThe PR body lists exactly which checks ran. With no checks configured, it explicitly says runtime correctness is unproven. Even a passing test suite covers only the assertions you wrote, not every language/client or example.\n\nFor open static sites, CI attaches **docsy-static-preview**, a seven-day Actions artifact containing the validated rendered `dist/` site. The PR body links to its workflow run. It is a download for review, not a public preview deployment; serve it at the configured base path locally. Protected/server builds do **not** upload their bundle as a static preview. Review those behind your actual trusted authentication integration using Node/Bun.\n\nLocal runs write `.docsy/maintenance/preview.json`, the validated patch, and `pr-body.md`. Run `npm run preview` in that checkout to inspect the result. Draft creation still requires `--pr` locally, and no workflow auto-approves or merges changes.\n\n## Inspect impact locally\n\nRun a report without invoking a model or opening a PR:\n\n```bash\nnpm run maintain -- plan --base HEAD~1\n```\n\nThe planner writes `.docsy/maintenance/report.json` and `prompt.md`. These local artifacts are ignored by Git. You can use the report and prompt with another coding agent as well.\n\n`--base` is required. Use `--head <ref>` to inspect a particular committed revision. Comparisons use committed files, so commit the source change before running a maintenance task.\n\n## Run the agent locally\n\nWith an authenticated Codex CLI and a clean checkout:\n\n```bash\nnpm run maintain -- run --base HEAD~1\n```\n\nThe agent updates the working tree, then Docsy checks the scope and validates the production build. The changes remain available as a local diff for review. Add `--pr` when you want Docsy to create a branch, commit, push, and open a draft using your authenticated GitHub CLI:\n\n```bash\nnpm run maintain -- run --base HEAD~1 --pr --target-branch main\n```\n\nLeave `maintenance.model` unset to use the agent's configured default, or set it to a model available to your account. The local CLI uses your existing Codex sign-in; GitHub Actions uses the repository's API secret.\n\n## Source and review boundaries\n\nAuthorship and per-page edit metadata are protected. The agent may register or correct an article's ordinary route/title/source metadata, but cannot assign authors, contributors or reviewers, change publication/update/review dates, add agent provenance, or redirect the edit button. These are maintainer-supplied records, not claims that an automatic build may invent. See [Authors, reviews and edit links](../authors-and-edit-links).\n\nThis workflow reacts to Git changes in the default branch. Remote OpenAPI and SDK URLs are still valid ingestion sources, but the maintenance planner does not poll them for upstream changes. Commit snapshots when you need reproducible version comparisons; a source-sync job can update those snapshots and trigger the same loop.\n\nSDK and application changes are reviewed from their Git diff and documentation references. Structural breaking-change classification currently applies to OpenAPI and Swagger; the agent interprets SDK and application semantics from the available code.\n\nThe workflow uses the [official Codex GitHub Action](https://learn.chatgpt.com/docs/github-action) with repository read permissions during generation. Validation and PR publishing run in separate jobs; the publisher receives the GitHub write permissions needed for the draft.\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/documentation-maintenance.md"}