documentation.yaml

name: Documentation Updates

# Any change in triggers needs to be reflected in the concurrency group.
on:
  pull_request: {}
  push:
    branches:
      - main
      - ft/main/**
  merge_group:
    types: [checks_requested]

permissions: read-all

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.after || github.event.merge_group && github.run_id }}
  cancel-in-progress: ${{ !github.event.merge_group }}

jobs:
  check_changes:
    name: Deduce required tests from code changes
    runs-on: ubuntu-22.04
    outputs:
      docs-tree: ${{ steps.docs-tree.outputs.src }}
    steps:
      - name: Checkout code
        if: ${{ !github.event.pull_request }}
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          persist-credentials: false
      - name: Check code changes
        uses: dorny/paths-filter@0bc4621a3135347011ad047f9ecf449bf72ce2bd # v3.0.0
        id: docs-tree
        with:
          # For `push` events, compare against the `ref` base branch
          # For `pull_request` events, this is ignored and will compare against the pull request base branch
          base: ${{ github.ref }}
          filters: |
            src:
              - .github/workflows/documentation.yaml
              - 'Documentation/**'
              - 'bugtool/cmd/**'
              - 'cilium/cmd/**'
              - 'cilium-health/cmd/**'
              - 'daemon/cmd/**'
              - 'hubble-relay/cmd/**'
              - 'install/kubernetes/**'
              - 'operator/cmd/**'
              - README.rst

  # Runs only if code under Documentation or */cmd/ is changed as the docs
  # should be unaffected otherwise.
  build-html:
    needs: check_changes
    if: ${{ needs.check_changes.outputs.docs-tree == 'true' }}
    name: Validate & Build HTML
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          persist-credentials: false
      - name: Build HTML
        uses: docker://quay.io/cilium/docs-builder:6f53f8ad89e205c78afcce5e106061a4e45484de@sha256:db358ec7730851a641cc8ee99fde367072e2bd0b13d35b5856eee6b2d0eaa7d5
        with:
          entrypoint: ./Documentation/check-build.sh
          args: html

  check-generated-documentation:
    name: Check generated documentation
    if: ${{ github.event_name != 'merge_group' }}
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
        with:
          persist-credentials: false
      - name: Install Go
        uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
        with:
          # renovate: datasource=golang-version depName=go
          go-version: 1.21.6

      - name: Set clang directory
        id: set_clang_dir
        run: echo "clang_dir=$HOME/.clang" >> $GITHUB_OUTPUT

      - name: Cache LLVM and Clang
        id: cache-llvm
        uses: actions/cache@13aacd865c20de90d75de3b17ebe84f7a17d57d2 # v4.0.0
        with:
          path: ${{ steps.set_clang_dir.outputs.clang_dir }}
          key: llvm-10.0

      - name: Install LLVM and Clang prerequisites
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends libtinfo5

      - name: Install LLVM and Clang
        uses: KyleMayes/install-llvm-action@be40c5af3a4adc3e4a03199995ab73aa37536712 # v1.9.0
        with:
          version: "10.0"
          directory: ${{ steps.set_clang_dir.outputs.clang_dir }}
          cached: ${{ steps.cache-llvm.outputs.cache-hit }}

      # Building Cilium as precondition to generate documentation artifacts.
      - name: Build Cilium
        run: |
          make -C Documentation cilium-build

      - name: Check generated documentation
        run: |
          SKIP_BUILD=true make -C Documentation check