Skip to content

ci: fix documentation artefacts automatically after merge #8024

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
emyller wants to merge 5 commits into
base: main
Choose a base branch
from
Open

ci: fix documentation artefacts automatically after merge #8024

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a6fa48a
auto-fix documentation artefacts on merge to main
emyller Jul 16, 2026
180332d
DROPME: trigger docs artefact fix on pull requests
emyller Jul 15, 2026
f38778a
exercise all documentation artefact generators
emyller Jul 15, 2026
e61a1a6
Revert "DROPME: trigger docs artefact fix on pull requests"
emyller Jul 16, 2026
102acf0
improve dev interface
emyller Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .github/workflows/api-fix-docs-artefacts.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
name: API Documentation Artefacts Auto-Update

permissions:
contents: read # For actions/checkout
id-token: write # For CodeArtifact OIDC
Comment on lines +3 to +5

@coderabbitai coderabbitai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🔵 Trivial | 💤 Low value

Restrict id-token: write permission to the job level.

Applying id-token: write at the workflow level grants broad access to all jobs in the workflow, which violates the principle of least privilege. While there is only one job here, it is best practice to move the permissions block to the specific job that requires it.

🛡️ Proposed refactor

Remove the global permissions block:

-permissions:
-  contents: read # For actions/checkout
-  id-token: write # For CodeArtifact OIDC

And add it to the fix-docs-artefacts job:

 jobs:
   fix-docs-artefacts:
     runs-on: depot-ubuntu-latest
     name: Fix Documentation Artefacts
+    permissions:
+      contents: read
+      id-token: write
🧰 Tools
🪛 zizmor (1.26.1)

[error] 5-5: overly broad permissions (excessive-permissions): id-token: write is overly broad at the workflow level

(excessive-permissions)

Source: Linters/SAST tools


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

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; }
Comment on lines +70 to +71

@khvn26 khvn26 Jul 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this violates SOC2.

@emyller emyller Jul 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean having app pushing to main?

@khvn26 khvn26 Jul 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean having anything pushing to main bypassing the PR approval mechanism.

Comment on lines +61 to +71

@coderabbitai coderabbitai Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Improve commit step reliability and prevent redundant CI runs.

  • Prevent Redundant Triggers: Because this workflow uses a GitHub App token to push changes, the push will re-trigger this and any other on: push workflows. Appending [skip ci] to the commit message prevents these redundant executions, saving CI resources in direct alignment with the PR objectives.
  • Working Directory: The default working directory for the job is api/. While git add --all operates on the entire working tree regardless of the current directory (in Git 2.0+), it is clearer and safer to explicitly set the working directory to the repository root for repository-wide Git commands to avoid any pathspec ambiguity with artefacts generated in ../docs.
♻️ Proposed refactor 
       - name: Commit and push fixes
+        working-directory: ${{ github.workspace }}
         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 commit --message 'chore: Update documentation artefacts [skip ci]'
           git push || { git pull --rebase && git push; }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- 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; }
- name: Commit and push fixes
working-directory: ${{ github.workspace }}
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 [skip ci]'
git push || { git pull --rebase && git push; }
🧰 Tools
🪛 zizmor (1.26.1)

[info] 75-75: code injection via template expansion (template-injection): may expand into attacker-controllable code

(template-injection)

[info] 76-76: code injection via template expansion (template-injection): may expand into attacker-controllable code

(template-injection)

5 changes: 0 additions & 5 deletions .github/workflows/api-pull-request.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 0 additions & 16 deletions .github/workflows/api-tests-with-private-packages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 10 additions & 0 deletions api/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ codeartifact-login:
install-packages:
uv sync --frozen $(opts)

.PHONY: install-private-packages
install-private-packages: opts=--extra private
install-private-packages: install-packages

.PHONY: install
install: install-packages

Expand Down Expand Up @@ -193,6 +197,12 @@ 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: install-private-packages 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)
1 change: 1 addition & 0 deletions api/experimentation/tasks.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
Expand Down
2 changes: 1 addition & 1 deletion api/experimentation/views.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion api/features/views.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion api/segment_membership/metrics.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.",
)
Loading