Update documentation

This reverts commit 878b38deac.

.github/workflows/build.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Clone the code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     - name: Setup Go
-      uses: actions/setup-go@v5
+      uses: actions/setup-go@v6
       with:
         go-version-file: go.mod
 

.github/workflows/e2e-tests.yml

@@ -0,0 +1,52 @@
+name: E2E Tests [reusable]
+
+on:
+  workflow_call:
+    secrets:
+      OP_CONNECT_CREDENTIALS:
+        description: '1Password Connect credentials'
+        required: true
+      OP_CONNECT_TOKEN:
+        description: '1Password Connect token'
+        required: true
+      OP_SERVICE_ACCOUNT_TOKEN:
+        description: '1Password service account token'
+        required: true
+
+jobs:
+  e2e-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Install dependencies
+        run: go mod tidy
+
+      - name: Create kind cluster
+        uses: helm/kind-action@v1
+        with:
+          cluster_name: onepassword-operator-test-e2e
+
+      # install cli to interact with item in 1Password to update/read using `testhelper/op` package
+      - name: Install 1Password CLI
+        uses: 1password/install-cli-action@v2
+        with:
+          version: 2.32.0
+
+      - name: Create '1password-credentials.json' file
+        env:
+          OP_CONNECT_CREDENTIALS: ${{ secrets.OP_CONNECT_CREDENTIALS }}
+        run: |
+          echo "$OP_CONNECT_CREDENTIALS" > 1password-credentials.json
+
+      - name: Run E2E tests
+        run: make test-e2e
+        env:
+          OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
+          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}

.github/workflows/lint.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Clone the code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 

.github/workflows/ok-to-test.yml

@@ -0,0 +1,25 @@
+# Write comments "/ok-to-test sha=<hash>" on a pull request. This will emit a repository_dispatch event.
+name: Ok To Test
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  ok-to-test:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write # For adding reactions to the pull request comments
+      contents: write # For executing the repository_dispatch event
+    # Only run for PRs, not issue comments
+    if: ${{ github.event.issue.pull_request }}
+    steps:
+      - name: Slash Command Dispatch
+        uses: volodymyrZotov/slash-command-dispatch@7c1b623a2b0eba93f684c34f689a441f0be84cf1 # TODO: use peter-evans/slash-command-dispatch when fix for team permissions is released https://github.com/peter-evans/slash-command-dispatch/pull/424
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          reaction-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-type: pull-request
+          commands: ok-to-test
+          # The repository permission level required by the user to dispatch commands. Only allows 1Password collaborators to run this.
+          permission: write

.github/workflows/release-pr.yml

@@ -43,7 +43,7 @@ jobs:
     name: Create Release Pull Request
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Parse release version
         id: get_version

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
       DOCKER_CLI_EXPERIMENTAL: "enabled"
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 

.github/workflows/test-e2e-fork.yml

@@ -0,0 +1,67 @@
+name: E2E tests [fork]
+
+on:
+  repository_dispatch:
+    types: [ ok-to-test-command ]
+
+permissions:
+  contents: read
+  checks: write
+
+concurrency:
+  group: e2e-fork-${{ github.event.client_payload.pull_request.number || github.run_id }}
+  cancel-in-progress: true # cancel previous job runs for the same branch
+
+jobs:
+  run-e2e-tests:
+    uses: ./.github/workflows/e2e-tests.yml
+    if: |
+      github.event_name == 'repository_dispatch' &&
+      github.event.client_payload.slash_command.args.named.sha != '' &&
+      contains(
+        github.event.client_payload.pull_request.head.sha,
+        github.event.client_payload.slash_command.args.named.sha
+      )
+    secrets:
+      OP_CONNECT_CREDENTIALS: ${{ secrets.OP_CONNECT_CREDENTIALS }}
+      OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
+      OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+
+  update-check-status:
+    needs: run-e2e-tests
+    runs-on: ubuntu-latest
+    if: always() && github.event_name == 'repository_dispatch'
+    steps:
+      - uses: actions/github-script@v6
+        env:
+          ref: ${{ github.event.client_payload.pull_request.head.sha }}
+          conclusion: ${{ needs.run-e2e-tests.result }}
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { data: checks } = await github.rest.checks.listForRef({
+              ...context.repo,
+              ref: process.env.ref
+            });
+
+            // update the 'check-external-pr' check run
+            const check = checks.check_runs.filter(c => c.name === 'check-external-pr');
+
+            const { data: result } = await github.rest.checks.update({
+              ...context.repo,
+              check_run_id: check[0].id,
+              status: 'completed',
+              conclusion: process.env.conclusion
+            });
+
+            // update the 'run-e2e-tests' check run from 'test-e2e.yml' workflow
+            const check = checks.check_runs.filter(c => c.name === 'run-e2e-tests');
+
+            const { data: result } = await github.rest.checks.update({
+              ...context.repo,
+              check_run_id: check[0].id,
+              status: 'completed',
+              conclusion: process.env.conclusion
+            });
+
+            return null;

.github/workflows/test-e2e.yml

@@ -1,48 +1,43 @@
-name: Test E2E
+name: E2E Tests
 
 on:
   pull_request:
     types: [opened, synchronize, reopened]
     branches: ['**']   # run for PRs targeting any branch (main and others)
+    paths-ignore: &ignore_paths
+      - 'docs/**'
+      - '*.md'
+      - '.golangci.yml'
+      - '.gitignore'
+      - '.dockerignore'
+      - 'LICENSE'
+  push:
+    branches: [main]
+    paths-ignore: *ignore_paths
 
 concurrency:
   group: e2e-${{ github.event.pull_request.head.ref }}
   cancel-in-progress: true  # cancel previous job runs for the same branch
 
 jobs:
-  e2e-test:
+  check-external-pr:
     runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
     steps:
-      - name: Checkout code
+      - name: Check if PR is from external contributor
-        uses: actions/checkout@v4
-
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: go.mod
-
-      - name: Install dependencies
-        run: go mod tidy
-
-      - name: Create kind cluster
-        uses: helm/kind-action@v1
-        with:
-          cluster_name: onepassword-operator-test-e2e
-
-        # install cli to interact with item in 1Password to update/read using `testhelper/op` package
-      - name: Install 1Password CLI
-        uses: 1password/install-cli-action@v2
-        with:
-          version: 2.32.0
-
-      - name: Create '1password-credentials.json' file
-        env:
-          OP_CONNECT_CREDENTIALS: ${{ secrets.OP_CONNECT_CREDENTIALS }}
         run: |
-          echo "$OP_CONNECT_CREDENTIALS" > 1password-credentials.json
+          if [ "${{ github.event.pull_request.head.repo.full_name }}" != "${{ github.repository }}" ]; then
+            echo "❌ External PR detected. This workflow requires approval from a maintainer."
+            echo "Please ask a maintainer to run '/ok-to-test' command to trigger the fork workflow."
+            exit 1
+          fi
+          echo "✅ Internal PR detected. Proceeding with tests."
 
-      - name: Run E2E tests
+  run-e2e-tests:
-        run: make test-e2e
+    needs: check-external-pr
-        env:
+    if: always() && (needs.check-external-pr.result == 'success' || github.event_name != 'pull_request')
+    uses: ./.github/workflows/e2e-tests.yml
+    secrets:
+      OP_CONNECT_CREDENTIALS: ${{ secrets.OP_CONNECT_CREDENTIALS }}
       OP_CONNECT_TOKEN: ${{ secrets.OP_CONNECT_TOKEN }}
       OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}

.github/workflows/test.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Clone the code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
 

docs/fork-pr-testing.md

@@ -0,0 +1,109 @@
+# Fork PR Testing Guide
+
+This document explains how to test external pull requests using the dispatch action workflow system.
+
+## Overview
+
+The testing system consists of three main workflows:
+
+1. **E2E Tests** (`test-e2e.yml`) - Runs automatically for internal PRs, requires approval for external PRs
+2. **Ok To Test** (`ok-to-test.yml`) - Processes slash commands to trigger fork testing
+3. **E2E tests [fork]** (`test-e2e-fork.yml`) - Triggered manually via slash commands for external PRs
+
+## How It Works
+
+### 1. Initial PR State
+When a PR is created or updated:
+- The `test-e2e.yml` workflow automatically runs
+- For **external PRs**: The `check-external-pr` job detects it's from a fork and **fails intentionally**
+- For **internal PRs**: The workflow proceeds normally with e2e tests
+- External PRs show ❌ for the check-external-pr job with a message asking for maintainer approval
+
+### 2. Manual Approval Required
+**Important**: External PRs require manual approval before workflows can run.
+
+**Steps for maintainers:**
+1. Go to the PR page
+2. Click **"Approve workflow to run"** button
+3. The workflow will then execute
+
+**Note**: The `test-e2e.yml` workflow will still fail for external PRs even after approval, as it's designed to prevent automatic execution. Need to use the slash command instead.
+
+### 3. Testing External PRs
+Once the initial checks have run (and failed), maintainers can test the PR using slash commands:
+
+#### Step-by-Step Process:
+
+1. **Navigate to the PR**
+   - Go to the pull request you want to test
+
+2. **Add a comment with slash command**
+   ```
+   /ok-to-test sha=<commit-sha>
+   ```
+   Replace `<commit-sha>` with the actual commit SHA from the PR.
+   
+   **Note**: Use the short SHA.
+
+3. **Dispatch Action Triggers**
+   - The `ok-to-test.yml` workflow processes the slash command
+   - It triggers a `repository_dispatch` event with type `ok-to-test-command`
+   - The `test-e2e-fork.yml` workflow starts
+
+4. **Workflow Execution**
+   The fork workflow runs two jobs:
+   
+   **a) `run-e2e-tests` job** (conditional)
+   - Only runs if:
+     - Event is `repository_dispatch`
+     - SHA parameter is not empty
+     - PR head SHA contains the provided SHA
+   - Calls the reusable `run-e2e-tests.yml` workflow
+   - Runs the actual E2E tests if conditions are met
+   
+   **b) `update-check-status` job** (conditional)
+   - Runs after `e2e-tests` completes
+   - Updates the existing check for job named "run-e2e-tests" from 'test-e2e.yml' workflow
+   - Sets the conclusion based on `run-e2e-tests` result:
+     - ✅ **Success** if tests pass
+     - ❌ **Failure** if tests fail
+
+## Troubleshooting
+
+### Workflow Not Running
+- **Check**: Ensure you've approved the workflow to run
+- **Action**: Click "Approve workflow to run" in the PR checks tab
+
+### SHA Not Found
+- **Check**: Verify the SHA exists in the PR commits
+- **Action**: Use `git log --oneline` to find valid commit SHAs
+
+### Dispatch Not Triggering
+- **Check**: Ensure the slash command format is correct
+- **Action**: Use exact format: `/ok-to-test sha=<sha>`
+
+### Check Runs Not Updating
+- **Note**: The fork workflow updates the existing "E2E Tests [reusable]" check run
+- **Behavior**: The same check run is updated with new results rather than creating a new one
+
+## Security Notes
+
+- Only users with **write** permissions can trigger dispatch commands
+- The fork workflow runs in the main repository context, allowing it to update check runs
+- Manual approval is required for external PR workflows
+- External PRs are automatically detected and prevented from running tests automatically
+
+## Workflow Files
+
+- **`.github/workflows/ok-to-test.yml`** - Ok To Test - Slash command processor
+- **`.github/workflows/test-e2e.yml`** - E2E Tests - Initial PR checks
+- **`.github/workflows/test-e2e-fork.yml`** - E2E tests [fork] - Dispatch action handler
+- **`.github/workflows/e2e-tests.yml`** - E2E Tests [reusable] - Reusable workflow for actual testing
+
+## Testing Checklist
+
+- [ ] PR created with failing check-external-pr check (for external PRs)
+- [ ] Workflow approved to run (if required)
+- [ ] Slash command posted with valid SHA
+- [ ] Dispatch action triggered successfully
+- [ ] `check-external-pr` check run updated with correct conclusion