v1.12.0 #4
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: Docs | |
| on: | |
| release: | |
| # A stable release publishes docs. A prerelease still builds the docs and | |
| # checks the deploy credentials, but does not publish. "released" also | |
| # catches promotion of an existing prerelease to stable. | |
| types: [published, released] | |
| workflow_call: | |
| inputs: | |
| build_docs: | |
| description: "Build and verify the documentation" | |
| required: false | |
| type: boolean | |
| default: true | |
| check_credentials: | |
| description: "Check the docs deploy AWS credentials" | |
| required: false | |
| type: boolean | |
| default: false | |
| version: | |
| description: "Documentation version (e.g. v0.1.0)" | |
| required: false | |
| type: string | |
| upload_artifact: | |
| description: "Upload the generated docs as a workflow artifact" | |
| required: false | |
| type: boolean | |
| default: true | |
| artifact_name: | |
| description: "Name of the uploaded docs artifact" | |
| required: false | |
| type: string | |
| default: livekit-cpp-docs | |
| artifact_retention_days: | |
| description: "Artifact retention in days" | |
| required: false | |
| type: number | |
| default: 7 | |
| secrets: | |
| DOCS_DEPLOY_AWS_ACCESS_KEY: | |
| required: false | |
| DOCS_DEPLOY_AWS_API_SECRET: | |
| required: false | |
| outputs: | |
| project_number: | |
| description: "Doxygen PROJECT_NUMBER used for the build" | |
| value: ${{ jobs.build.outputs.project_number }} | |
| artifact_name: | |
| description: "Uploaded docs artifact name" | |
| value: ${{ jobs.build.outputs.artifact_name }} | |
| permissions: | |
| contents: read | |
| actions: read | |
| jobs: | |
| build: | |
| name: Generate and verify docs | |
| if: github.event_name == 'release' || inputs.build_docs | |
| runs-on: ubuntu-latest | |
| outputs: | |
| project_number: ${{ steps.build_docs.outputs.project_number }} | |
| artifact_name: ${{ steps.artifact_meta.outputs.name }} | |
| steps: | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| # Required so git describe in generate-docs.sh can resolve a version. | |
| fetch-depth: 0 | |
| - name: Install Doxygen | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y doxygen graphviz | |
| - name: Generate docs | |
| id: build_docs | |
| shell: bash | |
| env: | |
| INPUT_VERSION: ${{ github.event_name == 'release' && github.event.release.tag_name || inputs.version || '' }} | |
| run: | | |
| set -euo pipefail | |
| args=() | |
| if [[ -n "$INPUT_VERSION" ]]; then | |
| args+=(--version "$INPUT_VERSION") | |
| elif [[ "${{ github.ref_type }}" == "tag" ]]; then | |
| args+=(--version "${{ github.ref_name }}") | |
| fi | |
| ./scripts/generate-docs.sh "${args[@]}" | |
| - name: Print docs version | |
| shell: bash | |
| run: | | |
| set -euo pipefail | |
| PROJECT_NUMBER="${{ steps.build_docs.outputs.project_number }}" | |
| if [[ -z "$PROJECT_NUMBER" ]]; then | |
| echo "ERROR: build_docs step did not emit a project_number output." | |
| exit 1 | |
| fi | |
| echo "Docs version: ${PROJECT_NUMBER}" | |
| { | |
| echo "Docs version: \`${PROJECT_NUMBER}\`" | |
| echo "" | |
| echo "> Note: On a non-tag/release run, the version resolves to:" | |
| echo " \`<closest tag>-<commits since tag>-<commit sha>\`" | |
| } >>"$GITHUB_STEP_SUMMARY" | |
| - name: Verify docs were generated | |
| shell: bash | |
| run: | | |
| set -euo pipefail | |
| if [[ ! -f docs/doxygen/html/index.html ]]; then | |
| echo "ERROR: Expected docs at docs/doxygen/html/index.html but file not found." | |
| exit 1 | |
| fi | |
| - name: Resolve artifact metadata | |
| id: artifact_meta | |
| if: github.event_name == 'release' || inputs.upload_artifact | |
| shell: bash | |
| env: | |
| INPUT_NAME: ${{ inputs.artifact_name || format('livekit-cpp-docs-{0}', github.run_id) }} | |
| INPUT_RETENTION: ${{ inputs.artifact_retention_days || 7 }} | |
| run: | | |
| set -euo pipefail | |
| if [[ -z "$INPUT_NAME" ]]; then | |
| echo "ERROR: Artifact name resolved to empty." | |
| exit 1 | |
| fi | |
| echo "name=${INPUT_NAME}" >>"$GITHUB_OUTPUT" | |
| echo "retention=${INPUT_RETENTION}" >>"$GITHUB_OUTPUT" | |
| - name: Upload docs artifact | |
| if: steps.artifact_meta.outputs.name != '' | |
| uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 | |
| with: | |
| name: ${{ steps.artifact_meta.outputs.name }} | |
| path: docs/doxygen/html/ | |
| retention-days: ${{ steps.artifact_meta.outputs.retention }} | |
| if-no-files-found: error | |
| - name: Re-download artifact | |
| if: steps.artifact_meta.outputs.name != '' | |
| uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 | |
| with: | |
| name: ${{ steps.artifact_meta.outputs.name }} | |
| path: html | |
| - name: Verify downloaded artifact | |
| if: steps.artifact_meta.outputs.name != '' | |
| shell: bash | |
| run: | | |
| set -euo pipefail | |
| TOTAL=$(find html -type f | wc -l | tr -d ' ') | |
| echo "Total files: ${TOTAL}" | |
| if [[ ! -f html/index.html ]]; then | |
| echo "ERROR: html/index.html is missing; the publish artifact layout regressed." | |
| exit 1 | |
| fi | |
| credentials: | |
| name: Check AWS credentials | |
| # CI enables this only for trusted main pushes. Release events always | |
| # check credentials before publishing. PR jobs never receive deploy keys. | |
| if: github.event_name == 'release' || inputs.check_credentials | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Verify docs deploy credentials | |
| env: | |
| AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} | |
| AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} | |
| AWS_DEFAULT_REGION: "us-east-1" | |
| run: | | |
| set -euo pipefail | |
| if [[ -z "${AWS_ACCESS_KEY_ID}" || -z "${AWS_SECRET_ACCESS_KEY}" ]]; then | |
| echo "Docs deploy AWS credentials are not available to this workflow." | |
| exit 1 | |
| fi | |
| aws sts get-caller-identity --query Arn --output text | |
| publish: | |
| name: Publish (S3 + CloudFront) | |
| needs: [build, credentials] | |
| if: github.event_name == 'release' && github.event.release.prerelease == false | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Download docs artifact | |
| uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 | |
| with: | |
| name: ${{ needs.build.outputs.artifact_name }} | |
| path: html | |
| - name: S3 Upload | |
| env: | |
| AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} | |
| AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} | |
| AWS_DEFAULT_REGION: "us-east-1" | |
| run: | | |
| set -euo pipefail | |
| if [[ ! -f html/index.html ]]; then | |
| echo "Expected docs at html/index.html but file not found." | |
| exit 1 | |
| fi | |
| VERSIONED_PREFIX="s3://livekit-docs/client-sdk-cpp/${{ needs.build.outputs.project_number }}" | |
| LATEST_PREFIX="s3://livekit-docs/client-sdk-cpp" | |
| aws s3 cp html/ "$VERSIONED_PREFIX" --recursive | |
| aws s3 cp html/ "$LATEST_PREFIX" --recursive | |
| - name: Invalidate CloudFront cache | |
| env: | |
| AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOY_AWS_ACCESS_KEY }} | |
| AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOY_AWS_API_SECRET }} | |
| AWS_DEFAULT_REGION: "us-east-1" | |
| run: | | |
| aws cloudfront create-invalidation \ | |
| --distribution-id EJJ40KLJ3TRY9 \ | |
| --paths "/client-sdk-cpp/*" |