add staging deployment of documentation github pages

Author: jl4ever

.github/workflows/staging.yml

@@ -0,0 +1,66 @@
+name: Deploy Staging to GitHub Pages
+
+# This workflow deploys to procore-staging.github.io/documentation/
+#
+# Triggers:
+# 1. When any branch starting with "staging-" is pushed (e.g., staging-my-feature)
+#    → Deploys that feature branch's content to staging
+# 2. When main branch is merged/pushed
+#    → Deploys main branch's content to procore-staging.github.io
+#    → This keeps staging in sync with the latest main branch content
+#
+# Both scenarios deploy to the same staging subdomain: procore-staging.github.io
+
+on:
+  push:
+    branches:
+      - 'staging-*'  # Deploy when any branch starting with "staging-" is updated (e.g., staging-1, staging-feature)
+      - main         # Deploy main branch to procore-staging.github.io when main is merged/pushed
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages-staging"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true
+      
+      - name: Build with Jekyll (Staging)
+        run: bundle exec jekyll build --config _config.yml,_config_staging.yml
+        env:
+          JEKYLL_ENV: staging
+      
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./_site
+
+  deploy:
+    environment:
+      name: github-pages-staging
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

STAGING_SETUP.md

@@ -0,0 +1,46 @@
+# Staging Environment Setup for GitHub Pages
+
+This guide explains how to set up a staging environment for the documentation that deploys to `procore-staging.github.io/documentation`.
+
+## Feature Branch Staging Workflow
+
+Use the same repository with `staging-*` branch pattern for per-feature staging deployments:
+
+1. **Work on your feature branch** (e.g., `my-feature-change-1`)
+2. **Create a staging branch** with `staging-` prefix (e.g., `staging-my-feature-change-1`)
+3. **Push the staging branch** - the `.github/workflows/staging.yml` workflow will automatically:
+   - Detect branches matching `staging-*` pattern
+   - Build with staging configuration (`_config_staging.yml`)
+   - Deploy to `procore-staging.github.io/documentation/`
+
+**How it works:**
+- Any branch starting with `staging-` triggers the staging deployment workflow
+- Each feature can have its own staging branch: `staging-feature-name`
+- The workflow uses the staging config which sets `url: "https://procore-staging.github.io"`
+
+**Example workflow:**
+```bash
+# 1. Work on your feature
+git checkout -b my-feature-change-1
+# ... make changes ...
+
+# 2. When ready for staging, create staging branch
+git checkout -b staging-my-feature-change-1
+
+# 3. Push to trigger staging deployment
+git push origin staging-my-feature-change-1
+# → GitHub Actions automatically builds and deploys to procore-staging.github.io
+```
+
+## Main Branch Deployment to Staging
+
+When the `main` branch is merged or pushed, it will also automatically deploy to `procore-staging.github.io/documentation/`:
+
+- **Purpose**: Keeps the staging environment in sync with the latest production-ready code from `main`
+- **Trigger**: Any push or merge to the `main` branch
+- **Deployment**: Same staging subdomain (`procore-staging.github.io`) as feature branch deployments
+- **Result**: Staging always reflects the current state of `main` branch
+
+**Note**: This means `main` branch content will be available at `procore-staging.github.io/documentation/`, allowing you to test the latest production code in the staging environment before it goes to production.
+
+

_config_staging.yml

@@ -0,0 +1,11 @@
+# Staging configuration - extends _config.yml with staging-specific settings
+# Usage: bundle exec jekyll build --config _config.yml,_config_staging.yml
+# 
+# For subdomain deployment (e.g., procore-staging.github.io):
+# - Create a separate repository named "procore-staging" (or similar)
+# - Deploy from that repository's main branch
+# - GitHub Pages will automatically serve it at procore-staging.github.io
+
+baseurl: "/documentation"  # Same baseurl as production (subdomain handles staging)
+url: "https://procore-staging.github.io"  # Staging subdomain URL
+