Rework preview workflows

reakaleek · reakaleek · commit 7c9d6adadf9a · 2025-02-11T15:27:04.000+01:00
diff --git a/.github/workflows/preview-build.yml b/.github/workflows/preview-build.yml
@@ -1,7 +1,7 @@
 name: preview-build
 
 on:
-  pull_request: 
+  pull_request_target: 
     types:
       - opened
       - synchronize
@@ -28,108 +28,136 @@ on:
         default: '**'
         required: false
 
-permissions: 
+permissions:
+  id-token: write
+  deployments: write
   contents: read
   pull-requests: read
 
 jobs:
   build:
     concurrency: 
       group: ${{ github.workflow }}-${{ github.ref }}
-      cancel-in-progress: true
+      cancel-in-progress: ${{ github.event_name == 'pull_request_target' }}
     runs-on: ubuntu-latest
     steps:
 
       - name: Get changed files
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request_target'
         id: check-files
         uses: tj-actions/changed-files@d6e91a2266cdb9d62096cebf1e8546899c6aa18f # v45.0.6
         with:
           files: ${{ inputs.path-pattern != '' && inputs.path-pattern || '**' }}
             
       - name: Checkout
-        if: github.event_name != 'pull_request' || steps.check-files.outputs.any_changed == 'true'
+        if: github.event_name == 'push' || steps.check-files.outputs.any_changed == 'true'
         uses: actions/checkout@v4
         with: 
+          ref: ${{ github.event.pull_request.head.sha || github.ref }}
           persist-credentials: false
-          
-      - name: Generate path prefix
+        
+      - name: Create Deployment
+        if: github.event_name == 'push' || steps.check-files.outputs.any_changed == 'true'
+        uses: actions/github-script@v7
+        id: deployment
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REF: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.ref || github.ref_name }}
+        with:
+          result-encoding: string
+          script: |
+            const { owner, repo } = context.repo;
+            const prNumber = process.env.PR_NUMBER;
+            // const environment = prNumber ? `docs-preview-${prNumber}` : 'docs-preview';
+            const environment = 'docs-preview';
+            const deployment = await github.rest.repos.createDeployment({
+                owner,
+                repo,
+                environment,
+                ref: process.env.REF,
+                auto_merge: false,
+                transient_environment: true,
+                required_contexts: [],
+            })
+            await github.rest.repos.createDeploymentStatus({
+                deployment_id: deployment.data.id,
+                owner,
+                repo,
+                state: "in_progress",
+                log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            })
+            return deployment.data.id
+            
+      - name: Generate env.PATH_PREFIX
+        if: steps.deployment.outputs.result
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
+          GITHUB_REF_NAME: ${{ github.ref_name }}
         run: |
           case "${GITHUB_EVENT_NAME}" in
-            "pull_request")
+            "pull_request_target")
               echo "PATH_PREFIX=/${GITHUB_REPOSITORY}/pull/${PR_NUMBER}" >> $GITHUB_ENV
               ;;
             "push")
               echo "PATH_PREFIX=/${GITHUB_REPOSITORY}/tree/${GITHUB_REF_NAME}" >> $GITHUB_ENV
               if [[ ! "${GITHUB_REF_NAME}" =~ ^(main|master|16\.x)$ ]]; then
-                echo "Unsupported ref name: ${GITHUB_REF_NAME}";
+                echo "Unsupported ref name: '${GITHUB_REF_NAME}'";
                 exit 1;
               fi
               ;;
             *)
-              echo "Unsupported event: ${GITHUB_EVENT_NAME}";
+              echo "Unsupported event: '${GITHUB_EVENT_NAME}'";
               exit 1;
               ;;
           esac
-          
-      - name: Store deployment metadata
-        id: metadata
-        env:
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          REF: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          SHOULD_DEPLOY: ${{ github.event_name == 'pull_request' && steps.check-files.outputs.any_changed || 'true' }}
-        run: |
-          cat << EOF > deployment_metadata.json
-          {
-            "pr_number": "${PR_NUMBER}",
-            "ref": "${REF}",
-            "should_deploy": "${SHOULD_DEPLOY}",
-            "path_prefix": "${PATH_PREFIX}"
-          }
-          EOF
-          echo "should_deploy=${SHOULD_DEPLOY}" >> "${GITHUB_OUTPUT}"
-      
-      - name: Upload deployment metadata
-        uses: actions/upload-artifact@v4
-        with:
-          name: deployment_metadata
-          path: deployment_metadata.json
-          if-no-files-found: error
-          retention-days: 1
-          compression-level: 1
 
       - name: Bootstrap Action Workspace
-        if: github.repository == 'elastic/docs-builder' && steps.metadata.outputs.should_deploy == 'true'
+        if: github.repository == 'elastic/docs-builder' && steps.deployment.outputs.result
+
         uses: ./.github/actions/bootstrap
         
       - name: Set REDESIGN feature flag
-        if: contains(github.event.pull_request.labels.*.name, 'redesign')
+        if: contains(github.event.pull_request.labels.*.name, 'redesign') && steps.deployment.outputs.result
         run: echo "REDESIGN=true" >> $GITHUB_ENV
 
       # we run our artifact directly please use the prebuild
       # elastic/docs-builder@main GitHub Action for all other repositories!
       - name: Build documentation
-        if: github.repository == 'elastic/docs-builder' && steps.metadata.outputs.should_deploy == 'true'
+        if: github.repository == 'elastic/docs-builder' && steps.deployment.outputs.result
         run: |
           dotnet run --project src/docs-builder -- --strict --path-prefix "${PATH_PREFIX}"
 
       - name: Build documentation
-        if: github.repository != 'elastic/docs-builder' && steps.metadata.outputs.should_deploy == 'true'
+        if: github.repository != 'elastic/docs-builder' && steps.deployment.outputs.result
         uses: elastic/docs-builder@main
         continue-on-error: ${{ fromJSON(inputs.continue-on-error != '' && inputs.continue-on-error || 'false') }}
         with:
           prefix: ${{ env.PATH_PREFIX }}
           strict: ${{ fromJSON(inputs.strict != '' && inputs.strict || 'true') }}
 
-      - uses: actions/upload-artifact@v4
-        if: steps.metadata.outputs.should_deploy == 'true'
+      - uses: elastic/docs-builder/.github/actions/aws-auth@main
+        if: steps.deployment.outputs.result
+
+      - name: Upload to S3
+        if: steps.deployment.outputs.result
+        run: |
+          aws s3 sync .artifacts/docs/html "s3://elastic-docs-v3-website-preview${PATH_PREFIX}" --delete
+          aws cloudfront create-invalidation \
+            --distribution-id EKT7LT5PM8RKS \
+            --paths "${PATH_PREFIX}" "${PATH_PREFIX}/*"
+
+      - name: Update deployment status
+        uses: actions/github-script@v7
+        if: always() && steps.deployment.outputs.result
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         with:
-          name: docs
-          path: .artifacts/docs/html/
-          if-no-files-found: error
-          retention-days: 1
-          # The lower the compression-level, the faster the artifact will be uploaded.
-          # But the size of the artifact will be larger.
-          compression-level: 1
+          script: |
+            await github.rest.repos.createDeploymentStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              deployment_id: ${{ steps.deployment.outputs.result }},
+              state: "${{ job.status == 'success' && 'success' || 'failure' }}",
+              environment_url: `https://docs-v3-preview.elastic.dev${process.env.PATH_PREFIX}`,
+              log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+            })
diff --git a/.github/workflows/preview-cleanup.yml b/.github/workflows/preview-cleanup.yml
@@ -23,7 +23,8 @@ jobs:
             const deployments = await github.rest.repos.listDeployments({
               owner,
               repo,
-              environment: `docs-preview-${context.issue.number}`
+              environment: 'docs-preview',
+              ref: context.payload.pull_request.head.ref,
             });
             core.setOutput('is-empty', deployments.data.length === 0)
             for (const deployment of deployments.data) {
diff --git a/.github/workflows/preview-deploy.yml b/.github/workflows/preview-deploy.yml
@@ -14,103 +14,8 @@ permissions:
   actions: read
 
 jobs:
-  deployment-metadata:
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+  do-nothing:
     runs-on: ubuntu-latest
-    outputs: 
-      pr_number: ${{ steps.metadata.outputs.pr_number }}
-      ref: ${{ steps.metadata.outputs.ref }}
-      should_deploy: ${{ steps.metadata.outputs.should_deploy }}
-      path_prefix: ${{ steps.metadata.outputs.path_prefix }}
     steps:
-      - name: Download deployment metadata
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh run download ${{ github.event.workflow_run.id }} \
-            --repo "${GITHUB_REPOSITORY}" \
-            --name deployment_metadata
-      - name: Get deployment metadata
-        id: metadata
-        run: |
-          {
-            echo "pr_number=$(jq -r '.pr_number' deployment_metadata.json)"
-            echo "ref=$(jq -r '.ref' deployment_metadata.json)"
-            echo "path_prefix=$(jq -r '.path_prefix' deployment_metadata.json)"
-            echo "should_deploy=$(jq -r '.should_deploy' deployment_metadata.json)"
-          } >> "${GITHUB_OUTPUT}"
-    
-  deploy:
-    needs: deployment-metadata
-    if: needs.deployment-metadata.outputs.should_deploy == 'true'
-    runs-on: ubuntu-latest
-    concurrency: 
-      group: ${{ github.workflow }}-${{ needs.deployment-metadata.outputs.pr_number }}
-      cancel-in-progress: true
-    steps:
-      - name: Create Deployment
-        uses: actions/github-script@v7
-        id: deployment
-        env:
-          PR_NUMBER: ${{ needs.deployment-metadata.outputs.pr_number }}
-          REF: ${{ needs.deployment-metadata.outputs.ref }}
-        with:
-          result-encoding: string
-          script: |
-            const { owner, repo } = context.repo;
-            const prNumber = process.env.PR_NUMBER;
-            const environment = prNumber ? `docs-preview-${prNumber}` : 'docs-preview';
-            const deployment = await github.rest.repos.createDeployment({
-                owner,
-                repo,
-                environment,
-                ref: process.env.REF,
-                auto_merge: false,
-                required_contexts: [],
-            })
-            await github.rest.repos.createDeploymentStatus({
-                deployment_id: deployment.data.id,
-                owner,
-                repo,
-                state: "in_progress",
-                log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
-            })
-            return deployment.data.id
-            
-      - name: Download docs
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh run download ${{ github.event.workflow_run.id }} \
-            --repo "${GITHUB_REPOSITORY}" \
-            --name docs \
-            --dir html
-
-      - uses: elastic/docs-builder/.github/actions/aws-auth@main
-
-      - name: Upload to S3
-        env:
-          PR_NUMBER: ${{ needs.deployment-metadata.outputs.pr_number }}
-          PATH_PREFIX: ${{ needs.deployment-metadata.outputs.path_prefix }}
-        run: |
-          aws s3 sync ./html "s3://elastic-docs-v3-website-preview${PATH_PREFIX}" --delete
-          aws cloudfront create-invalidation \
-            --distribution-id EKT7LT5PM8RKS \
-            --paths "${PATH_PREFIX}" "${PATH_PREFIX}/*"
-
-      - name: Update deployment status
-        uses: actions/github-script@v7
-        if: always() && steps.deployment.outputs.result
-        env:
-          PR_NUMBER: ${{ needs.deployment-metadata.outputs.pr_number }}
-          PATH_PREFIX: ${{ needs.deployment-metadata.outputs.path_prefix }}
-        with:
-          script: |
-            await github.rest.repos.createDeploymentStatus({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              deployment_id: ${{ steps.deployment.outputs.result }},
-              state: "${{ job.status == 'success' && 'success' || 'failure' }}",
-              environment_url: `https://docs-v3-preview.elastic.dev${process.env.PATH_PREFIX}`,
-              log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
-            })
+      - name: Do nothing
+        run: echo "This is here for backwards compatibility. After validating that the preview-build workflow is working as expected, you can remove this workflow file."
diff --git a/docs/migration/guide/how-to-set-up-docs-previews.md b/docs/migration/guide/how-to-set-up-docs-previews.md
@@ -4,9 +4,8 @@ This guide will help you set up docs previews for your GitHub repository.
 
 ## GitHub Workflows
 
-The docs preview system consists of three GitHub Workflows:
+The docs preview system consists of two GitHub Workflows:
 - [`docs-build.yml`](#build): **Build** the docs on a PR
-- [`docs-deploy.yml`](#deploy): **Deploy** the docs to our preview environment
 - [`docs-cleanup.yml`](#cleanup): **Cleanup** the docs after a PR is merged or closed
 
 
@@ -22,65 +21,31 @@ This way you only build and deploy the docs when there are changes to the docs a
 
 ```yaml
 ---
-name: docs-build <1>
+name: docs-build
 
 on:
-  push: <2>
+  push:
     branches: 
         - main 
-  pull_request: ~
+  pull_request_target: ~
 
 jobs:
   docs-preview:
-    uses: elastic/docs-builder/.github/workflows/preview-build.yml <3>
+    uses: elastic/docs-builder/.github/workflows/preview-build.yml <2>
     with:
-      path-pattern: docs/** <4>
+      path-pattern: docs/** <3>
     permissions:
+      id-token: write
+      deployments: write
       contents: read
       pull-requests: read
 ```
 
-1. The naming is important so that the `docs-deploy` workflow is triggered.
-2. You can omit the `push` event if you only want to build the docs on PRs.
-3. Reusable workflow: [elastic/docs-builder/.github/workflows/preview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-build.yml)
-4. This should be the path to your docs folder.
-
+1. Reusable workflow: [elastic/docs-builder/.github/workflows/preview-build.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-build.yml)
+2. This should be the path to your docs folder.
 
 ::::
 
-### Deploy
-
-This workflow is triggered when the `docs-build` workflow is completed. The underlying reusable workflow, downloads the artifact and deploys the docs to our preview environment.
-
-
-::::{dropdown} .github/workflows/docs-deploy.yml
-:open:
-
-```yaml
----
-name: docs-deploy
-
-on:
-  workflow_run:
-    workflows: 
-      - docs-build <1>
-    types:
-      - completed
-
-jobs:
-  docs-preview:
-    uses: elastic/docs-builder/.github/workflows/preview-deploy.yml <2>
-    permissions:
-      contents: none <3>
-      id-token: write
-      deployments: write
-      actions: read
-```
-1. The name of the previously mentioned `docs-build` workflow.
-2. Reusable workflow: [elastic/docs-builder/.github/workflows/preview-deploy.yml](https://github.com/elastic/docs-builder/blob/main/.github/workflows/preview-deploy.yml)
-3. No need to read the code.
-
-::::
 
 ### Cleanup
 
