@worksafevictoria/wcl7.5 1.19.0-beta.7 → 1.19.0-beta.8

package/docs/AZURE_DEVOPS_TO_GITHUB_ACTIONS_MIGRATION_beta_pipeline.md

@@ -0,0 +1,778 @@
+# Azure DevOps to GitHub Actions Migration: Beta Release Pipeline
+
+## Overview
+This document details the migration of the beta release pipeline from Azure DevOps to GitHub Actions. The original pipeline (`ci/release/beta.yml`) was converted to GitHub Actions workflow (`.github/workflows/beta_exact.yml`) while preserving all original commands and structure.
+
+## Table of Contents
+- [Original Pipeline](#original-pipeline)
+- [Converted Pipeline](#converted-pipeline)
+- [Migration Steps](#migration-steps)
+- [Key Changes](#key-changes)
+- [Pipeline Structure](#pipeline-structure)
+
+
+---
+
+## Original Pipeline
+
+**Location**: `ci/release/beta.yml`
+
+```yaml
+#######################################################
+# Original Author: Yavisht Katgara
+# Email: WSV-DigitalOperations@worksafetac.onmicrosoft.com
+# Project: Worksafe Public Website - Front End
+# Description: Publish beta release to NPM
+#######################################################
+
+trigger:
+  branches:
+    include:
+      - beta
+pr: none
+
+variables:
+  - group: Public Websites - Front End
+
+stages:
+  - stage: publish_npm_beta
+    jobs:
+      - deployment: publish_to_npm_beta
+        displayName: Publish to NPM - Beta
+        environment: Public Websites - Front End
+        strategy:
+          runOnce:
+            deploy:
+              steps:
+                - checkout: self
+                - task: NodeTool@0
+                  displayName: Use Node 20.x
+                  inputs:
+                    versionSpec: 20.x
+
+                - script: |
+                    set -e
+                    npm i -g husky
+                    npm i -g pinst
+                    npx semantic-release
+                  displayName: 'NPM Publish Beta Release'
+                  env:
+                    GITHUB_TOKEN: $(GH_TOKEN)
+                    NPM_TOKEN: $(NPM_TOKEN)
+
+  - stage: publish_storybook
+    jobs:
+      - job: publish_storybook_website
+        displayName: Publish Storybook
+        steps:
+          - checkout: self
+          - task: NodeTool@0
+            displayName: Use Node 18.x
+            inputs:
+              versionSpec: 18.x
+
+          - task: CmdLine@2
+            displayName: Setup Git Repo
+            inputs:
+              script: |
+                git remote remove origin
+                git config --global user.email "webupdates@worksafe.vic.gov.au"
+                git config --global user.name "worksafedigital"
+                git remote add origin https://$(GH_TOKEN)@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7
+                git fetch origin
+          - task: CmdLine@2
+            displayName: Install dependencies
+            inputs:
+              script: 'yarn'
+
+          - task: CmdLine@2
+            displayName: Deploy to GitHub Pages
+            inputs:
+              script: 'yarn deploy'
+
+```
+
+### Key Features
+- **Two-stage pipeline**: NPM publish then Storybook deployment
+- **Trigger**: On push to `beta` branch
+- **NPM Publishing**: 
+- **Storybook Deployment**: 
+- **Tokens**: Uses GH_TOKEN and NPM_TOKEN for authentication
+
+---
+
+## Converted Pipeline
+
+**Location**: `.github/workflows/beta_exact.yml`
+
+```yaml
+#######################################################
+# POCX
+#######################################################
+
+name: Beta Release
+
+on:
+  push:
+    branches: [beta]
+
+jobs:
+  publish_npm_beta:
+    name: Publish to NPM - Beta
+    runs-on: ubuntu-latest
+    environment: Public Websites - Front End
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Use Node 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+
+      - name: Configure Git for semantic-release
+        run: |
+          git remote set-url origin https://${{github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git
+          git config --global user.email "webupdates@worksafe.vic.gov.au"
+          git config --global user.name "worksafedigital"
+
+
+      - name: NPM Publish Beta Release
+        run: |
+          set -e
+          npm i -g husky
+          npm i -g pinst
+          npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ github.token}}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish_storybook:
+    name: Publish Storybook
+    runs-on: ubuntu-latest
+    needs: publish_npm_beta
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Use Node 18.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Build Storybook
+        run: yarn build-storybook
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./storybook-static
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+```
+
+### Key Features
+- **Two jobs**: Sequential pipeline (NPM publish then Storybook deployment)
+- **Trigger**: On push to `beta` branch
+- **NPM Publishing**: 
+- **Storybook Deployment**:
+- **GitHub Pages**: Uses official GitHub Actions for Pages deployment
+- **Tokens**: Uses `${{ github.token }}` and `${{ secrets.NPM_TOKEN }}`
+
+---
+
+## Migration Steps
+
+### Step 1: Convert Trigger
+**Azure DevOps**:
+```yaml
+trigger: 
+  branches:
+    include:
+      - beta
+pr: none
+```
+
+**GitHub Actions**:
+```yaml
+on:
+  push:
+    branches: [beta]
+```
+
+### Step 2: Convert Stages to Jobs
+**Azure DevOps** (stages):
+```yaml
+stages:
+  - stage: publish_npm_beta
+    jobs:
+      - deployment: publish_to_npm_beta
+```
+
+**GitHub Actions** (jobs):
+```yaml
+jobs:
+  publish_npm_beta:
+```
+
+### Step 3: Add Job Dependencies
+**Azure DevOps**: Stages run sequentially by default
+
+**GitHub Actions**: Explicit `needs` dependency
+```yaml
+publish_storybook:
+  needs: publish_npm_beta
+```
+
+### Step 4: Configure Git for Semantic Release
+**Azure DevOps**: Uses environment variable in git remote
+```yaml
+git remote add origin https://$(GH_TOKEN)@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7
+```
+
+**GitHub Actions**: Configure git remote URL
+```yaml
+- name: Configure Git for semantic-release
+  run: |
+    git remote set-url origin https://${{ github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git
+    git config --global user.email "webupdates@worksafe.vic.gov.au"
+    git config --global user.name "worksafedigital"
+```
+
+### Step 5: Update Storybook Deployment
+**Azure DevOps**: Manual git-based deployment via `yarn deploy`
+```yaml
+- task: CmdLine@2
+  displayName: Deploy to GitHub Pages
+  inputs:
+    script: 'yarn deploy'
+```
+
+**GitHub Actions**: Use official GitHub Pages actions
+```yaml
+- name: Build Storybook
+  run: yarn build-storybook
+
+- name: Upload Pages artifact
+  uses: actions/upload-pages-artifact@v3
+  with:
+    path: ./storybook-static
+
+- name: Deploy to GitHub Pages
+  id: deployment
+  uses: actions/deploy-pages@v4
+```
+
+### Step 6: Add Permissions
+**GitHub Actions**: Explicit permissions required for Pages
+```yaml
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+```
+
+---
+
+## Key Changes
+
+### 1. Trigger Syntax
+**Azure DevOps**:
+```yaml
+trigger: 
+  branches:
+    include:
+      - beta
+pr: none
+```
+
+**GitHub Actions**:
+```yaml
+on:
+  push:
+    branches: [beta]
+```
+
+### 2. Stages to Jobs
+**Azure DevOps**: Uses `stages` with `deployment` job type
+```yaml
+stages:
+  - stage: publish_npm_beta
+    jobs:
+      - deployment: publish_to_npm_beta
+```
+
+**GitHub Actions**: Uses `jobs` with explicit `needs` for sequencing
+```yaml
+jobs:
+  publish_npm_beta:
+    ...
+
+  publish_storybook:
+    needs: publish_npm_beta
+```
+
+### 3. Environment Syntax
+**Azure DevOps**:
+```yaml
+environment: Public Websites - Front End
+```
+
+**GitHub Actions**:
+```yaml
+environment: Public Websites - Front End
+# OR for Pages:
+environment:
+  name: github-pages
+  url: ${{ steps.deployment.outputs.page_url }}
+```
+
+### 4. Git Configuration
+**Azure DevOps**:
+```yaml
+- task: CmdLine@2
+  displayName: Setup Git Repo
+  inputs:
+    script: |
+      git remote remove origin
+      git config --global user.email "webupdates@worksafe.vic.gov.au"
+      git config --global user.name "worksafedigital"
+      git remote add origin https://$(GH_TOKEN)@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7
+      git fetch origin
+```
+
+**GitHub Actions**:
+```yaml
+- name: Configure Git for semantic-release
+  run: |
+    git remote set-url origin https://${{ github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git
+    git config --global user.email "webupdates@worksafe.vic.gov.au"
+    git config --global user.name "worksafedigital"
+```
+
+### 5. Environment Variables
+**Azure DevOps**:
+```yaml
+env:
+  GITHUB_TOKEN: $(GH_TOKEN)
+  NPM_TOKEN: $(NPM_TOKEN)
+```
+
+**GitHub Actions**:
+```yaml
+env:
+  GITHUB_TOKEN: ${{ github.token }}
+  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### 6. Storybook Deployment
+**Azure DevOps** (manual deployment):
+```yaml
+- task: CmdLine@2
+  displayName: Deploy to GitHub Pages
+  inputs:
+    script: 'yarn deploy'
+```
+
+**GitHub Actions** (official actions):
+```yaml
+- name: Build Storybook
+  run: yarn build-storybook
+
+- name: Upload Pages artifact
+  uses: actions/upload-pages-artifact@v3
+  with:
+    path: ./storybook-static
+
+- name: Deploy to GitHub Pages
+  uses: actions/deploy-pages@v4
+```
+
+---
+
+## Pipeline Structure
+
+### Azure DevOps Structure
+```
+Stages (Sequential)
+  ├── Stage: publish_npm_beta
+  │     └── Job: deployment (publish_to_npm_beta)
+  │           ├── Checkout
+  │           ├── Setup Node 20.x
+  │           ├── Install packages
+  │           └── Run semantic-release
+  │
+  └── Stage: publish_storybook
+        └── Job: publish_storybook_website
+              ├── Checkout
+              ├── Setup Node 18.x
+              ├── Setup Git Repo
+              ├── Install dependencies
+              └── Deploy to GitHub Pages
+```
+
+### GitHub Actions Structure
+```
+Jobs (with dependencies)
+  ├── Job: publish_npm_beta
+  │     ├── Checkout
+  │     ├── Setup Node 20.x
+  │     ├── Configure Git
+  │     └── Run semantic-release
+  │
+  └── Job: publish_storybook (needs: publish_npm_beta)
+        ├── Checkout
+        ├── Setup Node 18.x
+        ├── Install dependencies
+        ├── Build Storybook
+        ├── Upload Pages artifact
+        └── Deploy to GitHub Pages
+```
+
+
+---
+
+## Errors Encountered and Solutions
+
+### Error 1: Git Authentication Required
+**Error Message**:
+```
+fatal: could not read Username for 'https://github.com': No such device or address
+Error: Process completed with exit code 128.
+```
+
+**Context**: Git operations requiring authentication failed when semantic-release tried to push tags or create releases.
+
+**Solution**: Configure git remote URL with token authentication
+```yaml
+- name: Configure Git for semantic-release
+  run: |
+    git remote set-url origin https://${{ github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git
+    git config --global user.email "webupdates@worksafe.vic.gov.au"
+    git config --global user.name "worksafedigital"
+```
+
+**Key Changes**:
+- Used `${{ github.token }}` instead of `${{ secrets.GH_TOKEN }}`
+- Changed from `git remote add` to `git remote set-url`
+- Configured git user before semantic-release runs
+
+---
+
+### Error 2: NPM Token Not Available
+**Error Message**:
+```
+npm ERR! code E401
+npm ERR! Unable to authenticate, need: Basic realm="npmjs.org"
+```
+
+**Context**: NPM publishing failed due to missing authentication token.
+
+**Solution**: Added NPM_TOKEN to environment variables
+```yaml
+- name: NPM Publish Beta Release
+  run: |
+    set -e
+    npm i -g husky
+    npm i -g pinst
+    npx semantic-release
+  env:
+    GITHUB_TOKEN: ${{ github.token }}
+    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+**Configuration Required**:
+1. Go to GitHub repository → Settings → Secrets and variables → Actions
+2. Add new repository secret
+3. Name: `NPM_TOKEN`
+4. Value: Your NPM access token
+
+**Alternative**: Configure NPM Trusted Publisher (had some issues with error)
+- Go to npmjs.com → Access Tokens → Trusted Publishers
+- Add publisher with GitHub repository details
+- ![NPM Trusted Publisher](./assets/trusted.PNG)
+- ![Allow Actios](./assets/allow.PNG)
+- ![Configure github-pages](./assets/github-pages-config.PNG) 
+- ![New environment](./assets/environments.PNG)
+- ![GitHub Pages](./assets/github-pages.PNG)
+- ![GitHub Pages](./assets/secrets-and-variables.PNG)
+---
+
+### Error 3: GitHub Pages Deployment Permissions
+**Error Message**:
+```
+Error: Resource not accessible by integration
+Error: Actions deploy step failed with error: The deploy step is not enabled. Please enable it in your repository settings.
+```
+
+**Context**: GitHub Actions couldn't deploy to Pages due to missing permissions.
+
+**Solution**: Added explicit permissions for Pages deployment
+```yaml
+publish_storybook:
+  permissions:
+    contents: read
+    pages: write
+    id-token: write  # Required for OIDC authentication
+```
+
+**Additional Requirements**:
+1. Enable GitHub Pages in repository settings
+2. Select "GitHub Actions" as the deployment source
+3. Verify workflow has proper permissions
+
+---
+
+### Error 4: Storybook Build Path Not Found
+**Error Message**:
+```
+Error: No such file or directory: ./storybook-static
+Error: Upload Pages artifact failed with error
+```
+
+**Context**: Upload action couldn't find the Storybook build output.
+
+**Solution**: Ensure Storybook builds before upload step
+```yaml
+- name: Build Storybook
+  run: yarn build-storybook
+
+- name: Upload Pages artifact
+  uses: actions/upload-pages-artifact@v3
+  with:
+    path: ./storybook-static
+```
+
+**Key Points**:
+- Build step must complete before upload step
+- Verify output directory matches configured path
+- Check `package.json` build-storybook script
+
+---
+
+### Error 5: Actions Blocked by Enterprise Policy
+**Error Message**:
+```
+The actions actions/deploy-pages@v4 are not allowed in WorkSafeVictoria/wsv-websites-wcl-sb7 because all actions must be from a repository owned by your enterprise.
+```
+
+**Context**: Enterprise security policy blocked GitHub's own actions.
+
+**Solution**: Updated GitHub repository settings
+1. Repository → Settings → Actions → General
+2. Select: "Allow select actions and reusable workflows"
+3. Enable: "Allow actions created by GitHub"
+4. Enable: "Allow actions created by verified creators"
+
+**Alternative (if settings unavailable)**: Use manual deployment
+```yaml
+- name: Deploy to GitHub Pages
+  run: |
+    git remote set-url origin https://${{ github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git
+    yarn deploy
+```
+
+**Note**: After enabling actions, reverted to using official GitHub Pages actions.
+
+---
+
+### Error 6: Job Dependency Not Running
+**Error Message**:
+```
+Job 'publish_storybook' was skipped due to 'publish_npm_beta' being skipped or failing
+```
+
+**Context**: The second job failed to run even though the first job completed.
+
+**Root Cause**: Missing `needs` configuration or job failure.
+
+**Solution**: Verify job dependencies
+```yaml
+publish_storybook:
+  needs: publish_npm_beta  # Explicitly declare dependency
+```
+
+**Additional Checks**:
+- Ensure first job doesn't have `if: failure()` condition
+- Verify first job completes successfully
+- Check workflow has proper permissions
+
+---
+
+### Error 7: Environment Not Found
+**Error Message**:
+```
+Environment 'Public Websites - Front End' does not exist
+```
+
+**Context**: GitHub Actions couldn't find the configured environment.
+
+**Solution**: Create environment in repository settings
+1. Repository → Settings → Environments
+2. Click "New environment"
+3. Name: `Public Websites - Front End`
+4. Configure protection rules if needed
+5. Add environment-specific secrets if required
+
+**Configuration**:
+- Environment name must match exactly (case-sensitive)
+- Can add reviewers for manual approval
+- Can set deployment branches
+
+---
+
+## Common Migration Issues and Solutions
+
+### Issue 1: Token Variables Not Accessible
+**Problem**: Azure DevOps uses `$(GH_TOKEN)` while GitHub Actions uses different syntax.
+
+**Solution**: Use `${{ github.token }}` for auto-provided GitHub token.
+
+### Issue 2: Deployment Strategy Not Available
+**Problem**: Azure DevOps has `deployment` job type with strategies, GitHub Actions doesn't.
+
+**Solution**: Use regular jobs with environment configuration.
+
+### Issue 3: Manual Git Operations
+**Problem**: Original pipeline had manual git operations for deployment.
+
+**Solution**: Use official GitHub Pages actions instead of manual git operations.
+
+### Issue 4: Stage vs Job Sequencing
+**Problem**: Azure DevOps stages run sequentially by default.
+
+**Solution**: Use `needs` in GitHub Actions to control job execution order.
+
+---
+
+## Summary
+
+### What Changed
+✅ Trigger syntax (Azure DevOps → GitHub Actions)  
+✅ Stages converted to jobs with dependencies  
+✅ Environment configuration updated  
+✅ Git configuration approach changed  
+✅ Storybook deployment method updated  
+✅ Permissions explicitly defined  
+✅ Environment variables syntax updated  
+
+### What Stayed the Same
+✅ All original commands  
+✅ Job and step names  
+✅ Node versions (20.x for NPM, 18.x for Storybook)  
+✅ Two-stage sequential execution  
+✅ Environment names  
+✅ User email and name configuration  
+
+### Key Differences
+
+1. **Pipeline Structure**
+   - Azure DevOps: Uses `stages` with automatic sequencing
+   - GitHub Actions: Uses `jobs` with explicit `needs` for sequencing
+
+2. **Deployment Method**
+   - Azure DevOps: Uses `yarn deploy` with manual git operations
+   - GitHub Actions: Uses official GitHub Pages actions with artifact upload
+
+3. **Git Configuration**
+   - Azure DevOps: Configured in separate job step
+   - GitHub Actions: Configured in single step before semantic-release
+
+4. **Environment Protection**
+   - Azure DevOps: Uses variable groups and environments
+   - GitHub Actions: Uses repository environments with protection rules
+
+---
+
+## Configuration Required
+
+### GitHub Repository Settings
+
+1. **Environments**: Create "Public Websites - Front End" environment
+   - Settings → Environments → New environment
+   - Configure protection rules if needed
+
+2. **Secrets**: Add `NPM_TOKEN` secret
+   - Settings → Secrets and variables → Actions → New repository secret
+   - Name: `NPM_TOKEN`
+   - Value: Your NPM token
+
+3. **Pages**: Enable GitHub Pages
+   - Settings → Pages
+   - Source: GitHub Actions
+
+### NPM Trusted Publisher (Alternative)
+Instead of `NPM_TOKEN` secret, configure NPM Trusted Publisher:
+1. Go to NPM → Access Tokens → Trusted Publishers
+2. Add publisher:
+   - Publisher Name: `@worksafevictoria`
+   - GitHub Owner: `WorkSafeVictoria`
+   - GitHub Repository: `wsv-websites-wcl-sb7`
+   - Workflow Name: `Beta Release`
+
+---
+
+## Testing
+
+### Test on Feature Branch
+```yaml
+on:
+  push:
+    branches: [poc/test-github-actions-beta-release]
+```
+
+### Verify Steps
+1. ✓ Job `publish_npm_beta` completes successfully
+2. ✓ NPM package published to registry
+3. ✓ Job `publish_storybook` runs after NPM job
+4. ✓ Storybook builds successfully
+5. ✓ Storybook deployed to GitHub Pages
+6. ✓ Pages accessible at published URL
+
+### Production Settings
+Change trigger to production branch:
+```yaml
+on:
+  push:
+    branches: [beta]
+```
+
+---
+
+## References
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Semantic Release Documentation](https://semantic-release.gitbook.io/)
+- [GitHub Pages Actions](https://github.com/actions/deploy-pages)
+- [Original Pipeline](ci/release/beta.yml)
+- [Converted Pipeline](.github/workflows/beta_exact.yml)
+- [Related Migration Doc](AZURE_DEVOPS_TO_GITHUB_ACTIONS_MIGRATION.md)
+
+---
+
+## Revision History
+
+- **2025-12-10**: Initial migration document created
+- **Status**: Beta release pipeline successfully migrated and tested

package/docs/AZURE_DEVOPS_TO_GITHUB_ACTIONS_MIGRATION_build_validation_pipeline.md

@@ -0,0 +1,455 @@
+# Azure DevOps to GitHub Actions Migration: Build Validation Pipeline
+
+## Overview
+This document details the migration of the build validation pipeline from Azure DevOps to GitHub Actions. The original pipeline (`ci/build/build_validation.yml`) was converted to GitHub Actions workflow (`.github/workflows/build_validation_exact.yml`) while preserving all original commands and structure.
+
+## Table of Contents
+- [Original Pipeline](#original-pipeline)
+- [Converted Pipeline](#converted-pipeline)
+- [Migration Steps](#migration-steps)
+- [Errors Encountered and Solutions](#errors-encountered-and-solutions)
+- [Key Changes](#key-changes)
+- [Best Practices](#best-practices)
+
+---
+
+## Original Pipeline
+
+**Location**: `ci/build/build_validation.yml`
+
+```yaml
+########################################################
+# Author: Yavisht Katgara
+# Email: yavisht_katgara@worksafe.vic.gov.au
+# Project: Worksafe Public Website - Front End
+# Description: Build Validation for Pull Requests
+########################################################
+trigger: none
+
+pr:
+  autoCancel: true
+  drafts: false
+  branches:
+    include:
+      - master
+      - beta
+
+variables:
+  - group: Public Websites - Front End
+
+jobs:
+  - job: Build_Test_Dryrun
+    displayName: Build - Test - DryRun
+    pool:
+      vmImage: ubuntu-latest
+    steps:
+      - checkout: self
+        fetchTags: true
+      - task: NodeTool@0
+        displayName: Use Node 18.x
+        inputs:
+          versionSpec: 18.x
+      - task: CmdLine@2
+        displayName: Install
+        inputs:
+          script: |
+            set -e
+            npm i -g husky
+            npm i -g pinst
+            yarn install
+      - task: CmdLine@2
+        displayName: Build
+        inputs:
+          script: yarn build-storybook
+      - task: CmdLine@2
+        displayName: Unit Test
+        inputs:
+          script: yarn test
+      - script: 'npm run dryrun'
+        displayName: 'Perform Dry Run'
+        env:
+          GITHUB_TOKEN: $(GH_TOKEN)
+          NPM_TOKEN: $(NPM_TOKEN)
+
+```
+
+### Key Features
+- Triggered on Pull Requests to `master` and `beta` branches
+- Runs on `ubuntu-latest` VM
+- Installs global packages (husky, pinst)
+- Runs build, unit tests, and semantic-release dry-run
+- Uses environment variables for GITHUB_TOKEN and NPM_TOKEN
+
+---
+
+## Converted Pipeline
+
+**Location**: `.github/workflows/build_validation_exact.yml`
+
+```yaml
+########################################################
+#POC
+########################################################
+
+name: Build Validation
+
+on:
+  pull_request:
+    branches: [master,beta]
+    types: [opened, synchronize, reopened]
+
+jobs:
+  Build_Test_Dryrun:
+    name: Build - Test - DryRun
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Use Node 18.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+
+      - name: Install
+        run: |
+          set -e
+          npm i -g husky
+          npm i -g pinst
+          yarn install
+
+      - name: Build
+        run: yarn build-storybook
+
+      - name: Unit Test
+        run: yarn test
+
+      - name: Perform Dry Run
+        run: npm run dryrun
+
+```
+
+### Key Features
+- Triggered on Pull Requests to `master` and `beta` branches
+- Runs on `ubuntu-latest` runner
+- Same commands as original Azure DevOps pipeline
+- No manual token configuration required
+- Uses GitHub Actions official actions
+
+---
+
+## Migration Steps
+
+### Step 1: Initial Conversion
+Converted the basic structure:
+- Azure DevOps `trigger` → GitHub Actions `on`
+- Azure DevOps `jobs` → GitHub Actions `jobs`
+- Azure DevOps `pool: vmImage` → GitHub Actions `runs-on`
+- Azure DevOps `checkout: self` → GitHub Actions `actions/checkout@v4`
+- Azure DevOps `NodeTool@0` → GitHub Actions `actions/setup-node@v4`
+- Azure DevOps `CmdLine@2` → GitHub Actions `run:`
+
+### Step 2: Environment Variables Removal
+Removed unnecessary environment variables:
+- **GITHUB_TOKEN**: Not needed in GitHub Actions (auto-provided)
+- **NPM_TOKEN**: Using NPM Trusted Publisher instead
+
+### Step 3: Token Authentication
+Removed token dependencies since GitHub Actions automatically provides authentication.
+
+---
+
+## Errors Encountered and Solutions
+
+### Error 1: Actions from Marketplace Blocked
+**Error Message**:
+```
+The actions actions/checkout@v4 and actions/setup-node@v4 are not allowed in WorkSafeVictoria/wsv-websites-wcl-sb7 because all actions must be from a repository owned by your enterprise.
+```
+
+**Solution 1 (Initial)**: Used manual git clone and Node.js installation
+```yaml
+- name: Checkout code
+  run: |
+    git clone https://${{ github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git .
+
+- name: Setup Node 18.x
+  run: |
+    curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+    sudo apt-get install -y nodejs
+```
+
+**Solution 2 (Final)**: Updated GitHub repository settings to allow GitHub's own actions
+- **GitHub Settings**: Repository → Settings → Actions → Allow select actions and reusable workflows
+- **Selected**: Allow actions created by GitHub
+- **Result**: Can now use `actions/checkout@v4` and `actions/setup-node@v4`
+
+---
+
+### Error 2: Git Repository Not Found
+**Error Message**:
+```
+fatal: not a git repository (or any of the parent directories): .git
+Error: Process completed with exit code 128.
+```
+
+**Solution**: Added git clone command to checkout the repository
+```yaml
+- name: Checkout code
+  run: |
+    git clone https://github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git .
+```
+
+**Root Cause**: GitHub Actions runner doesn't automatically checkout code when not using `actions/checkout`.
+
+---
+
+### Error 3: Authentication Required for Private Repository
+**Error Message**:
+```
+fatal: could not read Username for 'https://github.com': No such device or address
+Error: Process completed with exit code 128.
+```
+
+**Solution**: Added GitHub token to git clone command
+```yaml
+- name: Checkout code
+  run: |
+    git clone https://${{ github.token }}@github.com/WorkSafeVictoria/wsv-websites-wcl-sb7.git .
+```
+
+**Root Cause**: Repository is private and requires authentication.
+
+---
+
+### Error 4: Yarn Lock File Not Found
+**Error Message**:
+```
+Error: Dependencies lock file is not found in /home/runner/work/wsv-websites-wcl-sb7/wsv-websites-wcl-sb7. Supported file patterns: yarn.lock
+```
+
+**Solution**: Removed yarn caching from setup-node action
+```yaml
+- name: Use Node 18.x
+  uses: actions/setup-node@v4
+  with:
+    node-version: '18'
+    # cache: 'yarn'  # Removed - no yarn.lock file
+```
+
+**Root Cause**: The repository doesn't have a `yarn.lock` file, so yarn caching fails.
+
+**Note**: After updating GitHub settings to allow official actions, we reverted to using `actions/checkout@v4` and `actions/setup-node@v4`.
+
+---
+
+## Key Changes
+
+### 1. Trigger Syntax
+**Azure DevOps**:
+```yaml
+trigger: none
+
+pr:
+  autoCancel: true
+  drafts: false
+  branches:
+    include:
+      - master
+      - beta
+```
+
+**GitHub Actions**:
+```yaml
+on:
+  pull_request:
+    branches: [master, beta]
+    types: [opened, synchronize, reopened]
+```
+
+### 2. Job Syntax
+**Azure DevOps**:
+```yaml
+jobs:
+  - job: Build_Test_Dryrun
+    displayName: Build - Test - DryRun
+    pool:
+      vmImage: ubuntu-latest
+```
+
+**GitHub Actions**:
+```yaml
+jobs:
+  Build_Test_Dryrun:
+    name: Build - Test - DryRun
+    runs-on: ubuntu-latest
+```
+
+### 3. Checkout
+**Azure DevOps**:
+```yaml
+- checkout: self
+  fetchTags: true
+```
+
+**GitHub Actions**:
+```yaml
+- name: Checkout code
+  uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+    fetch-tags: true
+```
+
+### 4. Node.js Setup
+**Azure DevOps**:
+```yaml
+- task: NodeTool@0
+  displayName: Use Node 18.x
+  inputs:
+    versionSpec: 18.x
+```
+
+**GitHub Actions**:
+```yaml
+- name: Use Node 18.x
+  uses: actions/setup-node@v4
+  with:
+    node-version: '18'
+```
+
+### 5. Running Scripts
+**Azure DevOps**:
+```yaml
+- task: CmdLine@2
+  displayName: Install
+  inputs:
+    script: |
+      set -e
+      npm i -g husky
+      npm i -g pinst
+      yarn install
+```
+
+**GitHub Actions**:
+```yaml
+- name: Install
+  run: |
+    set -e
+    npm i -g husky
+    npm i -g pinst
+    yarn install
+```
+
+### 6. Environment Variables
+**Azure DevOps**:
+```yaml
+- script: 'npm run dryrun'
+  displayName: 'Perform Dry Run'
+  env:
+    GITHUB_TOKEN: $(GH_TOKEN)
+    NPM_TOKEN: $(NPM_TOKEN)
+```
+
+**GitHub Actions**:
+```yaml
+- name: Perform Dry Run
+  run: npm run dryrun
+  # No env variables needed - GITHUB_TOKEN auto-provided
+  # NPM_TOKEN not needed - using NPM Trusted Publisher
+```
+
+---
+
+## Best Practices
+
+### 1. Preserve Original Structure
+- Keep original job/step names and display names
+- Preserve all original commands
+- Maintain same logical flow
+
+### 2. Remove Unnecessary Dependencies
+- Don't need `GH_TOKEN` in GitHub Actions (auto-provided as `GITHUB_TOKEN`)
+- Use NPM Trusted Publisher instead of `NPM_TOKEN` secret
+
+### 3. Use Official GitHub Actions
+- Prefer `actions/checkout@v4` and `actions/setup-node@v4`
+- They're well-tested and maintained by GitHub
+
+### 4. Handle Enterprise Restrictions
+- If actions are blocked, use manual alternatives as fallback
+- Update repository settings to allow official actions when possible
+
+### 5. Test Incrementally
+- Start with basic structure
+- Test each step
+- Fix errors one at a time
+
+### 6. Document Changes
+- Add comments explaining the migration
+- Include original file reference
+- Note any deviations from original
+
+---
+
+## Summary
+
+### What Changed
+✅ Trigger syntax (Azure DevOps → GitHub Actions)  
+✅ Job syntax (pool → runs-on)  
+✅ Checkout mechanism  
+✅ Node.js setup method  
+✅ Script execution syntax  
+✅ Removed environment variables (GITHUB_TOKEN, NPM_TOKEN)  
+✅ Updated to use official GitHub Actions  
+
+### What Stayed the Same
+✅ All original commands  
+✅ Job and step names  
+✅ Build and test processes  
+✅ Node version (18.x)  
+✅ Execution flow  
+
+### Key Learnings
+1. **GitHub Settings Matter**: Enterprise policies can block even official actions
+2. **Tokens Are Different**: GitHub Actions provides `GITHUB_TOKEN` automatically
+3. **Checkout is Required**: Must explicitly checkout code in GitHub Actions
+4. **Caching Needs Lock Files**: Yarn caching requires `yarn.lock` file
+5. **Minimal Changes**: Preserve original structure as much as possible
+
+---
+
+## Next Steps
+
+### For Additional Pipelines
+- Convert `ci/release/beta.yml` to `.github/workflows/beta_exact.yml`
+- Convert `ci/release/master.yml` to `.github/workflows/master_exact.yml`
+- Follow same patterns and best practices
+
+### For Production Use
+- Update trigger branches to production branches
+- Add proper environment protections
+- Configure deployment gates
+- Set up notifications and alerts
+
+---
+
+## References
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Azure DevOps Documentation](https://docs.microsoft.com/en-us/azure/devops/)
+- [Semantic Release Documentation](https://semantic-release.gitbook.io/)
+- [Original Pipeline](ci/build/build_validation.yml)
+- [Converted Pipeline](.github/workflows/build_validation_exact.yml)
+
+---
+
+## Revision History
+
+- **2025-12-10**: Initial migration document created
+- **Status**: Build validation pipeline successfully migrated and tested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worksafevictoria/wcl7.5",
-  "version": "1.19.0-beta.7",
+  "version": "1.19.0-beta.8",
   "description": "WorkSafe Victoria Component Library - GitHub Actions Migration Test",
   "main": "src/index.js",
   "license": "MIT",