Use the workflow file associate git reference

Author: pedro-psb

.github/workflows/docs-ci.yml

@@ -8,21 +8,64 @@ jobs:
   build:
     runs-on: "ubuntu-latest"
     steps:
+      # The git reference for the workflow isn't acessible directly. That's a workaround:
+      # https://github.com/actions/toolkit/issues/1264#issuecomment-2496121368
+      - name: "Get called workflow reference"
+        run: |
+          JWT=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL")
+          PAYLOAD=$(echo "$JWT" | cut -d '.' -f 2 | base64 -d 2>/dev/null || true)
+
+          WORKFLOW_FULL_REF=$(
+            echo "$PAYLOAD" \
+              | grep -o '"job_workflow_ref":"[^"]*"' \
+              | cut -d':' -f2 \
+              | cut -d'@' -f2 \
+              | tr -d '"'
+          )
+
+          echo "WORKFLOW_FULL_REF=$WORKFLOW_FULL_REF"
+
+          case $WORKFLOW_FULL_REF in
+            refs/heads/*)
+              WORKFLOW_REF=${WORKFLOW_FULL_REF#refs/heads/}
+              ;;
+            refs/tags/*)
+              WORKFLOW_REF=${WORKFLOW_FULL_REF#refs/tags/}
+              ;;
+            refs/pull/*/merge)
+              # exception: we got triggered by a pull request, the ref is the base branch
+              WORKFLOW_REF=$GITHUB_HEAD_REF
+              ;;
+          esac
+
+          echo "::notice ::WORKFLOW_FULL_REF=$WORKFLOW_FULL_REF"
+          echo "::notice ::WORKFLOW_REF=$WORKFLOW_REF"
+
+          echo "WORKFLOW_REF=$WORKFLOW_REF" | tee -a $GITHUB_ENV
+
+      - name: "Checkout pulp-docs repository"
+        uses: "actions/checkout@v4"
+        with:
+          repository: "pulp/pulp-docs"
+          path: "pulp-docs"
+          ref: "${{ env.WORKFLOW_REF }}"
+          fetch-depth: 0
+
+      - name: "Get pulp-docs commit"
+        working-directory: "pulp-docs"
+        run: |
+          set -e
+          echo "CHECKOUT_SHA=$(git rev-parse HEAD)" | tee -a $GITHUB_ENV
 
       - name: "Instructions to run locally"
-        shell: "bash"
         run: |
           cat <<EOL
-          To run this locally, make sure:
-          1. You have pulp-docs and your plugin checkout in the same dir.
-          2. You have the latest pulp-docs availabe in your python environment
-
-          Then run:
+          Assuming you have pulp-docs and your plugin checkout in the same dir, run:
 
           cd pulp-docs
+          git checkout ${{ env.CHECKOUT_SHA }}
           pulp-docs fetch --dest /tmp/pulp-docs-tmp
           pulp-docs build --path pulp-docs@..:${{ github.event.repository.name }}@..:/tmp/pulp-docs-tmp
-
           EOL
 
       # The caller repository and context is used
@@ -32,16 +75,6 @@ jobs:
         with:
           path: "${{ github.event.repository.name }}"
 
-      - name: "Checkout pulp-docs repository"
-        uses: "actions/checkout@v4"
-        with:
-          repository: "pulp/pulp-docs"
-          path: "pulp-docs"
-          # ref: "rewrite-as-mkdocs-plugin"
-          # TODO: revert. using this because pulpcore-selinux is not included in rewrite-as-mkdocs-plugin
-          ref: "experiment-reusable-ci-workflow"
-          fetch-depth: 0
-
       - uses: "actions/setup-python@v5"
         with:
           python-version: "3.12"
@@ -54,15 +87,15 @@ jobs:
 
       - name: "Build Docs"
         working-directory: "pulp-docs"
+        env:
+          DOCS_PATH: "pulp-docs@..:${{ github.event.repository.name }}@.."
+          DOCS_TMPDIR: "/tmp/pulp-docs-tmp"
         run: |
-          PATH="pulp-docs@..:${{ github.event.repository.name }}@.."
-          TMPDIR="/tmp/pulp-docs-tmp"
-          pulp-docs fetch --path "$PATH" --dest "$TMPDIR"
-          pulp-docs build --path "$PATH:$TMPDIR"
+          pulp-docs fetch --path-exclude "$DOCS_PATH" --dest "$DOCS_TMPDIR"
+          pulp-docs build --path "$DOCS_PATH:$DOCS_TMPDIR"
 
       - name: "Sanity Check"
         working-directory: "pulp-docs"
-        shell: "bash"
         run: |
           echo "Checking that the namespace for the component under CI exists in the built docs."
           ls "site/${{ github.event.repository.name }}/docs"

.github/workflows/pr.yml

@@ -10,9 +10,13 @@ concurrency:
 
 jobs:
   docs:
+    permissions:
+      contents: "read"
+      id-token: "write"
     uses: "./.github/workflows/docs-ci.yml"
 
   tests:
+    needs: "docs"
     uses: "./.github/workflows/tests.yml"
 
   ready-to-ship:

src/pulp_docs/cli.py

@@ -101,14 +101,19 @@ async def clone_repository(repo_url: str) -> None:
     envvar="PULPDOCS_DIR",
     help="Path to mkdocs.yml config file",
 )
-@path_option
-def fetch(dest, config_file, find_path):
+@click.option(
+    "--path-exclude",
+    default="",
+    callback=find_path_callback,
+    help="A colon separated list of lookup paths to exclude in the form [repo1@]path1 [:[repo2@]path2 [...]].",
+)
+def fetch(dest, config_file, path_exclude):
     """Fetch repositories to destination dir."""
     dest_path = Path(dest)
-    config = load_config(config_file)
-    all_components = config.plugins["PulpDocs"].config.components
+    pulpdocs_plugin = load_config(config_file).plugins["PulpDocs"]
+    all_components = pulpdocs_plugin.config.components
     all_repositories_set = {r.git_url for r in all_components if r.git_url}
-    found_components = load_components(find_path, config_file, draft=True)
+    found_components = load_components(path_exclude, pulpdocs_plugin.config, draft=True)
     found_repositories_set = {r.git_url for r in found_components}
     final_repositories_set = all_repositories_set - found_repositories_set
 

src/pulp_docs/plugin.py

@@ -257,7 +257,7 @@ def rss_items() -> list:
     return rss_feed["items"][:20]
 
 
-def load_components(find_path: list[str], config: MkDocsConfig, draft: bool):
+def load_components(find_path: list[str], config: PulpDocsPluginConfig, draft: bool):
     loaded_components = []
     for component_opt in config.components:
         component = Component.build(find_path, component_opt)