From 2f58974927dc52925da920016b4e3ac342bb86d0 Mon Sep 17 00:00:00 2001 From: Mark Fulton Date: Fri, 15 May 2026 11:08:02 -0400 Subject: [PATCH 1/3] Add /stage-deploy skill for shared staging environment Simplified approach using existing staging infrastructure: - Reuses existing workflow_deploy-to-pantheon-staging.yml - Deploys to single shared helpdocs multidev environment - Creates/pushes staging/pr-{number} branches to trigger deployment - No new workflows or Pantheon changes required Commands: - /stage-deploy {pr-number-or-branch} - Push staging branch to deploy - /stage-teardown {pr-number-or-branch} - Delete staging branch URL: https://helpdocs-sumo-logic.pantheonsite.io/help/ (shared, single slot) Limitations: - Only one PR can be staged at a time (team coordination required) - Manual cleanup of staging branches needed Co-Authored-By: Claude Sonnet 4.5 --- .claude/skills/stage-deploy/SKILL.md | 83 ++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 .claude/skills/stage-deploy/SKILL.md diff --git a/.claude/skills/stage-deploy/SKILL.md b/.claude/skills/stage-deploy/SKILL.md new file mode 100644 index 0000000000..ee27d066c9 --- /dev/null +++ b/.claude/skills/stage-deploy/SKILL.md @@ -0,0 +1,83 @@ +# Stage Deploy Skill + +Deploy PR branches to the shared Pantheon staging environment for external review. + +## Purpose + +Enable external reviewers (legal, compliance, product) to preview documentation changes in a live staging environment before merge. Uses the existing `helpdocs` staging environment and `staging/**` branch workflow. + +## Usage + +### Deploy a PR to Staging + +``` +/stage-deploy {pr-number-or-branch} +``` + +**Examples:** +- `/stage-deploy 6701` +- `/stage-deploy docs-update-jira-skill-fields` + +### Remove a Staging Branch + +``` +/stage-teardown {pr-number-or-branch} +``` + +**Examples:** +- `/stage-teardown 6701` +- `/stage-teardown docs-update-jira-skill-fields` + +## How It Works + +### Deploy Flow + +1. **Resolve input to PR branch**: + - If input is numeric: look up PR and get head branch + - If input is branch name: use directly + - Validate PR exists and is open + +2. **Create/update staging branch**: + ```bash + git fetch origin {pr-branch} + git branch -f staging/pr-{number} origin/{pr-branch} + git push origin staging/pr-{number} + ``` + +3. **Existing workflow automatically triggers**: + - Push to `staging/**` triggers `workflow_deploy-to-pantheon-staging.yml` + - Workflow builds site from staging branch + - Deploys to `helpdocs` multidev environment + - Sends Slack notification on success/failure + +4. **Post PR comment** with staging URL and instructions + +### Teardown Flow + +1. **Resolve to staging branch name**: `staging/pr-{number}` or `staging/{branch-name}` + +2. **Delete staging branch**: + ```bash + git push origin --delete staging/pr-{number} + ``` + +3. **Post PR comment** confirming deletion + +## Staging Environment + +- **Single shared environment**: `https://helpdocs-sumo-logic.pantheonsite.io/help/` +- **HTTP basic auth protected**: Contact docs team for credentials +- **Only one PR at a time**: Deploying a new PR overwrites the previous deployment +- **Manual coordination required**: Team should communicate before deploying to staging + +## Limitations + +- **Single staging slot**: Only one PR can be deployed to staging at a time +- **No automatic cleanup**: Staging branches persist until explicitly deleted +- **Manual coordination**: Team must communicate to avoid overwriting each other's deployments +- **Build time**: 5-10 minutes for this large Docusaurus site +- **Shared URL**: All reviewers see the same staging environment (whatever was deployed last) + +## Implementation Notes + +This skill uses **git commands only** - no new GitHub Actions workflows required. The existing `workflow_deploy-to-pantheon-staging.yml` handles all deployment logic automatically when it detects a push to `staging/**` branches. From eb9fb73d168ba73b3c5dc6c623c73e13c90097a0 Mon Sep 17 00:00:00 2001 From: Mark Fulton Date: Fri, 15 May 2026 11:15:30 -0400 Subject: [PATCH 2/3] Add Slack notifications and conflict detection to stage-deploy skill Enhancements: - Slack notifications to #web-ops on deploy start and teardown - Include article preview URL in Slack message (detects from PR files) - Conflict detection: checks for existing staging/pr-* branches - Shows who created conflicting deployment and preview URL - Prompts user to continue/overwrite or cancel - Uses same WEBOPS_SLACK_URL as existing Pantheon workflows Coordination improvements: - Team always aware of staging changes via Slack - Direct link to article being previewed - Prevents accidental overwrites with conflict warnings - Identifies conflicting PR author for coordination --- .claude/skills/stage-deploy/SKILL.md | 155 +++++++++++++++++++++++++-- 1 file changed, 147 insertions(+), 8 deletions(-) diff --git a/.claude/skills/stage-deploy/SKILL.md b/.claude/skills/stage-deploy/SKILL.md index ee27d066c9..c3cfa6ce24 100644 --- a/.claude/skills/stage-deploy/SKILL.md +++ b/.claude/skills/stage-deploy/SKILL.md @@ -37,38 +37,126 @@ Enable external reviewers (legal, compliance, product) to preview documentation - If input is branch name: use directly - Validate PR exists and is open -2. **Create/update staging branch**: +2. **Check for conflicts**: + ```bash + # List existing staging/pr-* branches + git ls-remote --heads origin 'refs/heads/staging/pr-*' + ``` + - If staging branches exist, identify: + - Which PR number(s) from branch names + - Who created each branch (via gh pr view) + - Preview URL from the PRs + - Ask user if they want to: + - Continue and overwrite existing staging + - Cancel and coordinate with team + +3. **Detect article URL from PR files**: + ```bash + # Get files changed in PR + gh pr view {pr-number} --json files --jq '.files[].path' + + # Filter for docs markdown files + # Convert docs/path/to/article.md ā†’ /docs/path/to/article/ + # Example: docs/integrations/jira.md ā†’ /docs/integrations/jira/ + ``` + +4. **Send Slack notification (deploy starting)**: + ```bash + # Post to #web-ops via webhook + curl -X POST $WEBOPS_SLACK_URL \ + -H 'Content-Type: application/json' \ + -d '{ + "text": "šŸš€ Staging deployment started for PR #{number}", + "blocks": [{ + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Staging deployment started*\nā€¢ PR: <{pr-url}|#{number} - {title}>\nā€¢ Author: {author}\nā€¢ Staging: \nā€¢ Preview: \nā€¢ Monitor: <{actions-url}|GitHub Actions>" + } + }] + }' + ``` + + **Article URL detection**: + - If PR modifies a single doc file: include direct preview link + - If PR modifies multiple docs: list primary file or skip article link + - If PR modifies non-doc files only: omit article preview + +5. **Create/update staging branch**: ```bash git fetch origin {pr-branch} git branch -f staging/pr-{number} origin/{pr-branch} git push origin staging/pr-{number} ``` -3. **Existing workflow automatically triggers**: +6. **Existing workflow automatically triggers**: - Push to `staging/**` triggers `workflow_deploy-to-pantheon-staging.yml` - Workflow builds site from staging branch - Deploys to `helpdocs` multidev environment - - Sends Slack notification on success/failure + - Workflow sends its own Slack notification on success/failure -4. **Post PR comment** with staging URL and instructions +7. **Post PR comment** with staging URL and instructions ### Teardown Flow 1. **Resolve to staging branch name**: `staging/pr-{number}` or `staging/{branch-name}` -2. **Delete staging branch**: +2. **Verify branch exists**: + ```bash + git ls-remote --heads origin refs/heads/staging/pr-{number} + ``` + - If not found, inform user and exit gracefully + +3. **Send Slack notification (teardown)**: + ```bash + curl -X POST $WEBOPS_SLACK_URL \ + -H 'Content-Type: application/json' \ + -d '{ + "text": "šŸ—‘ļø Staging environment torn down", + "blocks": [{ + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Staging environment removed*\nā€¢ Branch: staging/pr-{number}\nā€¢ Previous deployment remains live until next deploy" + } + }] + }' + ``` + +4. **Delete staging branch**: ```bash git push origin --delete staging/pr-{number} ``` -3. **Post PR comment** confirming deletion +5. **Post PR comment** confirming deletion ## Staging Environment - **Single shared environment**: `https://helpdocs-sumo-logic.pantheonsite.io/help/` - **HTTP basic auth protected**: Contact docs team for credentials - **Only one PR at a time**: Deploying a new PR overwrites the previous deployment -- **Manual coordination required**: Team should communicate before deploying to staging +- **Automatic coordination**: Skill checks for conflicts and posts to #web-ops Slack channel + +## Conflict Detection + +Before deploying, the skill checks for existing `staging/pr-*` branches: + +```bash +# Example output if conflict detected: +āš ļø Staging environment conflict detected! + +Currently staged PR(s): +ā€¢ PR #6701 - "Update Jira skill fields" + - Author: @mafsumo + - Branch: staging/pr-6701 + - Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/ + +Do you want to: +1. Continue and overwrite (will notify team in Slack) +2. Cancel and coordinate with @mafsumo first +``` + +This prevents accidentally overwriting a colleague's staging deployment. ## Limitations @@ -78,6 +166,57 @@ Enable external reviewers (legal, compliance, product) to preview documentation - **Build time**: 5-10 minutes for this large Docusaurus site - **Shared URL**: All reviewers see the same staging environment (whatever was deployed last) +## Slack Notifications + +The skill posts to **#web-ops** Slack channel (same as existing workflows): + +**On deploy start:** +``` +šŸš€ Staging deployment started for PR #6701 +ā€¢ PR: #6701 - Update Jira skill fields +ā€¢ Author: @mafsumo +ā€¢ Staging: https://helpdocs-sumo-logic.pantheonsite.io/help/ +ā€¢ Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/docs/integrations/jira/ +ā€¢ Monitor: [GitHub Actions] +``` + +If the PR modifies multiple docs, the preview link shows the primary changed file (first .md file in docs/). + +**On teardown:** +``` +šŸ—‘ļø Staging environment torn down +ā€¢ Branch: staging/pr-6701 +ā€¢ Previous deployment remains live until next deploy +``` + +**On deploy complete:** (via existing workflow) +``` +šŸŸ¢ helpdocs staging site deployed +[Link to staging site] +``` + +This ensures the team is always aware of staging environment changes. + +## Slack Webhook + +The skill uses the same `WEBOPS_SLACK_URL` secret as existing workflows. To access: + +```bash +# Check if webhook is available (secret not exposed directly) +gh secret list --repo SumoLogic/sumologic-documentation | grep WEBOPS_SLACK_URL +``` + +If the secret is not accessible locally, the skill will: +1. Skip Slack notifications +2. Warn the user +3. Proceed with deployment (posting to #web-ops is optional, not blocking) + ## Implementation Notes -This skill uses **git commands only** - no new GitHub Actions workflows required. The existing `workflow_deploy-to-pantheon-staging.yml` handles all deployment logic automatically when it detects a push to `staging/**` branches. +This skill uses: +- **Git commands** for branch management +- **GitHub CLI (`gh`)** for PR metadata +- **curl** for Slack webhooks (optional) +- **Existing workflow** `workflow_deploy-to-pantheon-staging.yml` handles deployment + +No new GitHub Actions workflows required. From 8a17cebf336fdecdf26f3fbfaa286732f3389f29 Mon Sep 17 00:00:00 2001 From: Mark Fulton Date: Fri, 5 Jun 2026 09:08:56 -0400 Subject: [PATCH 3/3] Address Kim's review feedback on stage-deploy - Move stage-deploy from .claude/skills/ subdirectory to .claude/commands/stage-deploy.md to match command convention - Create .claude/commands/stage-teardown.md as a standalone command - Register both commands in CLAUDE.md slash commands section - Replace git branch -f with direct refspec push to avoid clobbering local branch state - Treat $WEBOPS_SLACK_URL as optional with graceful skip when not set locally Co-Authored-By: Claude Sonnet 4.6 --- .claude/commands/stage-deploy.md | 126 +++++++++++++++ .claude/commands/stage-teardown.md | 70 +++++++++ .claude/skills/stage-deploy/SKILL.md | 222 --------------------------- CLAUDE.md | 7 + 4 files changed, 203 insertions(+), 222 deletions(-) create mode 100644 .claude/commands/stage-deploy.md create mode 100644 .claude/commands/stage-teardown.md delete mode 100644 .claude/skills/stage-deploy/SKILL.md diff --git a/.claude/commands/stage-deploy.md b/.claude/commands/stage-deploy.md new file mode 100644 index 0000000000..36ed87a37b --- /dev/null +++ b/.claude/commands/stage-deploy.md @@ -0,0 +1,126 @@ +# Stage Deploy ā€” Deploy PR to Shared Staging + +Deploy a PR branch to the shared Pantheon staging environment for external review (legal, compliance, product). + +## When to use this command + +- You need an external reviewer to preview a doc change in a live environment before merge. +- A PR author or reviewer asks for a staging link. + +## Usage + +``` +/stage-deploy {pr-number-or-branch} +``` + +**Examples:** +- `/stage-deploy 6701` +- `/stage-deploy docs-update-jira-skill-fields` + +## Staging environment + +- **URL**: `https://helpdocs-sumo-logic.pantheonsite.io/help/` +- **HTTP basic auth protected**: Contact the docs team for credentials. +- **Single shared slot**: Only one PR can be staged at a time. Deploying overwrites the previous deployment. +- **Build time**: 5ā€“10 minutes after the push triggers the workflow. + +## Workflow + +### Step 1: Resolve input to PR branch + +- If input is numeric: run `gh pr view {number} --json headRefName --jq '.headRefName'` to get the branch name. Validate the PR exists and is open. +- If input is a branch name: use it directly. Look up the PR number with `gh pr list --head {branch} --json number --jq '.[0].number'`. + +You need both the branch name (for the push) and the PR number (for the staging branch name and PR comment). + +### Step 2: Check for conflicts + +```bash +git ls-remote --heads origin 'refs/heads/staging/pr-*' +``` + +If staging branches exist, identify who owns each one (`gh pr view {n}`) and ask the user: + +``` +āš ļø Staging conflict detected! + +Currently staged: PR #{n} ā€” "{title}" (author: @{handle}) +Branch: staging/pr-{n} +Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/ + +1. Continue and overwrite (notifies #web-ops if Slack is configured) +2. Cancel and coordinate with @{handle} first +``` + +### Step 3: Detect article URL from PR files + +```bash +gh pr view {pr-number} --json files --jq '.files[].path' +``` + +Convert changed doc paths to preview URLs: +- `docs/integrations/jira.md` ā†’ `/docs/integrations/jira/` + +- Single doc changed: include direct article preview link. +- Multiple docs changed: link to the first `.md` file under `docs/`, or omit. +- No doc files changed: omit article preview link entirely. + +### Step 4: Send Slack notification (optional) + +Slack notifications require `$WEBOPS_SLACK_URL` to be exported in the local environment. Check first: + +```bash +if [ -z "$WEBOPS_SLACK_URL" ]; then + echo "āš ļø WEBOPS_SLACK_URL not set ā€” skipping Slack notification. To enable, export the webhook URL: export WEBOPS_SLACK_URL=https://hooks.slack.com/..." +fi +``` + +If set, post to #web-ops: + +```bash +curl -X POST "$WEBOPS_SLACK_URL" \ + -H 'Content-Type: application/json' \ + -d '{ + "text": "šŸš€ Staging deployment started for PR #{number}", + "blocks": [{ + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Staging deployment started*\nā€¢ PR: <{pr-url}|#{number} - {title}>\nā€¢ Author: {author}\nā€¢ Staging: \nā€¢ Preview: \nā€¢ Monitor: <{actions-url}|GitHub Actions>" + } + }] + }' +``` + +If not set, skip silently and continue. + +### Step 5: Push staging branch + +```bash +git fetch origin {pr-branch} +git push origin origin/{pr-branch}:refs/heads/staging/pr-{number} +``` + +This pushes directly from the remote-tracking ref without touching local branch state. + +### Step 6: Workflow triggers automatically + +Pushing to `staging/**` triggers `workflow_deploy-to-pantheon-staging.yml`, which: +1. Builds the Docusaurus site from the staging branch. +2. Deploys to the `helpdocs` multidev environment. +3. Posts its own success/failure notification to Slack. + +### Step 7: Post PR comment + +Post a comment on the PR with: +- Staging URL +- Direct article preview link (if applicable) +- Note that the environment is shared and may be overwritten +- Link to the Actions run for build status + +## Limitations + +- **Single staging slot**: Only one PR deployed at a time. +- **No automatic cleanup**: Staging branches persist until explicitly deleted with `/stage-teardown`. +- **Slack optional**: Notifications only fire if `WEBOPS_SLACK_URL` is set locally. +- **Shared URL**: All reviewers see whatever was deployed last. diff --git a/.claude/commands/stage-teardown.md b/.claude/commands/stage-teardown.md new file mode 100644 index 0000000000..501a629b31 --- /dev/null +++ b/.claude/commands/stage-teardown.md @@ -0,0 +1,70 @@ +# Stage Teardown ā€” Remove a Staging Deployment + +Delete a staging branch to free the shared Pantheon staging slot. + +## When to use this command + +- External review is complete and the staging branch is no longer needed. +- A PR was closed or merged and the staging slot should be cleared for the next deployment. + +## Usage + +``` +/stage-teardown {pr-number-or-branch} +``` + +**Examples:** +- `/stage-teardown 6701` +- `/stage-teardown docs-update-jira-skill-fields` + +## Workflow + +### Step 1: Resolve to staging branch name + +- If input is numeric: staging branch is `staging/pr-{number}`. +- If input is a branch name: look up the PR number with `gh pr list --head {branch} --json number --jq '.[0].number'`, then use `staging/pr-{number}`. + +### Step 2: Verify the branch exists + +```bash +git ls-remote --heads origin refs/heads/staging/pr-{number} +``` + +If the branch is not found, inform the user and exit ā€” nothing to delete. + +### Step 3: Send Slack notification (optional) + +Slack notifications require `$WEBOPS_SLACK_URL` to be exported in the local environment. Check first: + +```bash +if [ -z "$WEBOPS_SLACK_URL" ]; then + echo "āš ļø WEBOPS_SLACK_URL not set ā€” skipping Slack notification." +fi +``` + +If set, post to #web-ops: + +```bash +curl -X POST "$WEBOPS_SLACK_URL" \ + -H 'Content-Type: application/json' \ + -d '{ + "text": "šŸ—‘ļø Staging environment torn down", + "blocks": [{ + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Staging environment removed*\nā€¢ Branch: staging/pr-{number}\nā€¢ Note: previous deployment remains live at the staging URL until the next deployment overwrites it" + } + }] + }' +``` + +### Step 4: Delete the staging branch + +```bash +git push origin --delete staging/pr-{number} +``` + +### Step 5: Post PR comment + +Post a comment on the PR confirming the staging branch was deleted and noting that the staging URL may still serve the old build until the next deployment. diff --git a/.claude/skills/stage-deploy/SKILL.md b/.claude/skills/stage-deploy/SKILL.md deleted file mode 100644 index c3cfa6ce24..0000000000 --- a/.claude/skills/stage-deploy/SKILL.md +++ /dev/null @@ -1,222 +0,0 @@ -# Stage Deploy Skill - -Deploy PR branches to the shared Pantheon staging environment for external review. - -## Purpose - -Enable external reviewers (legal, compliance, product) to preview documentation changes in a live staging environment before merge. Uses the existing `helpdocs` staging environment and `staging/**` branch workflow. - -## Usage - -### Deploy a PR to Staging - -``` -/stage-deploy {pr-number-or-branch} -``` - -**Examples:** -- `/stage-deploy 6701` -- `/stage-deploy docs-update-jira-skill-fields` - -### Remove a Staging Branch - -``` -/stage-teardown {pr-number-or-branch} -``` - -**Examples:** -- `/stage-teardown 6701` -- `/stage-teardown docs-update-jira-skill-fields` - -## How It Works - -### Deploy Flow - -1. **Resolve input to PR branch**: - - If input is numeric: look up PR and get head branch - - If input is branch name: use directly - - Validate PR exists and is open - -2. **Check for conflicts**: - ```bash - # List existing staging/pr-* branches - git ls-remote --heads origin 'refs/heads/staging/pr-*' - ``` - - If staging branches exist, identify: - - Which PR number(s) from branch names - - Who created each branch (via gh pr view) - - Preview URL from the PRs - - Ask user if they want to: - - Continue and overwrite existing staging - - Cancel and coordinate with team - -3. **Detect article URL from PR files**: - ```bash - # Get files changed in PR - gh pr view {pr-number} --json files --jq '.files[].path' - - # Filter for docs markdown files - # Convert docs/path/to/article.md ā†’ /docs/path/to/article/ - # Example: docs/integrations/jira.md ā†’ /docs/integrations/jira/ - ``` - -4. **Send Slack notification (deploy starting)**: - ```bash - # Post to #web-ops via webhook - curl -X POST $WEBOPS_SLACK_URL \ - -H 'Content-Type: application/json' \ - -d '{ - "text": "šŸš€ Staging deployment started for PR #{number}", - "blocks": [{ - "type": "section", - "text": { - "type": "mrkdwn", - "text": "*Staging deployment started*\nā€¢ PR: <{pr-url}|#{number} - {title}>\nā€¢ Author: {author}\nā€¢ Staging: \nā€¢ Preview: \nā€¢ Monitor: <{actions-url}|GitHub Actions>" - } - }] - }' - ``` - - **Article URL detection**: - - If PR modifies a single doc file: include direct preview link - - If PR modifies multiple docs: list primary file or skip article link - - If PR modifies non-doc files only: omit article preview - -5. **Create/update staging branch**: - ```bash - git fetch origin {pr-branch} - git branch -f staging/pr-{number} origin/{pr-branch} - git push origin staging/pr-{number} - ``` - -6. **Existing workflow automatically triggers**: - - Push to `staging/**` triggers `workflow_deploy-to-pantheon-staging.yml` - - Workflow builds site from staging branch - - Deploys to `helpdocs` multidev environment - - Workflow sends its own Slack notification on success/failure - -7. **Post PR comment** with staging URL and instructions - -### Teardown Flow - -1. **Resolve to staging branch name**: `staging/pr-{number}` or `staging/{branch-name}` - -2. **Verify branch exists**: - ```bash - git ls-remote --heads origin refs/heads/staging/pr-{number} - ``` - - If not found, inform user and exit gracefully - -3. **Send Slack notification (teardown)**: - ```bash - curl -X POST $WEBOPS_SLACK_URL \ - -H 'Content-Type: application/json' \ - -d '{ - "text": "šŸ—‘ļø Staging environment torn down", - "blocks": [{ - "type": "section", - "text": { - "type": "mrkdwn", - "text": "*Staging environment removed*\nā€¢ Branch: staging/pr-{number}\nā€¢ Previous deployment remains live until next deploy" - } - }] - }' - ``` - -4. **Delete staging branch**: - ```bash - git push origin --delete staging/pr-{number} - ``` - -5. **Post PR comment** confirming deletion - -## Staging Environment - -- **Single shared environment**: `https://helpdocs-sumo-logic.pantheonsite.io/help/` -- **HTTP basic auth protected**: Contact docs team for credentials -- **Only one PR at a time**: Deploying a new PR overwrites the previous deployment -- **Automatic coordination**: Skill checks for conflicts and posts to #web-ops Slack channel - -## Conflict Detection - -Before deploying, the skill checks for existing `staging/pr-*` branches: - -```bash -# Example output if conflict detected: -āš ļø Staging environment conflict detected! - -Currently staged PR(s): -ā€¢ PR #6701 - "Update Jira skill fields" - - Author: @mafsumo - - Branch: staging/pr-6701 - - Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/ - -Do you want to: -1. Continue and overwrite (will notify team in Slack) -2. Cancel and coordinate with @mafsumo first -``` - -This prevents accidentally overwriting a colleague's staging deployment. - -## Limitations - -- **Single staging slot**: Only one PR can be deployed to staging at a time -- **No automatic cleanup**: Staging branches persist until explicitly deleted -- **Manual coordination**: Team must communicate to avoid overwriting each other's deployments -- **Build time**: 5-10 minutes for this large Docusaurus site -- **Shared URL**: All reviewers see the same staging environment (whatever was deployed last) - -## Slack Notifications - -The skill posts to **#web-ops** Slack channel (same as existing workflows): - -**On deploy start:** -``` -šŸš€ Staging deployment started for PR #6701 -ā€¢ PR: #6701 - Update Jira skill fields -ā€¢ Author: @mafsumo -ā€¢ Staging: https://helpdocs-sumo-logic.pantheonsite.io/help/ -ā€¢ Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/docs/integrations/jira/ -ā€¢ Monitor: [GitHub Actions] -``` - -If the PR modifies multiple docs, the preview link shows the primary changed file (first .md file in docs/). - -**On teardown:** -``` -šŸ—‘ļø Staging environment torn down -ā€¢ Branch: staging/pr-6701 -ā€¢ Previous deployment remains live until next deploy -``` - -**On deploy complete:** (via existing workflow) -``` -šŸŸ¢ helpdocs staging site deployed -[Link to staging site] -``` - -This ensures the team is always aware of staging environment changes. - -## Slack Webhook - -The skill uses the same `WEBOPS_SLACK_URL` secret as existing workflows. To access: - -```bash -# Check if webhook is available (secret not exposed directly) -gh secret list --repo SumoLogic/sumologic-documentation | grep WEBOPS_SLACK_URL -``` - -If the secret is not accessible locally, the skill will: -1. Skip Slack notifications -2. Warn the user -3. Proceed with deployment (posting to #web-ops is optional, not blocking) - -## Implementation Notes - -This skill uses: -- **Git commands** for branch management -- **GitHub CLI (`gh`)** for PR metadata -- **curl** for Slack webhooks (optional) -- **Existing workflow** `workflow_deploy-to-pantheon-staging.yml` handles deployment - -No new GitHub Actions workflows required. diff --git a/CLAUDE.md b/CLAUDE.md index b2d98bcf07..b25a8e4a30 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,6 +103,13 @@ When a user asks "what can I do", "what commands are available", or similar, sha |---------|-------------| | `/remove-doc` | Safely deprecate or move a doc with redirects | +**Staging** + +| Command | What it does | +|---------|-------------| +| `/stage-deploy` | Deploy a PR branch to the shared Pantheon staging environment for external review | +| `/stage-teardown` | Delete a staging branch and free the shared staging slot | + ### Which audit command to use Run both for a thorough pre-PR check ā€” they cover different things: