From a6fa48ac7df492b32c56bebe23e6457dd3adcf17 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Thu, 16 Jul 2026 11:39:33 -0300 Subject: [PATCH 1/8] auto-fix documentation artefacts on merge to main Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HWahXvKyob4DTBgmGzV1gm --- .github/workflows/api-fix-docs-artefacts.yml | 78 +++++++++++++++++++ .github/workflows/api-pull-request.yml | 5 -- .../api-tests-with-private-packages.yml | 16 ---- 3 files changed, 78 insertions(+), 21 deletions(-) create mode 100644 .github/workflows/api-fix-docs-artefacts.yml diff --git a/.github/workflows/api-fix-docs-artefacts.yml b/.github/workflows/api-fix-docs-artefacts.yml new file mode 100644 index 000000000000..b763e5c45cf0 --- /dev/null +++ b/.github/workflows/api-fix-docs-artefacts.yml @@ -0,0 +1,78 @@ +name: API Documentation Artefacts Auto-Update + +permissions: + contents: read # For actions/checkout + id-token: write # For CodeArtifact OIDC + +on: + push: + paths: + - api/** + branches: + - main + +concurrency: + group: ${{ github.workflow }} + cancel-in-progress: false + +defaults: + run: + working-directory: api + +env: + DOTENV_OVERRIDE_FILE: .env-ci + +jobs: + fix-docs-artefacts: + runs-on: depot-ubuntu-latest + name: Fix Documentation Artefacts + + steps: + - name: Generate GitHub App token with push access + id: app-token + uses: actions/create-github-app-token@v1 + with: + app-id: ${{ vars.FLAGSMITH_ENGINEERING_GH_APP_ID }} + private-key: ${{ secrets.FLAGSMITH_ENGINEERING_GH_APP_PRIVATE_KEY }} + + - name: Cloning repo + uses: actions/checkout@v7 + with: + ref: main + token: ${{ steps.app-token.outputs.token }} + + - uses: ./.github/actions/install-uv + with: + working-directory: api + + - name: Install SAML Dependencies + run: sudo apt-get install -y xmlsec1 + + - name: Generate public documentation artefacts + run: | + make install-packages opts='--extra dev' + make generate-docs + + - name: Authenticate with CodeArtifact + uses: ./.github/actions/codeartifact-login + + - name: Generate private documentation artefacts + run: | + make install-packages opts='--extra dev --extra private' + make generate-full-openapi + make generate-mcp-openapi + uv run python manage.py generate_mcp_tool_catalogue \ + --exclude ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md \ + > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md + + - name: Commit and push fixes + run: | + git add --all + if git diff --cached --quiet; then + echo "Documentation artefacts are up to date." + exit 0 + fi + git config user.name '${{ steps.app-token.outputs.app-slug }}[bot]' + git config user.email '${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com' + git commit --message 'chore: Update documentation artefacts' + git push || { git pull --rebase && git push; } diff --git a/.github/workflows/api-pull-request.yml b/.github/workflows/api-pull-request.yml index d6dc9740f05b..21f446c9bb04 100644 --- a/.github/workflows/api-pull-request.yml +++ b/.github/workflows/api-pull-request.yml @@ -68,11 +68,6 @@ jobs: action: remove linters: mypy - - name: Check autogenerated documentation - uses: nickcharlton/diff-check@v1.0.0 - with: - command: make -C api generate-docs - - name: Run Tests run: make test diff --git a/.github/workflows/api-tests-with-private-packages.yml b/.github/workflows/api-tests-with-private-packages.yml index 6111de9584ee..5b851e06db00 100644 --- a/.github/workflows/api-tests-with-private-packages.yml +++ b/.github/workflows/api-tests-with-private-packages.yml @@ -60,22 +60,6 @@ jobs: make integrate-private-tests rm -rf ${HOME}/.git-credentials - - name: Check MCP enterprise tool catalogue is up to date - env: - DOTENV_OVERRIDE_FILE: .env-ci - run: | - uv run python manage.py generate_mcp_tool_catalogue \ - --exclude ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md \ - > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md - git diff --exit-code ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md - - - name: Check full OpenAPI schema is up to date - env: - DOTENV_OVERRIDE_FILE: .env-ci - run: | - make generate-full-openapi - git diff --exit-code ../openapi.yaml - - name: Run Tests env: DOTENV_OVERRIDE_FILE: .env-ci From 180332d5251c9def4c33edb6d6271c27e32ac786 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Wed, 15 Jul 2026 20:18:46 -0300 Subject: [PATCH 2/8] DROPME: trigger docs artefact fix on pull requests Co-Authored-By: Claude Fable 5 --- .github/workflows/api-fix-docs-artefacts.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/api-fix-docs-artefacts.yml b/.github/workflows/api-fix-docs-artefacts.yml index b763e5c45cf0..ebfd2c3d8370 100644 --- a/.github/workflows/api-fix-docs-artefacts.yml +++ b/.github/workflows/api-fix-docs-artefacts.yml @@ -10,6 +10,11 @@ on: - api/** branches: - main + # DROPME: temporary trigger to validate the fix behaviour in a PR. + pull_request: + paths: + - api/** + types: [opened, synchronize, reopened, ready_for_review] concurrency: group: ${{ github.workflow }} @@ -38,7 +43,8 @@ jobs: - name: Cloning repo uses: actions/checkout@v7 with: - ref: main + # DROPME: push to the PR branch while validating; restore `main`. + ref: ${{ github.event.pull_request.head.ref || 'main' }} token: ${{ steps.app-token.outputs.token }} - uses: ./.github/actions/install-uv From f38778a8ce8c3c8724255e6b119ebf56c6a87946 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Wed, 15 Jul 2026 20:19:23 -0300 Subject: [PATCH 3/8] exercise all documentation artefact generators Co-Authored-By: Claude Fable 5 --- api/experimentation/tasks.py | 1 + api/experimentation/views.py | 2 +- api/features/views.py | 2 +- api/segment_membership/metrics.py | 2 +- 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/api/experimentation/tasks.py b/api/experimentation/tasks.py index d035330a8e74..1446db7f31b2 100644 --- a/api/experimentation/tasks.py +++ b/api/experimentation/tasks.py @@ -101,6 +101,7 @@ def compute_experiment_exposures(experiment_id: int) -> None: "exposures.compute_failed", exc_info=exc, experiment__id=experiment.id, + feature__id=experiment.feature_id, environment__id=experiment.environment_id, organisation__id=experiment.environment.project.organisation_id, ) diff --git a/api/experimentation/views.py b/api/experimentation/views.py index 2a4af7fdf4a6..897b3d0546e0 100644 --- a/api/experimentation/views.py +++ b/api/experimentation/views.py @@ -210,7 +210,7 @@ def _get_user(request: Request) -> FFAdminUser: decorator=extend_schema( tags=["mcp"], operation_id="update_experiment", - description="(Beta) Updates an experiment's name or hypothesis.", + description="(Beta) Updates an experiment's name or its hypothesis.", ), ) class ExperimentViewSet( diff --git a/api/features/views.py b/api/features/views.py index e4d25e761a59..462053151125 100644 --- a/api/features/views.py +++ b/api/features/views.py @@ -996,7 +996,7 @@ class SDKFeatureStates(GenericAPIView): # type: ignore[type-arg] ) def get(self, request, identifier=None, *args, **kwargs): # type: ignore[no-untyped-def] """ - Retrieve the flags for an environment. + Retrieve the feature flags for an environment. --- *Note*: when providing the `feature` query argument, this endpoint will diff --git a/api/segment_membership/metrics.py b/api/segment_membership/metrics.py index 7ced432a4485..c18561aea9a7 100644 --- a/api/segment_membership/metrics.py +++ b/api/segment_membership/metrics.py @@ -25,5 +25,5 @@ flagsmith_segment_membership_read_duration_seconds = prometheus_client.Histogram( "flagsmith_segment_membership_read_duration_seconds", - "Duration of a single segment membership page read.", + "Duration of one segment membership page read.", ) From e61a1a6236642f268675de0a0711e7d4ecb85063 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Thu, 16 Jul 2026 13:12:47 -0300 Subject: [PATCH 4/8] Revert "DROPME: trigger docs artefact fix on pull requests" This reverts commit 180332d5251c9def4c33edb6d6271c27e32ac786. --- .github/workflows/api-fix-docs-artefacts.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.github/workflows/api-fix-docs-artefacts.yml b/.github/workflows/api-fix-docs-artefacts.yml index ebfd2c3d8370..b763e5c45cf0 100644 --- a/.github/workflows/api-fix-docs-artefacts.yml +++ b/.github/workflows/api-fix-docs-artefacts.yml @@ -10,11 +10,6 @@ on: - api/** branches: - main - # DROPME: temporary trigger to validate the fix behaviour in a PR. - pull_request: - paths: - - api/** - types: [opened, synchronize, reopened, ready_for_review] concurrency: group: ${{ github.workflow }} @@ -43,8 +38,7 @@ jobs: - name: Cloning repo uses: actions/checkout@v7 with: - # DROPME: push to the PR branch while validating; restore `main`. - ref: ${{ github.event.pull_request.head.ref || 'main' }} + ref: main token: ${{ steps.app-token.outputs.token }} - uses: ./.github/actions/install-uv From a35b11c8efe9d7bad2528643460f753953d3bf32 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Fri, 17 Jul 2026 14:59:24 -0300 Subject: [PATCH 5/8] improve dev interface --- api/Makefile | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/api/Makefile b/api/Makefile index 0f40fa25692f..3950e5efa21c 100644 --- a/api/Makefile +++ b/api/Makefile @@ -193,6 +193,14 @@ generate-docs: generate-flagsmith-sdk-openapi generate-mcp-openapi uv run flagsmith docgen events > ../docs/docs/deployment-self-hosting/observability/_events-catalogue.md uv run python manage.py generate_mcp_tool_catalogue > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md +.PHONY: generate-docs-private +generate-docs-private: + $(MAKE) install-packages opts="--extra dev --extra private" + $(MAKE) generate-full-openapi generate-mcp-openapi + uv run python manage.py generate_mcp_tool_catalogue \ + --exclude ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md \ + > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md + .PHONY: add-known-sdk-version add-known-sdk-version: uv run python scripts/add-known-sdk-version.py $(opts) From 0d3bb9d886c962021e0c1d7dacc60267fa53bf34 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Fri, 17 Jul 2026 15:00:28 -0300 Subject: [PATCH 6/8] no golden passport to main --- .github/workflows/api-fix-docs-artefacts.yml | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/.github/workflows/api-fix-docs-artefacts.yml b/.github/workflows/api-fix-docs-artefacts.yml index b763e5c45cf0..65ffc30208f4 100644 --- a/.github/workflows/api-fix-docs-artefacts.yml +++ b/.github/workflows/api-fix-docs-artefacts.yml @@ -5,15 +5,14 @@ permissions: id-token: write # For CodeArtifact OIDC on: - push: + pull_request: paths: - api/** - branches: - - main + types: [opened, synchronize, reopened, ready_for_review] concurrency: - group: ${{ github.workflow }} - cancel-in-progress: false + group: ${{ github.workflow }}-${{ github.event.pull_request.number }} + cancel-in-progress: true defaults: run: @@ -38,7 +37,7 @@ jobs: - name: Cloning repo uses: actions/checkout@v7 with: - ref: main + ref: ${{ github.event.pull_request.head.ref }} token: ${{ steps.app-token.outputs.token }} - uses: ./.github/actions/install-uv @@ -57,13 +56,7 @@ jobs: uses: ./.github/actions/codeartifact-login - name: Generate private documentation artefacts - run: | - make install-packages opts='--extra dev --extra private' - make generate-full-openapi - make generate-mcp-openapi - uv run python manage.py generate_mcp_tool_catalogue \ - --exclude ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md \ - > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md + run: make generate-docs-private - name: Commit and push fixes run: | From 59e37ca3bb3fd38c3dcbdfe5a3fb93a55ae93198 Mon Sep 17 00:00:00 2001 From: Evandro Myller Date: Fri, 17 Jul 2026 15:13:48 -0300 Subject: [PATCH 7/8] notice the strictness now --- .github/workflows/api-fix-docs-artefacts.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/api-fix-docs-artefacts.yml b/.github/workflows/api-fix-docs-artefacts.yml index 65ffc30208f4..e80fcd6bd893 100644 --- a/.github/workflows/api-fix-docs-artefacts.yml +++ b/.github/workflows/api-fix-docs-artefacts.yml @@ -1,9 +1,5 @@ name: API Documentation Artefacts Auto-Update -permissions: - contents: read # For actions/checkout - id-token: write # For CodeArtifact OIDC - on: pull_request: paths: @@ -25,6 +21,9 @@ jobs: fix-docs-artefacts: runs-on: depot-ubuntu-latest name: Fix Documentation Artefacts + permissions: + contents: read # For actions/checkout + id-token: write # For CodeArtifact OIDC steps: - name: Generate GitHub App token with push access From 79294f22c0a6530fe43736001be13796f9104e0c Mon Sep 17 00:00:00 2001 From: "flagsmith-engineering[bot]" Date: Fri, 17 Jul 2026 18:45:13 +0000 Subject: [PATCH 8/8] chore: Update documentation artefacts --- .../observability/_events-catalogue.md | 3 ++- .../observability/_metrics-catalogue.md | 2 +- docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md | 2 +- mcp/src/flagsmith_mcp/openapi.json | 2 +- openapi.yaml | 6 +++--- sdk/openapi.yaml | 2 +- 6 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md index 06de7fe32398..1085abcb90df 100644 --- a/docs/docs/deployment-self-hosting/observability/_events-catalogue.md +++ b/docs/docs/deployment-self-hosting/observability/_events-catalogue.md @@ -89,12 +89,13 @@ Attributes: - `environment.id` - `exc_info` - `experiment.id` + - `feature.id` - `organisation.id` ### `experimentation.results.compute_failed` Logged at `error` from: - - `api/experimentation/tasks.py:135` + - `api/experimentation/tasks.py:136` Attributes: - `environment.id` diff --git a/docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md b/docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md index 9dce2c26d313..649284cdac6b 100644 --- a/docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md +++ b/docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md @@ -90,7 +90,7 @@ Labels: Histogram. -Duration of a single segment membership page read. +Duration of one segment membership page read. Labels: diff --git a/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md b/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md index f88cd61ac287..1378fc490d8d 100644 --- a/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md +++ b/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md @@ -40,7 +40,7 @@ | `publish_environment_feature_version` | Publishes a feature version to make it live in the environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | | `update_environment_feature_state` | Updates a feature state in an environment, including enabled status and value. Applies to environments without v2 feature versioning (use_v2_feature_versioning: false). | | `update_environment_feature_version_state` | Updates an existing feature state for a specific version in an environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | -| `update_experiment` | (Beta) Updates an experiment's name or hypothesis. | +| `update_experiment` | (Beta) Updates an experiment's name or its hypothesis. | | `update_feature` | Updates feature flag properties such as name and description. | | `update_feature_multivariate_option` | Updates an existing multivariate option. | | `update_feature_state` | Updates a feature state, including its enabled status and value. Also updates a segment override's value for environments without v2 feature versioning (use_v2_feature_versioning: false). | diff --git a/mcp/src/flagsmith_mcp/openapi.json b/mcp/src/flagsmith_mcp/openapi.json index 008774b33d4d..be7e662ebd92 100644 --- a/mcp/src/flagsmith_mcp/openapi.json +++ b/mcp/src/flagsmith_mcp/openapi.json @@ -551,7 +551,7 @@ }, "put": { "operationId": "update_experiment", - "description": "(Beta) Updates an experiment's name or hypothesis.", + "description": "(Beta) Updates an experiment's name or its hypothesis.", "parameters": [ { "name": "environment_api_key", diff --git a/openapi.yaml b/openapi.yaml index bcbf094e222d..fb578ada57aa 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3118,7 +3118,7 @@ paths: - mcp put: operationId: update_experiment - description: (Beta) Updates an experiment's name or hypothesis. + description: (Beta) Updates an experiment's name or its hypothesis. parameters: - name: environment_api_key in: path @@ -8425,7 +8425,7 @@ paths: get: operationId: sdk_v1_flags description: |- - Retrieve the flags for an environment. + Retrieve the feature flags for an environment. --- *Note*: when providing the `feature` query argument, this endpoint will @@ -8513,7 +8513,7 @@ paths: get: operationId: sdk_v1_flags_2 description: |- - Retrieve the flags for an environment. + Retrieve the feature flags for an environment. --- *Note*: when providing the `feature` query argument, this endpoint will diff --git a/sdk/openapi.yaml b/sdk/openapi.yaml index 2422d7dc3133..0c67801d259e 100644 --- a/sdk/openapi.yaml +++ b/sdk/openapi.yaml @@ -33,7 +33,7 @@ paths: get: operationId: sdk_v1_flags description: |- - Retrieve the flags for an environment. + Retrieve the feature flags for an environment. --- *Note*: when providing the `feature` query argument, this endpoint will