Publish docs #2
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: Publish docs | |
| on: | |
| push: | |
| branches: [main, master] | |
| tags: ['v*'] | |
| paths: | |
| - 'docs/**' | |
| - 'CHANGELOG.md' | |
| - '.github/workflows/publish-docs.yml' | |
| workflow_dispatch: | |
| inputs: | |
| version: | |
| description: 'Version slug (e.g. master, v4.3.1)' | |
| required: true | |
| default: 'master' | |
| concurrency: | |
| group: publish-docs-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| publish: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 5 | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Resolve version slug | |
| id: ver | |
| run: | | |
| set -euo pipefail | |
| if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then | |
| RAW="${{ inputs.version }}" | |
| elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then | |
| RAW="${GITHUB_REF#refs/tags/}" | |
| else | |
| RAW="master" | |
| fi | |
| # Fold semver-shaped inputs (`v4.3.2`, `v4.3.0-rc1`, `v10.20.30`) to | |
| # their minor branch (`v4.3.x`, `v4.3.x`, `v10.20.x`). `master` and | |
| # anything that doesn't start with `vMAJOR.MINOR.PATCH` is forwarded | |
| # untouched — including already-normalised `v4.3.x`. | |
| if [[ "${RAW}" =~ ^v([0-9]+)\.([0-9]+)\.[0-9] ]]; then | |
| VERSION="v${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.x" | |
| else | |
| VERSION="${RAW}" | |
| fi | |
| echo "version=${VERSION}" >> "$GITHUB_OUTPUT" | |
| echo "Raw input: ${RAW}" | |
| echo "Resolved version: ${VERSION}" | |
| - name: Validate repo layout | |
| run: | | |
| set -euo pipefail | |
| if [ ! -d docs ]; then | |
| echo "::error::Required directory 'docs/' is missing at the repo root." | |
| exit 1 | |
| fi | |
| echo "::notice::Found docs/ tree with $(find docs -type f | wc -l) files." | |
| - name: Build artifact | |
| run: | | |
| set -euo pipefail | |
| INCLUDE=(docs) | |
| if [ -f CHANGELOG.md ]; then | |
| INCLUDE+=(CHANGELOG.md) | |
| else | |
| echo "::warning::CHANGELOG.md not found — uploading docs/ only." | |
| fi | |
| if [ -d assets ]; then | |
| INCLUDE+=(assets) | |
| echo "::notice::Found assets/ tree with $(find assets -type f | wc -l) files." | |
| else | |
| echo "::notice::No assets/ folder — skipping brand assets." | |
| fi | |
| tar -czf docs-artifact.tar.gz "${INCLUDE[@]}" | |
| ls -lh docs-artifact.tar.gz | |
| - name: Upload to docs hub | |
| env: | |
| DOCS_HUB_URL: ${{ secrets.DOCS_HUB_URL }} | |
| DOCS_INGEST_TOKEN: ${{ secrets.DOCS_INGEST_TOKEN }} | |
| PACKAGE_CODE: ${{ vars.PACKAGE_CODE }} | |
| VERSION: ${{ steps.ver.outputs.version }} | |
| run: | | |
| set -euo pipefail | |
| if [ -z "${DOCS_HUB_URL:-}" ] || [ -z "${DOCS_INGEST_TOKEN:-}" ] || [ -z "${PACKAGE_CODE:-}" ]; then | |
| echo "::error::DOCS_HUB_URL, DOCS_INGEST_TOKEN, and PACKAGE_CODE must be set." | |
| exit 1 | |
| fi | |
| URL="${DOCS_HUB_URL%/}/api/v1/packages/${PACKAGE_CODE}/docs" | |
| echo "POST ${URL} (version=${VERSION})" | |
| # `--fail-with-body` is intentionally NOT used: it makes curl exit | |
| # non-zero on 4xx/5xx, which `set -e` would catch BEFORE we get to | |
| # print the response body. We capture the HTTP status via | |
| # `--write-out` and inspect it ourselves. | |
| HTTP_STATUS=$(curl --silent --show-error \ | |
| --output response.json \ | |
| --write-out '%{http_code}' \ | |
| -H "Authorization: Bearer ${DOCS_INGEST_TOKEN}" \ | |
| -H "Accept: application/json" \ | |
| -F "version=${VERSION}" \ | |
| -F "archive=@docs-artifact.tar.gz;type=application/gzip" \ | |
| "${URL}") | |
| echo "HTTP ${HTTP_STATUS}" | |
| echo "::group::Response body" | |
| cat response.json || true | |
| echo | |
| echo "::endgroup::" | |
| if [ "${HTTP_STATUS}" != "201" ]; then | |
| echo "::error::Upload failed with HTTP ${HTTP_STATUS}. See the 'Response body' group above." | |
| exit 1 | |
| fi | |
| - name: Upload artifact for inspection | |
| if: always() | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: docs-artifact-${{ steps.ver.outputs.version }} | |
| path: docs-artifact.tar.gz | |
| retention-days: 7 |