feat: run GitLab E2E for labeled fork pull requests (#149)

Fork pull requests currently skip GitLab E2E because `pull_request`
workflows cannot access `GITLAB_TRIGGER_TOKEN`.

Allow maintainers with write access to request the full suite with the
`run-e2e` label. A `pull_request` helper starts the trusted
`workflow_run` handler. The handler checks the labeler, helper file, PR
state, and exact head SHA before it calls GitLab. It does not load fork
code, artifacts, or caches. This flow uses no `pull_request_target`
trigger.

Both workflows must reach `main` before use. The fork branch must
include the unchanged helper. New commits require another review and a
new `run-e2e` label event.

Author: fengmk2

.github/workflows/e2e-request.yml

@@ -0,0 +1,23 @@
+name: GitLab E2E request
+
+# The privileged workflow verifies this file's Git blob before it trusts this
+# run-name format. Keep all request metadata in GitHub's run record, not artifacts.
+run-name: "PR #${{ github.event.pull_request.number }}: ${{ github.event.action }} ${{ github.event.label.name }} at ${{ github.event.pull_request.head.sha }}"
+
+on:
+  pull_request:
+    branches: [main]
+    # New commits need a fresh review and label event.
+    types: [labeled]
+
+permissions: {}
+
+jobs:
+  request:
+    if: >-
+      github.event.label.name == 'run-e2e' &&
+      github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - run: echo 'GitLab E2E requested. The workflow on main will validate this request.'

.github/workflows/gitlab-e2e.yml

@@ -6,6 +6,9 @@ on:
     tags: ["v*"]
   pull_request:
     branches: [main]
+  workflow_run:
+    workflows: [GitLab E2E request]
+    types: [completed]
   merge_group:
   workflow_dispatch:
     inputs:
@@ -30,15 +33,29 @@ permissions:
 jobs:
   gitlab-e2e:
     name: GitLab E2E
+    if: >-
+      github.event_name != 'workflow_run' ||
+      (github.event.workflow_run.event == 'pull_request' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.path == '.github/workflows/e2e-request.yml' &&
+       github.event.workflow_run.head_repository.full_name != github.repository)
     runs-on: ubuntu-latest
     timeout-minutes: 35
+    # Keep this privileged job API-only: no PR checkout, artifacts, or caches.
     steps:
       - name: Resolve test parameters
         id: parameters
         env:
           EVENT_NAME: ${{ github.event_name }}
           EVENT_REF: ${{ github.ref }}
           EVENT_REF_NAME: ${{ github.ref_name }}
+          REQUEST_EVENT: ${{ github.event.workflow_run.event }}
+          REQUEST_CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+          REQUEST_PATH: ${{ github.event.workflow_run.path }}
+          REQUEST_TITLE: ${{ github.event.workflow_run.display_title }}
+          REQUEST_ACTOR: ${{ github.event.workflow_run.actor.login }}
+          REQUEST_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+          REQUEST_HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
           PR_HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
           PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
@@ -53,11 +70,68 @@ jobs:
           setup_vp_ref="$GITHUB_SHA"
           suite=required
           vite_plus_version=latest
+          skip_reason=""
+
+          resolve_fork_request() {
+            should_run=false
+            skip_reason='Only a successful run-e2e label request for a fork PR can approve a GitLab E2E run.'
+            local request_pattern='^PR #([1-9][0-9]*): labeled run-e2e at ([0-9a-f]{40})$'
+            if [ "$REQUEST_EVENT" != "pull_request" ] || [ "$REQUEST_CONCLUSION" != "success" ] ||
+              [ "$REQUEST_PATH" != ".github/workflows/e2e-request.yml" ] ||
+              [ "$REQUEST_HEAD_REPOSITORY" = "$GITHUB_REPOSITORY" ] ||
+              ! [[ "$REQUEST_TITLE" =~ $request_pattern ]]; then
+              return
+            fi
+
+            local pr_number="${BASH_REMATCH[1]}"
+            if [ "${BASH_REMATCH[2]}" != "$REQUEST_HEAD_SHA" ]; then
+              echo "::error::The request title does not match the workflow run's head SHA."
+              exit 1
+            fi
+
+            # Check the original labeler's access, even on reruns.
+            # GitHub maps the maintain role to write.
+            local permission
+            permission="$(gh api "repos/${GITHUB_REPOSITORY}/collaborators/${REQUEST_ACTOR}/permission" --jq '.permission')"
+            case "$permission" in
+              admin | write) ;;
+              *)
+                echo "::error::Adding run-e2e requires repository write access to approve a test run."
+                exit 1
+                ;;
+            esac
+
+            # Compare Git blobs to reject altered request triggers or run names.
+            local workflow_url="repos/${GITHUB_REPOSITORY}/contents/${REQUEST_PATH}"
+            local trusted_blob request_blob
+            trusted_blob="$(gh api "${workflow_url}?ref=${GITHUB_SHA}" --jq '.sha')"
+            if ! request_blob="$(gh api "${workflow_url}?ref=${REQUEST_HEAD_SHA}" --jq '.sha')" ||
+              [ "$request_blob" != "$trusted_blob" ]; then
+              echo "::error::The fork must include e2e-request.yml unchanged from main. Update the branch, then remove and re-add run-e2e."
+              exit 1
+            fi
+
+            # Fork runs can have an empty workflow_run.pull_requests array.
+            # Resolve the PR from the verified title and cross-check its head.
+            local pull_request
+            pull_request="$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${pr_number}")"
+            if ! jq -e --arg sha "$REQUEST_HEAD_SHA" --arg head_repo "$REQUEST_HEAD_REPOSITORY" --arg repo "$GITHUB_REPOSITORY" \
+              '.state == "open" and .head.sha == $sha and .head.repo.full_name == $head_repo and
+               .base.repo.full_name == $repo and .base.ref == "main" and any(.labels[]; .name == "run-e2e")' \
+              <<< "$pull_request" > /dev/null; then
+              skip_reason='This approval is stale or does not match the PR: check its head, base, and run-e2e label. Review the current commit, then remove and re-add run-e2e to test it.'
+              return
+            fi
+
+            should_run=true
+            setup_vp_ref="$REQUEST_HEAD_SHA"
+            suite=full
+          }
 
           if [ "$EVENT_NAME" = "pull_request" ]; then
             if [ "$PR_HEAD_REPOSITORY" != "$GITHUB_REPOSITORY" ]; then
               should_run=false
-              echo "The workflow skips fork pull requests. The merge queue or a maintainer can test these changes."
+              skip_reason='A maintainer with write access can review this fork PR and add the run-e2e label to test its current commit. New commits require removing and re-adding the label. The merge queue also tests the reviewed merge commit.'
             else
               setup_vp_ref="$PR_HEAD_SHA"
               while IFS= read -r changed_path; do
@@ -69,6 +143,8 @@ jobs:
                 esac
               done < <(gh api --paginate "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" --jq '.[].filename')
             fi
+          elif [ "$EVENT_NAME" = "workflow_run" ]; then
+            resolve_fork_request
           elif [ "$EVENT_NAME" = "merge_group" ]; then
             suite=full
           elif [ "$EVENT_NAME" = "workflow_dispatch" ]; then
@@ -90,10 +166,11 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
           if [ "$should_run" = "false" ]; then
+            echo "$skip_reason"
             {
               echo "### GitLab E2E"
               echo
-              echo "The workflow skipped this fork pull request. The merge queue tests the reviewed merge commit."
+              echo "$skip_reason"
             } >> "$GITHUB_STEP_SUMMARY"
           fi
 

README.md

@@ -419,7 +419,7 @@ setup-vp also provides a GitLab CI/CD remote template hosted from this GitHub re
 
 See [GitLab integration notes](rfcs/gitlab-integration.md) for the design background, constraints, and follow-up work.
 
-The dedicated [GitLab end-to-end test project](https://gitlab.com/fengmk2/setup-vp-gitlab-test) tests each setup-vp pull request, merge, and release. The pipeline loads the template, bootstrap script, and compiled runtime from the exact setup-vp commit or release tag that it tests.
+The dedicated [GitLab end-to-end test project](https://gitlab.com/fengmk2/setup-vp-gitlab-test) tests same-repository pull requests, approved fork pull requests, merge queue commits, merges, and releases. The pipeline loads the template, bootstrap script, and compiled runtime from the exact setup-vp commit or release tag that it tests.
 
 ### Basic GitLab Usage
 
@@ -689,6 +689,12 @@ vp install
 - Generated files under `dist/` must be committed, including `dist/index.mjs` for the GitHub Action, `dist/gitlab/index.mjs` for the GitLab template, and `dist/azure/index.mjs` for the Azure Pipelines runtime
 - Pre-commit hooks (via husky + lint-staged) will automatically run `vp check --fix` on staged files via `vpx lint-staged`
 
+### GitLab E2E for Fork Pull Requests
+
+After reviewing the commit, a maintainer with write access can add `run-e2e` to run the full GitLab suite. Approve the Actions run if prompted.
+
+For new commits, review the changes and remove and re-add `run-e2e`. Results and the GitLab pipeline link appear in the GitLab E2E workflow summary.
+
 ### Releasing
 
 Releases are published as git tags; there is no npm package, but the `package.json` version tracks the latest release. Consumers pin an exact version tag such as `voidzero-dev/setup-vp@v1.19.0` or a commit SHA. The `v1` major tag is frozen at v1.15.0 and is never moved (an org-level ruleset rejects tag force-pushes).