ci: Fix documentation artefacts automatically

.github/workflows/api-fix-docs-artefacts.yml

@@ -0,0 +1,70 @@
+name: API Documentation Artefacts Auto-Update
+
+on:
+  pull_request:
+    paths:
+      - api/**
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: api
+
+env:
+  DOTENV_OVERRIDE_FILE: .env-ci
+
+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
+        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: ${{ github.event.pull_request.head.ref }}
+          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 generate-docs-private
+
+      - 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; }

.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
 

.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

api/Makefile

@@ -193,6 +193,15 @@ 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
+	$(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
+
 .PHONY: add-known-sdk-version
 add-known-sdk-version:
 	uv run python scripts/add-known-sdk-version.py $(opts)

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,
         )

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(

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

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.",
 )

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`

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:
 

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).                                                  |

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",

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

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