docs-gen.yaml

name: Docs

env:
    SLACK_DEBUG_TESTING: false      # when set to "true", send notifications to #slack-integration-testing.  Otherwise, post to #edge-team-bots
    MIN_SCANNED_VERSION: 'v1.14.0'  # ⚠️ you should also change trivy-analysis-scheduled.yaml ⚠️
on:
  push:
    branches:
    - 'main'
    - 'v1.17.x'
    - 'v1.16.x'
    - 'v1.15.x'
    - 'v1.14.x'
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches:
    - 'main'
  workflow_run:
    workflows: ["security-scan-scheduled"]
    types:
      - completed
jobs:
  prepare_env:
    name: Prepare Environment
    runs-on: ubuntu-22.04
    timeout-minutes: 5
    outputs:
      should-build-docs: ${{ steps.build-strategy.outputs.build_value }}
      version: ${{ steps.version.outputs.value }}}
    steps:
      - id: is-community-pr
        name: Detect Community PR
        if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != 'solo-io/gloo' }}
        shell: bash
        run: |
          echo "Pull Request is from a fork. Setting is_community_pr to true"
          echo "value=true" >> $GITHUB_OUTPUT
      - id: is-draft-pr
        name: Process draft Pull Requests
        if: ${{ github.event.pull_request.draft }}
        run: echo "value=true" >> $GITHUB_OUTPUT
      - id: checkout-code
        uses: actions/checkout@v4
        with:
          # We require gathering the branch and tag history since we rely on a `git diff`
          # which compares the state of two branches
          fetch-depth: 0
      - id: process-skip-directives
        uses: ./.github/workflows/composite-actions/process-skip-directives
        with:
          # GitHub baseRef is only availabe on PR:
          # https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
          # On other events (merge to LTS branches), this will be empty, ensuring that
          # the process-skip-directives action returns 'false' for all values (ie run docs builds)
          base-ref: ${{ github.base_ref }}
      - id: build-strategy
        name: Determine Docs Build Strategy
        run: |
          should_build=true

          is_draft_pr=${{ steps.is-draft-pr.outputs.value }}
          if [[ ! -z $is_draft_pr && $is_draft_pr = true ]] ; then
            should_build=false
          fi

          is_community_pr=${{ steps.is-community-pr.outputs.value }}
          if [[ ! -z $is_community_pr && $is_community_pr = true ]] ; then
            should_build=false
          fi

          skip_docs_build=${{ steps.process-skip-directives.outputs.skip-docs-build }}
          if [[ ! -z $skip_docs_build && $skip_docs_build = true ]] ; then
            should_build=false
          fi

          echo "Build strategy: Should build? $should_build"
          echo "build_value=$should_build" >> $GITHUB_OUTPUT
      - id: version
        shell: bash
        run: |
          version=$(git describe --tags --abbrev=0 | cut -c 2-)
          if [[ ${{ github.event_name == 'pull_request' }} = true ]]; then
            version=$(git describe --tags --abbrev=0 | cut -c 2-)-PR${{github.event.number}}
          fi
          echo "value=$version" >> $GITHUB_OUTPUT
  build:
    name: Generate versioned docs site
    needs: prepare_env
    if: needs.prepare_env.outputs.should-build-docs == 'true'
    env:
      VERSION: ${{ needs.prepare_env.outputs.version }}
    runs-on: ubuntu-22.04
    timeout-minutes: 60
    steps:
    - name: Check out code into the Go module directory
      uses: actions/checkout@v4
      with:
        ref: main
    - name: Override main checkout if deploying PR test
      if: ${{ github.event_name == 'pull_request' }}
      uses: actions/checkout@v4
    - uses: ./.github/workflows/composite-actions/prep-go-runner
    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v3
      with:
        hugo-version: '0.81.0'
    - name: Generate versioned docs site
      run: make -C docs build-site
      env:
        GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
        USE_PR_SHA_AS_MAIN: ${{ github.event_name == 'pull_request' }}
        PULL_REQUEST_SHA: ${{ github.event.pull_request.head.sha }}
    - name: Deploy to Firebase (live docs)
      # Do not publish docs if this workflow was triggered by a pull request
      # Only deploy if this was triggered by a push to main, or a successful trivy workflow_run
      if: ${{ github.event_name != 'pull_request' }}
      uses: FirebaseExtended/action-hosting-deploy@main
      with:
        repoToken: ${{ secrets.GITHUB_TOKEN }}
        firebaseServiceAccount: ${{ secrets.GC_FIREBASE_GHA_SA_JSON_KEY }}
        projectId: ${{ secrets.GC_FIREBASE_GHA_PROJECT_ID }}
        channelId: live
        entryPoint: ./docs/ci
    - name: Deploy to Firebase (preview)
      # Generate live preview of docs for PRs to main
      if: ${{ github.event_name == 'pull_request' }}
      uses: FirebaseExtended/action-hosting-deploy@main
      with:
        repoToken: ${{ secrets.GITHUB_TOKEN }}
        firebaseServiceAccount: ${{ secrets.GC_FIREBASE_GHA_SA_JSON_KEY }}
        projectId: ${{ secrets.GC_FIREBASE_GHA_PROJECT_ID }}
        entryPoint: ./docs/ci
    - name: Notify On Failure
      id: notify-on-failure
      if: ${{ github.event_name != 'pull_request' && failure() }}
      run : |
        curl -X POST\
             -H 'Content-type: application/json'\
             --data '{"text":"Gloo Edge has <https://github.com/solo-io/gloo/actions/runs/${{github.run_id}}|failed a docs build> on `main` branch"}'\
             ${{ env.SLACK_DEBUG_TESTING == true && secrets.SLACK_INTEGRATION_TESTING_WEBHOOK || secrets.EDGE_TEAM_BOTS_WEBHOOK }}