From 6e2e63e051438e7f8f56782f7ea901252a68ff32 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 10 Mar 2026 13:17:07 -0700 Subject: [PATCH 1/4] chore(ci): add automated Surge preview deploy workflow Deploys PR previews to opentdf-docs-pr-{number}.surge.sh on open/push, posts a comment with the URL on first open, and tears down on close. Requires SURGE_LOGIN and SURGE_TOKEN repo secrets. Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/surge-preview.yaml | 62 ++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 .github/workflows/surge-preview.yaml diff --git a/.github/workflows/surge-preview.yaml b/.github/workflows/surge-preview.yaml new file mode 100644 index 00000000..a9fa3f88 --- /dev/null +++ b/.github/workflows/surge-preview.yaml @@ -0,0 +1,62 @@ +name: Surge Preview + +on: + pull_request: + types: [opened, synchronize, reopened, closed] + +jobs: + deploy-preview: + if: github.event.action != 'closed' + name: Deploy Preview + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Build website + run: npm run build + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Deploy to Surge + run: npx surge build/ https://opentdf-docs-pr-${{ github.event.number }}.surge.sh + env: + SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }} + SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }} + + - name: Comment with preview URL + if: github.event.action == 'opened' || github.event.action == 'reopened' + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: '📄 Preview deployed to https://opentdf-docs-pr-${{ github.event.number }}.surge.sh' + }) + + teardown-preview: + if: github.event.action == 'closed' + name: Teardown Preview + runs-on: ubuntu-latest + steps: + - uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Teardown Surge preview + run: npx surge teardown opentdf-docs-pr-${{ github.event.number }}.surge.sh + env: + SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }} + SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }} From 16e64e6351cf7a0b61032279545efc21790a0515 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 10 Mar 2026 13:25:59 -0700 Subject: [PATCH 2/4] chore(ci): only trigger surge preview on content changes Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/surge-preview.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/surge-preview.yaml b/.github/workflows/surge-preview.yaml index a9fa3f88..0464ffeb 100644 --- a/.github/workflows/surge-preview.yaml +++ b/.github/workflows/surge-preview.yaml @@ -3,6 +3,15 @@ name: Surge Preview on: pull_request: types: [opened, synchronize, reopened, closed] + paths: + - 'docs/**' + - 'code_samples/**' + - 'src/**' + - 'static/**' + - 'blog/**' + - 'specs/**' + - 'docusaurus.config.ts' + - 'sidebars.js' jobs: deploy-preview: From 56d171c31e5893a37133114598714bcffc3a3fa4 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 10 Mar 2026 13:26:51 -0700 Subject: [PATCH 3/4] chore(ci): add workflow_dispatch trigger for manual preview deploy/teardown Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/surge-preview.yaml | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/.github/workflows/surge-preview.yaml b/.github/workflows/surge-preview.yaml index 0464ffeb..0c1046f1 100644 --- a/.github/workflows/surge-preview.yaml +++ b/.github/workflows/surge-preview.yaml @@ -1,6 +1,15 @@ name: Surge Preview on: + workflow_dispatch: + inputs: + pr_number: + description: 'PR number (used for deploy domain: opentdf-docs-pr-{number}.surge.sh)' + required: true + teardown: + description: 'Tear down the preview instead of deploying' + type: boolean + default: false pull_request: types: [opened, synchronize, reopened, closed] paths: @@ -15,7 +24,7 @@ on: jobs: deploy-preview: - if: github.event.action != 'closed' + if: github.event.action != 'closed' && (github.event_name != 'workflow_dispatch' || inputs.teardown == false) name: Deploy Preview runs-on: ubuntu-latest permissions: @@ -38,7 +47,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Deploy to Surge - run: npx surge build/ https://opentdf-docs-pr-${{ github.event.number }}.surge.sh + run: npx surge build/ https://opentdf-docs-pr-${{ inputs.pr_number || github.event.number }}.surge.sh env: SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }} SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }} @@ -52,11 +61,11 @@ jobs: issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, - body: '📄 Preview deployed to https://opentdf-docs-pr-${{ github.event.number }}.surge.sh' + body: '📄 Preview deployed to https://opentdf-docs-pr-${{ inputs.pr_number || github.event.number }}.surge.sh' }) teardown-preview: - if: github.event.action == 'closed' + if: github.event.action == 'closed' || (github.event_name == 'workflow_dispatch' && inputs.teardown == true) name: Teardown Preview runs-on: ubuntu-latest steps: @@ -65,7 +74,7 @@ jobs: node-version: 22 - name: Teardown Surge preview - run: npx surge teardown opentdf-docs-pr-${{ github.event.number }}.surge.sh + run: npx surge teardown opentdf-docs-pr-${{ inputs.pr_number || github.event.number }}.surge.sh env: SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }} SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }} From 1fa0412910fddcd06e0c5d1a46bbee3f1dff44b8 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 10 Mar 2026 14:10:52 -0700 Subject: [PATCH 4/4] docs: update preview deployment instructions to reflect automated CI workflow Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 11 ++++------- README.md | 25 ++++--------------------- 2 files changed, 8 insertions(+), 28 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e705e637..c3ef9f87 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,16 +35,13 @@ Docs-only checks: ## Preview Deployment -After opening a PR, deploy a Surge preview so reviewers can see the changes live. Use the ticket number as the identifier. +Surge previews are deployed automatically by CI when a PR is opened or updated (for content-affecting changes). The preview URL is posted as a PR comment on first open: -```bash -npm run build -npx surge build opentdf-docs-preview-.surge.sh +``` +https://opentdf-docs-pr-.surge.sh ``` -Preview URL: `https://opentdf-docs-preview-.surge.sh/` - -A free Surge account is required — first run will prompt to sign up or log in. +To trigger a preview manually (e.g. for a PR with only config changes), use the **Surge Preview** workflow dispatch from the Actions tab, providing the PR number. ## Commit & Pull Request Guidelines diff --git a/README.md b/README.md index f23ac996..3cf87c06 100644 --- a/README.md +++ b/README.md @@ -163,32 +163,15 @@ PLATFORM_BRANCH=my-feature npm run start ### Preview Deployment -Deploy to a Surge preview domain for testing changes before merging to production. **A free Surge account is required** - you'll be prompted to sign up the first time you deploy. +Surge previews are deployed automatically by CI when a PR is opened or updated (for content-affecting changes). A comment is posted on the PR with the preview URL on first open: -**Important:** Each developer should use a unique preview domain name to avoid conflicts. Use a descriptive name based on your ticket number or feature: - -```bash -# Build the site -npm run build - -# Deploy to your unique preview URL -# Replace with your ticket number or feature name -npx surge build opentdf-docs-preview-.surge.sh ``` - -**Examples:** - -```bash -# Using ticket number -npx surge build opentdf-docs-preview-dspx-2345.surge.sh - -# Using feature description -npx surge build opentdf-docs-preview-troubleshooting-updates.surge.sh +https://opentdf-docs-pr-.surge.sh ``` -Your preview will be available at `https://opentdf-docs-preview-.surge.sh/` +The preview is torn down automatically when the PR is closed. -**Note:** The first time you deploy, Surge will prompt you to create a free account or login. +To trigger a preview manually (e.g. for a PR with only config changes), use the **Surge Preview** workflow dispatch from the Actions tab, providing the PR number. ---