score/.github/workflows/docs.yml at main · eclipse-score/score · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# *******************************************************************************
# Copyright (c) 2025 Contributors to the Eclipse Foundation
#
# See the NOTICE file(s) distributed with this work for additional
# information regarding copyright ownership.
#
# This program and the accompanying materials are made available under the
# terms of the Apache License Version 2.0 which is available at
# https://www.apache.org/licenses/LICENSE-2.0
#
# SPDX-License-Identifier: Apache-2.0
# *******************************************************************************

name: Documentation
on:
  pull_request_target:
    types: [opened, reopened, synchronize] # Handles forked PRs
  push:
    branches:
      - main # docs are built only on push to main branch, for feature branches there are PR builds
  merge_group:
    types: [checks_requested]
  release:
    types: [created]

jobs:
  docs-build:
    name: Build documentation
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      # ------------------------------------------------------------------------------
      # Checkout the correct branch safely in all scenarios (PRs, forks, merges)
      # ------------------------------------------------------------------------------
      # | Condition                              | Event Type         | Checked Out Branch    |
      # |----------------------------------------|--------------------|-----------------------|
      # | github.head_ref                        | pull_request_target | PR branch (source branch) |
      # | github.event.pull_request.head.ref     | pull_request        | PR branch (source branch) |
      # | github.ref                             | push, merge_group   | The branch being pushed/merged |
      # ------------------------------------------------------------------------------
      # ------------------------------------------------------------------------------
      # Checkout the correct repository safely in all scenarios (PRs, forks, merges)
      # ------------------------------------------------------------------------------
      # | Condition                                      | Event Type         | Checked Out Repository           |
      # |------------------------------------------------|--------------------|----------------------------------|
      # | github.event.pull_request.head.repo.full_name  | pull_request       | Forked repository (if PR is from a fork) |
      # | github.repository                              | push, merge_group  | Default repository (same repo PRs, merges, pushes) |
      - name: Checkout repository (Handle all events)
        uses: actions/checkout@v4.2.2
        with:
          ref: ${{ github.head_ref || github.event.pull_request.head.ref || github.ref }}
          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}

      - name: Verify Doc-as-Code version
        if: ${{ github.event_name == 'pull_request_target' }}
        id: doc_version
        run: |
          if python3 .github/scripts/check_doc_tool_version.py \
            --doc docs/score_tools/doc_as_code.rst \
            --dac-module-name score_docs_as_code
          then
            echo "Doc-as-Code version matching. Everything is fine."
            echo "mismatch=False" >> "$GITHUB_OUTPUT"
          else
            echo "mismatch=True" >> "$GITHUB_OUTPUT"
          fi

      - name: Find Comment
        if: ${{ github.event_name == 'pull_request_target' }}
        uses: peter-evans/find-comment@v3
        id: fc
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: 'github-actions[bot]'
          body-includes: Docs-as-Code version mismatch detected

      - name: Warn in PR if docs-as-code version mismatch
        if: ${{ github.event_name == 'pull_request_target' && steps.doc_version.outputs.mismatch == 'True' && steps.fc.outputs.comment-id == '' }}
        uses: peter-evans/create-or-update-comment@v4
        with:
          issue-number: ${{github.event.pull_request.number}}
          body: |
            ⚠️ **Docs-as-Code version mismatch detected**
            Please check the CI build logs for details and align the documentation version with the Bazel dependency.

      - name: Setup Bazel
        uses: bazel-contrib/setup-bazel@0.9.1
      - name: Install Graphviz
        run: sudo apt update && sudo apt install -y graphviz
      - name: Build documentation
        run: |
          bazel run //:docs -- --github_user=${{ github.repository_owner }} --github_repo=${{ github.event.repository.name }}
          tar -cf github-pages.tar _build
        # ------------------------------------------------------------------------------
        # Generate a unique artifact name to ensure proper tracking in all scenarios
        # ------------------------------------------------------------------------------
        # | Condition                                     | Event Type             | Artifact Name Value                          |
        # |-----------------------------------------------|------------------------|----------------------------------------------|
        # | github.event.pull_request.head.sha            | pull_request           | PR commit SHA (ensures uniqueness per PR)    |
        # | github.event.pull_request.head.sha            | pull_request_target    | PR commit SHA (ensures uniqueness per PR)    |
        # | github.sha                                    | push, merge_group      | Current commit SHA (used for main branch)    |
        # ------------------------------------------------------------------------------
      - name: Upload artifact for job analysis
        uses: actions/upload-artifact@v4.4.0
        with:
          name: github-pages-${{ github.event.pull_request.head.sha || github.sha }}
          path: github-pages.tar
          retention-days: 1
          if-no-files-found: error

  docs-deploy:
    name: Deploy documentation to GitHub Pages
    permissions:
      pages: write
      id-token: write
      contents: write
      pull-requests: write
    runs-on: ubuntu-latest
    needs: docs-build
    steps:
      # ------------------------------------------------------------------------------
      # Always checks out the BASE repository since pull_request_target is used.
      # This ensures that the workflow runs with trusted code from the base repo,
      # even when triggered by a pull request from a fork.
      # ------------------------------------------------------------------------------
      - name: Checkout repository
        uses: actions/checkout@v4.2.2

      - name: Download documentation artifact
        uses: actions/download-artifact@v4.1.8
        # ------------------------------------------------------------------------------
        # Generate a unique artifact name to ensure proper tracking in all scenarios
        # ------------------------------------------------------------------------------
        # | Condition                                     | Event Type             | Artifact Name Value                          |
        # |-----------------------------------------------|------------------------|----------------------------------------------|
        # | github.event.pull_request.head.sha            | pull_request           | PR commit SHA (ensures uniqueness per PR)    |
        # | github.event.pull_request.head.sha            | pull_request_target    | PR commit SHA (ensures uniqueness per PR)    |
        # | github.sha                                    | push, merge_group      | Current commit SHA (used for main branch)    |
        # ------------------------------------------------------------------------------
        with:
          name: github-pages-${{ github.event.pull_request.head.sha || github.sha }}

      - name: Untar documentation artifact
        run: mkdir -p extracted_docs && tar -xf github-pages.tar -C extracted_docs

      - name: Deploy 🚀
        id: pages-deployment
        uses: ./.github/actions/deploy-versioned-pages
        with:
          source_folder: extracted_docs/_build