Merge pull request #281 from ai-agent-assembly/v0.0.1/AAASM-4874/docs… #364
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: documentation | |
| on: | |
| push: | |
| branches: | |
| - "master" | |
| paths: | |
| # Doc — CI workflow + deploy scripts | |
| - ".github/workflows/documentation.yaml" | |
| - "scripts/ci/deploy-latest-version-documentation.sh" | |
| - "scripts/ci/deploy-release-version-documentation.sh" | |
| # Doc — MkDocs config | |
| - "mkdocs.yml" | |
| # Doc — Markdown content | |
| - "docs/**/*.md" | |
| # Doc — theme overrides | |
| - "docs/_overrides/**" | |
| # Python source code (mkdocstrings reads docstrings from agent_assembly/) | |
| - "agent_assembly/**/*.py" | |
| # Python project metadata (version is read from pyproject.toml) | |
| - "pyproject.toml" | |
| # Build-only validation on PRs that touch docs — never deploys or pushes. | |
| pull_request: | |
| paths: | |
| - ".github/workflows/documentation.yaml" | |
| - "scripts/ci/deploy-latest-version-documentation.sh" | |
| - "scripts/ci/deploy-release-version-documentation.sh" | |
| - "mkdocs.yml" | |
| - "docs/**/*.md" | |
| - "docs/_overrides/**" | |
| - "agent_assembly/**/*.py" | |
| - "pyproject.toml" | |
| # Cut the frozen, versioned snapshot after a successful release run. The | |
| # referenced name must match release-python.yml's `name:` exactly, or this | |
| # trigger silently never fires. | |
| workflow_run: | |
| workflows: ["Release Python SDK"] | |
| types: [completed] | |
| branches: ["master"] | |
| # Operator-driven, on-demand republish (AAASM-3853). Between coordinated | |
| # releases the default-served channel (pre-release/stable + the root redirect) | |
| # is only recomputed by the workflow_run release path, so doc fixes merged to | |
| # master reach /latest/ immediately but never the default landing page. This | |
| # manual entry point lets an operator re-run a deploy on demand WITHOUT a code | |
| # push or a release cut, driving the EXACT same deploy scripts the automated | |
| # paths use — it adds no new deploy logic, only a new way to invoke it. | |
| workflow_dispatch: | |
| inputs: | |
| target: | |
| description: >- | |
| Which docs path to (re)publish. | |
| "latest" re-deploys the /latest/ channel from master HEAD. | |
| "release-channels" recomputes the pre-release/stable aliases + the | |
| root default from the full set of published versions (requires | |
| release_tag). | |
| type: choice | |
| required: true | |
| default: latest | |
| options: | |
| - latest | |
| - release-channels | |
| release_tag: | |
| description: >- | |
| Release tag to drive the channel recompute, e.g. v0.0.2 or | |
| v0.0.1-beta.2. REQUIRED when target=release-channels; ignored for | |
| target=latest. NOTE: the release deploy re-freezes this tag's snapshot | |
| from the CURRENT master tree, so pass the newest live release tag and | |
| run only when master matches that release's docs content. | |
| type: string | |
| required: false | |
| default: "" | |
| # Default to read-only at the top level so the PR build-only job inherits the | |
| # least privilege. The deploy jobs opt back into the write scopes they need. | |
| permissions: | |
| contents: read | |
| # Allow one concurrent deployment so a fast-follow push doesn't race the | |
| # previous deploy on gh-pages. | |
| concurrency: | |
| group: "pages-mkdocs" | |
| cancel-in-progress: true | |
| jobs: | |
| build_documentation: | |
| name: Build documentation (PR, no deploy) | |
| if: github.event_name == 'pull_request' | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout (full history for mike + git-revision-date plugins) | |
| uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 | |
| with: | |
| fetch-depth: 0 | |
| - name: Install uv | |
| uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 | |
| with: | |
| enable-cache: true | |
| - name: Install Python 3.13 | |
| run: uv python install 3.13 | |
| - name: Install docs dependency group | |
| run: uv sync --group docs | |
| - name: Print tool versions | |
| run: | | |
| uv run mkdocs --version | |
| uv run mike --version | |
| # Build-only: validate the site compiles under --strict. No mike deploy, | |
| # no push to gh-pages — PRs must never mutate the published docs. | |
| - name: Build documentation | |
| env: | |
| MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }} | |
| run: uv run mkdocs build --strict | |
| deploy_latest_documentation: | |
| name: Deploy latest documentation | |
| if: github.event_name == 'push' | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| id-token: write | |
| pages: write | |
| steps: | |
| - name: Checkout (full history for mike + git-revision-date plugins) | |
| uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 | |
| with: | |
| fetch-depth: 0 | |
| - name: Install uv | |
| uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 | |
| with: | |
| enable-cache: true | |
| - name: Install Python 3.13 | |
| run: uv python install 3.13 | |
| - name: Install docs dependency group | |
| run: uv sync --group docs | |
| - name: Print tool versions | |
| run: | | |
| uv run mkdocs --version | |
| uv run mike --version | |
| - name: Build and deploy latest documentation | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }} | |
| run: | | |
| # Activate the uv-managed venv so the deploy script's `mkdocs` and | |
| # `mike` commands resolve without the `uv run` prefix. | |
| source .venv/bin/activate | |
| bash ./scripts/ci/deploy-latest-version-documentation.sh | |
| deploy_release_documentation: | |
| name: Deploy release documentation (channel) | |
| # Gate on the SOURCE workflow_run's triggering event. release-python.yml's | |
| # `publish-release-tag` job is itself gated on `event_name == 'repository_dispatch'` | |
| # (the coordinated-release path), so the `release-tag` artifact only exists when | |
| # the source event was `repository_dispatch`. Without this gate, every push to | |
| # master that runs release-python via `workflow_dispatch` (e.g. dry-run sign-off | |
| # dispatches) triggers this job, which then fails downloading a non-existent | |
| # artifact. The asymmetry mirrors the runbook entry from AAASM-2858 section 2: | |
| # `workflow_dispatch` publishes don't snapshot docs because there's no upstream | |
| # tag to label them with. | |
| if: | | |
| github.event_name == 'workflow_run' && | |
| github.event.workflow_run.conclusion == 'success' && | |
| github.event.workflow_run.event == 'repository_dispatch' | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| id-token: write | |
| pages: write | |
| steps: | |
| - name: Checkout (full history for mike + git-revision-date plugins) | |
| uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 | |
| with: | |
| fetch-depth: 0 | |
| ref: master | |
| # The triggering "Release Python SDK" run published the real release tag | |
| # as a `release-tag` artifact (the workflow_run event only carries the | |
| # PEP-440 pyproject version, which loses the canonical tag form). Pull it | |
| # so the deploy script can label the frozen snapshot and pick the channel. | |
| - name: Download release-tag artifact from the release run | |
| uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 | |
| with: | |
| name: release-tag | |
| path: release-tag-artifact | |
| github-token: ${{ secrets.GITHUB_TOKEN }} | |
| run-id: ${{ github.event.workflow_run.id }} | |
| - name: Resolve release tag into the environment | |
| run: | | |
| set -euo pipefail | |
| tag="$(tr -d '[:space:]' < release-tag-artifact/release-tag.txt)" | |
| if [ -z "${tag}" ]; then | |
| echo "::error::release-tag artifact was empty" | |
| exit 1 | |
| fi | |
| echo "RELEASE_TAG=${tag}" >> "$GITHUB_ENV" | |
| echo "Resolved release tag: ${tag}" | |
| - name: Install uv | |
| uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 | |
| with: | |
| enable-cache: true | |
| - name: Install Python 3.13 | |
| run: uv python install 3.13 | |
| - name: Install docs dependency group | |
| run: uv sync --group docs | |
| - name: Print tool versions | |
| run: | | |
| uv run mkdocs --version | |
| uv run mike --version | |
| - name: Build and deploy release documentation | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }} | |
| RELEASE_TAG: ${{ env.RELEASE_TAG }} | |
| run: | | |
| source .venv/bin/activate | |
| bash ./scripts/ci/deploy-release-version-documentation.sh | |
| - name: Deployment summary | |
| env: | |
| BASE_URL: "https://docs.agent-assembly.com/python-sdk/" | |
| run: | | |
| { | |
| echo "## 📚 Release documentation deployed" | |
| echo "Tag: \`${RELEASE_TAG}\`" | |
| echo "🔗 ${BASE_URL}" | |
| } >> "$GITHUB_STEP_SUMMARY" | |
| manual_republish_documentation: | |
| name: Manual republish documentation (operator) | |
| # Purely additive entry point (AAASM-3853): the existing push / pull_request / | |
| # workflow_run jobs are NOT gated on workflow_dispatch, so this job is the only | |
| # one that runs on a manual dispatch and the automated release/deploy paths are | |
| # left byte-for-byte unchanged. It reuses the existing deploy scripts verbatim. | |
| if: github.event_name == 'workflow_dispatch' | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: write | |
| id-token: write | |
| pages: write | |
| steps: | |
| - name: Validate inputs | |
| env: | |
| TARGET: ${{ inputs.target }} | |
| RELEASE_TAG_INPUT: ${{ inputs.release_tag }} | |
| run: | | |
| set -euo pipefail | |
| if [ "${TARGET}" = "release-channels" ]; then | |
| if [ -z "${RELEASE_TAG_INPUT}" ]; then | |
| echo "::error::target=release-channels requires the 'release_tag' input (e.g. v0.0.2 or v0.0.1-beta.2)." | |
| exit 1 | |
| fi | |
| if ! printf '%s' "${RELEASE_TAG_INPUT}" \ | |
| | grep -Eq '^v[0-9]+\.[0-9]+\.[0-9]+(-.+)?$'; then | |
| echo "::error::release_tag='${RELEASE_TAG_INPUT}' is not a valid release tag (expected vX.Y.Z or vX.Y.Z-<pre>)." | |
| exit 1 | |
| fi | |
| fi | |
| echo "Manual republish: target=${TARGET}, release_tag=${RELEASE_TAG_INPUT:-(n/a)}" | |
| - name: Checkout (full history for mike + git-revision-date plugins) | |
| uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 | |
| with: | |
| fetch-depth: 0 | |
| ref: master | |
| - name: Install uv | |
| uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 | |
| with: | |
| enable-cache: true | |
| - name: Install Python 3.13 | |
| run: uv python install 3.13 | |
| - name: Install docs dependency group | |
| run: uv sync --group docs | |
| - name: Print tool versions | |
| run: | | |
| uv run mkdocs --version | |
| uv run mike --version | |
| - name: Republish documentation | |
| env: | |
| GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }} | |
| TARGET: ${{ inputs.target }} | |
| # Consumed by deploy-release-version-documentation.sh; harmless for the | |
| # latest path, which never reads it. | |
| RELEASE_TAG: ${{ inputs.release_tag }} | |
| run: | | |
| set -euo pipefail | |
| source .venv/bin/activate | |
| if [ "${TARGET}" = "release-channels" ]; then | |
| echo "🔁 Recomputing pre-release/stable channels + root default for ${RELEASE_TAG}" | |
| bash ./scripts/ci/deploy-release-version-documentation.sh | |
| else | |
| echo "🔁 Re-deploying the latest channel from master HEAD" | |
| bash ./scripts/ci/deploy-latest-version-documentation.sh | |
| fi | |
| - name: Republish summary | |
| env: | |
| BASE_URL: "https://docs.agent-assembly.com/python-sdk/" | |
| TARGET: ${{ inputs.target }} | |
| RELEASE_TAG: ${{ inputs.release_tag }} | |
| run: | | |
| { | |
| echo "## 🔁 Manual docs republish" | |
| echo "Target: \`${TARGET}\`" | |
| if [ "${TARGET}" = "release-channels" ]; then | |
| echo "Release tag: \`${RELEASE_TAG}\`" | |
| fi | |
| echo "🔗 ${BASE_URL}" | |
| } >> "$GITHUB_STEP_SUMMARY" |