ci: fix docs build

[moabu]

Prepare

• Read PR guidelines
• Read license information

---

Description

Target issue

closes #issue-number-here

Implementation Details

---

Test and Document the changes

• Static code analysis has been run locally and issues have been fixed
• Relevant unit and integration tests have been added/updated
• Relevant documentation has been updated if any (i.e. user guides, installation and configuration guides, technical design docs etc)

Please check the below before submitting your PR. The PR will not be merged if there are no commits that start with docs: to indicate documentation changes or if the below checklist is not selected.

• I confirm that there is no impact on the docs due to the code changes in this PR.

Closes #13233,

Summary by CodeRabbit

• Documentation

  • Removed extraneous subtitle from Agama project config page for slimmer front-matter

• New Features

  • Added configurable flags to enable conditional tracking pixel and REO script for versioned docs
  • Ensure template overrides are sourced from main before deploying versioned docs

• Chores

  • Simplified release workflow: apply flags prior to deployment, consolidate version-related commit messaging and copy final docs artifacts together

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Updates docs build workflow to pull template overrides from main and enable Scarf/REO flags for versioned docs; mkdocs.yml adds toggles for those trackers; docs template conditionalizes Scarf/REO inclusion; removes a subtitle from one docs page front matter.

Changes

Cohort / File(s)	Summary
Build workflow .github/workflows/build-docs.yml	Adds steps to fetch template overrides from origin/main, copy mkdocs.yml and CHANGELOG.md, enable enable_scarf_pixel/enable_reo_flag for versioned docs, and standardizes finalization commits to update version references.
Docs template docs/overrides/main.html	Replaces earlier release-automation comment block with conditional rendering controlled by config.extra.enable_scarf_pixel and config.extra.enable_reo_flag, gating Scarf pixel and REO script inclusion.
Site config mkdocs.yml	Adds two new extras: enable_scarf_pixel: false and enable_reo_flag: false.
Doc metadata docs/janssen-server/config-guide/auth-server-config/agama-project-configuration.md	Removes a subtitle line from the page YAML front matter (metadata-only change).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(ci): add Reo script for tracking #13118: Edits docs/overrides/main.html and CI/docs workflow to add/enable REO/Scarf tracking flags and include the REO script.

Suggested reviewers

• ossdhaval
• iromli

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description follows the template structure but is incomplete: target issue references a placeholder 'closes #issue-number-here' instead of a real issue, implementation details section is empty, testing/documentation checklists are unchecked, and the docs impact confirmation checkbox is unchecked despite documentation files being modified.	Replace placeholder issue reference with actual issue #13233, document implementation approach in details section, check appropriate testing/documentation checkboxes, and update the docs impact confirmation based on actual changes made.
Linked Issues check	❓ Inconclusive	Linked issue #13233 is an auto-created placeholder with no functional requirements or acceptance criteria provided; it merely reflects that the PR did not reference an open issue, making objective validation impossible.	Clarify the actual functional requirements being addressed by this PR. Either provide detailed objectives in issue #13233 or reference the original open issue that this PR resolves.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'ci: fix docs build' is directly related to the changeset, which modifies CI workflow files (.github/workflows/build-docs.yml) and documentation configuration (mkdocs.yml, docs/overrides/main.html) to fix docs build automation.
Out of Scope Changes check	✅ Passed	All changes appear directly related to fixing the docs build process: workflow updates, template overrides, and mkdocs configuration changes align with the PR's stated objective of fixing docs build automation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ci-fix-reo

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mo-auto]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[mo-auto]

Error: Hi @moabu, You did not reference an open issue in your PR. I attempted to create an issue for you.
Please update that issues' title and body and make sure I correctly referenced it in the above PRs body.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/build-docs.yml:
- Around line 159-163: Add a short diagnostic check immediately after the two
sed commands that toggles enable_scarf_pixel and enable_reo_flag in mkdocs.yml:
run a grep (or similar) for both keys in mkdocs.yml and echo the matching lines
(or a clear "not found" message) so the workflow logs whether the substitutions
occurred; reference the existing sed commands that modify mkdocs.yml and place
the verification before the subsequent mike deploy step, leaving the current
event condition unchanged (confirming that head pushes to main remain excluded
if intended).

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/build-docs.yml:
- Around line 159-165: Update the step named "Enable Scarf and Reo tracking for
versioned docs" so its if-condition matches the deploy guards: keep allowing
manual runs (github.event_name == 'workflow_dispatch') but for release events
require github.event.action == 'published', !github.event.release.draft, and
that the release tag is versioned or nightly
(startsWith(github.event.release.tag_name, 'v') || github.event.release.tag_name
== 'nightly'); this prevents sed edits to mkdocs.yml (the two sed commands that
toggle enable_scarf_pixel and enable_reo_flag) from running for releases that
will not be deployed.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/build-docs.yml:
- Around line 159-163: The workflow step named "Use latest template overrides
from main" can fail because docs/overrides/ may not exist in older tags; modify
that step's run block to ensure the target directory exists before the git show
redirect by running mkdir -p docs/overrides/ (or equivalent) prior to executing
git show origin/main:docs/overrides/main.html > docs/overrides/main.html so the
redirection cannot fail due to a missing directory.

---

Duplicate comments:
In @.github/workflows/build-docs.yml:
- Around line 164-165: The "Enable Reo and Scarf tracking for versioned docs"
step's if condition is too broad and should match the same guards used by the
"mike deploy new version" logic; update the step's if to require
github.event_name == 'workflow_dispatch' || (github.event_name == 'release' &&
github.event.action == 'published' && !github.event.release.draft &&
(startsWith(github.event.release.name, 'v') || github.event.release.name ==
'nightly')) so the Reo/Scarf edits only run for the same release cases that
trigger "mike deploy new version".

[coderabbitai]

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In @.github/workflows/build-docs.yml:
- Around line 159-162: The workflow step "Use latest template overrides from
main" writes to docs/overrides/main.html but doesn't ensure the docs/overrides
directory exists, so the redirect will fail for older tags; fix it by adding a
preceding command in that step to create the directory (ensure docs/overrides
exists before running git show origin/main:docs/overrides/main.html >
docs/overrides/main.html) so the redirect can write the file successfully.