pipecraft 0.0.0-releaseit

package/.github/actions/promote-branch/action.yml

@@ -0,0 +1,352 @@
+name: 'Promote Branch'
+description: 'Promote code from source to target branch via temporary branch + PR'
+author: 'PipeCraft'
+
+inputs:
+  sourceBranch:
+    description: 'Source branch to promote from (defaults to github.ref_name)'
+    required: false
+    default: ${{ github.ref_name }}
+  version:
+    description: 'Version being promoted (e.g., v1.2.3, auto-detected from git tags if not provided)'
+    required: false
+    default: ''
+  run_number:
+    description: 'Original run number from develop branch to track across promotions'
+    required: false
+    default: ''
+  configPath:
+    description: 'Path to .pipecraftrc.json config file'
+    required: false
+    default: '.pipecraftrc.json'
+  tempBranchPattern:
+    description: 'Pattern for temp branch name'
+    required: false
+    default: 'release/{source}-to-{target}-{version}'
+  token:
+    description: 'GitHub token for authentication'
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  prNumber:
+    description: 'The created PR number'
+    value: ${{ steps.create-pr.outputs.prNumber }}
+  prUrl:
+    description: 'The created PR URL'
+    value: ${{ steps.create-pr.outputs.prUrl }}
+  tempBranch:
+    description: 'The temporary branch name'
+    value: ${{ steps.create-temp.outputs.tempBranch }}
+  targetBranch:
+    description: 'The target branch determined from config'
+    value: ${{ steps.read-config.outputs.targetBranch }}
+  autoMerge:
+    description: 'The autoMerge setting for the target branch'
+    value: ${{ steps.read-config.outputs.autoMerge }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        token: ${{ inputs.token }}
+
+    - name: Read Config and Determine Target Branch
+      id: read-config
+      shell: bash
+      run: |
+        SOURCE="${{ inputs.sourceBranch }}"
+        CONFIG_PATH="${{ inputs.configPath }}"
+
+        echo "📖 Reading config from $CONFIG_PATH"
+
+        # Check if config file exists
+        if [ ! -f "$CONFIG_PATH" ]; then
+          echo "❌ Config file not found: $CONFIG_PATH"
+          exit 1
+        fi
+
+        # Read branchFlow array from config
+        BRANCH_FLOW=$(cat "$CONFIG_PATH" | jq -r '.branchFlow | join(" ")')
+        echo "🔍 Branch flow: $BRANCH_FLOW"
+
+        # Convert to array
+        IFS=' ' read -ra BRANCHES <<< "$BRANCH_FLOW"
+
+        # Find current branch index and determine target
+        TARGET=""
+        for i in "${!BRANCHES[@]}"; do
+          if [ "${BRANCHES[$i]}" == "$SOURCE" ]; then
+            # Get next branch in flow
+            NEXT_INDEX=$((i + 1))
+            if [ $NEXT_INDEX -lt ${#BRANCHES[@]} ]; then
+              TARGET="${BRANCHES[$NEXT_INDEX]}"
+            fi
+            break
+          fi
+        done
+
+        if [ -z "$TARGET" ]; then
+          echo "❌ Could not determine target branch for source: $SOURCE"
+          echo "   Branch flow: $BRANCH_FLOW"
+          exit 1
+        fi
+
+        echo "✅ Target branch: $TARGET"
+        echo "targetBranch=$TARGET" >> $GITHUB_OUTPUT
+
+        # Determine autoMerge setting for target branch
+        AUTO_MERGE=$(cat "$CONFIG_PATH" | jq -r ".autoMerge.\"$TARGET\" // false")
+        echo "🔍 Auto-merge for $TARGET: $AUTO_MERGE"
+        echo "autoMerge=$AUTO_MERGE" >> $GITHUB_OUTPUT
+
+    - name: Get Version
+      id: get-version
+      shell: bash
+      run: |
+        VERSION_INPUT="${{ inputs.version }}"
+
+        if [ -n "$VERSION_INPUT" ]; then
+          VERSION="$VERSION_INPUT"
+          echo "📌 Using provided version: $VERSION"
+        else
+          # Auto-detect from git tags
+          VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.1.0")
+          echo "🏷️  Auto-detected version from tags: $VERSION"
+        fi
+
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+    - name: Create Temporary Branch
+      id: create-temp
+      shell: bash
+      run: |
+        SOURCE="${{ inputs.sourceBranch }}"
+        TARGET="${{ steps.read-config.outputs.targetBranch }}"
+        VERSION="${{ steps.get-version.outputs.version }}"
+        PATTERN="${{ inputs.tempBranchPattern }}"
+
+        # Remove 'v' prefix from version for branch name
+        VERSION_CLEAN="${VERSION#v}"
+
+        # Replace placeholders in pattern
+        TEMP_BRANCH="$PATTERN"
+        TEMP_BRANCH="${TEMP_BRANCH//{source\}/$SOURCE}"
+        TEMP_BRANCH="${TEMP_BRANCH//{target\}/$TARGET}"
+        TEMP_BRANCH="${TEMP_BRANCH//{version\}/$VERSION_CLEAN}"
+
+        echo "🌿 Preparing temporary branch: $TEMP_BRANCH"
+        echo "   From: $SOURCE"
+        echo "   To: $TARGET"
+        echo "   Version: $VERSION"
+
+        # Ensure we're on the source branch
+        git checkout "$SOURCE"
+
+        # Check if temp branch already exists locally or remotely
+        if git show-ref --verify --quiet refs/heads/"$TEMP_BRANCH" || git ls-remote --heads origin "$TEMP_BRANCH" | grep -q "$TEMP_BRANCH"; then
+          echo "⚠️  Temp branch $TEMP_BRANCH already exists, using existing branch"
+          # Fetch and checkout existing branch
+          git fetch origin "$TEMP_BRANCH" 2>/dev/null || true
+          git checkout "$TEMP_BRANCH" 2>/dev/null || git checkout -b "$TEMP_BRANCH" origin/"$TEMP_BRANCH"
+        else
+          echo "📝 Creating new temp branch $TEMP_BRANCH"
+          # Create temp branch from current commit
+          git checkout -b "$TEMP_BRANCH"
+          # Push temp branch to remote
+          git push origin "$TEMP_BRANCH"
+        fi
+
+        echo "tempBranch=$TEMP_BRANCH" >> $GITHUB_OUTPUT
+        echo "✅ Temporary branch ready"
+
+    - name: Check for Existing PR
+      id: check-pr
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        TEMP_BRANCH="${{ steps.create-temp.outputs.tempBranch }}"
+        TARGET="${{ steps.read-config.outputs.targetBranch }}"
+
+        # Check if PR already exists from temp branch to target
+        EXISTING_PR=$(gh pr list --head "$TEMP_BRANCH" --base "$TARGET" --json number --jq '.[0].number' 2>/dev/null || echo "")
+
+        if [ -n "$EXISTING_PR" ]; then
+          echo "exists=true" >> $GITHUB_OUTPUT
+          echo "prNumber=$EXISTING_PR" >> $GITHUB_OUTPUT
+          echo "⚠️  PR already exists: #$EXISTING_PR"
+
+          # Get PR URL
+          PR_URL=$(gh pr view "$EXISTING_PR" --json url --jq '.url')
+          echo "prUrl=$PR_URL" >> $GITHUB_OUTPUT
+        else
+          echo "exists=false" >> $GITHUB_OUTPUT
+          echo "✅ No existing PR found"
+        fi
+
+    - name: Create Pull Request
+      id: create-pr
+      if: steps.check-pr.outputs.exists == 'false'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        TEMP_BRANCH="${{ steps.create-temp.outputs.tempBranch }}"
+        TARGET="${{ steps.read-config.outputs.targetBranch }}"
+        SOURCE="${{ inputs.sourceBranch }}"
+        VERSION="${{ steps.get-version.outputs.version }}"
+        AUTO_MERGE="${{ steps.read-config.outputs.autoMerge }}"
+
+        TITLE="🚀 Release $VERSION to $TARGET"
+
+        # Determine merge behavior text
+        if [ "$AUTO_MERGE" == "true" ]; then
+          MERGE_TEXT="merge automatically"
+        else
+          MERGE_TEXT="require manual approval"
+        fi
+
+        # Disable error exit to capture gh pr create output even on failure
+        set +e
+
+        # Create the PR - gh pr create returns the PR URL on success
+        PR_URL=$(gh pr create \--title "$TITLE" \--body "Release $VERSION from $SOURCE to $TARGET" \--head "$TEMP_BRANCH" \--base "$TARGET" 2>&1)
+        PR_EXIT_CODE=$?
+
+        # Re-enable error exit
+        set -e
+
+        if [ $PR_EXIT_CODE -eq 0 ] && [[ "$PR_URL" =~ ^https://github.com/.*/pull/[0-9]+$ ]]; then
+          # Extract PR number from URL (e.g., https://github.com/owner/repo/pull/123)
+          PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$')
+          echo "prNumber=$PR_NUMBER" >> $GITHUB_OUTPUT
+          echo "prUrl=$PR_URL" >> $GITHUB_OUTPUT
+          echo "✅ Created PR #$PR_NUMBER"
+          echo "🔗 URL: $PR_URL"
+        else
+          echo "❌ Failed to create PR"
+          echo "Error output:"
+          echo "$PR_URL"
+          exit 1
+        fi
+
+    - name: Enable PR Auto-Merge with Rebase (Manual Approval Required)
+      if: steps.read-config.outputs.autoMerge == 'false'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        PR_NUMBER="${{ steps.check-pr.outputs.prNumber || steps.create-pr.outputs.prNumber }}"
+        TARGET="${{ steps.read-config.outputs.targetBranch }}"
+
+        echo "🔐 Enabling auto-merge with rebase for PR #$PR_NUMBER (requires approval)"
+        echo "   This will fast-forward $TARGET when approved, maintaining linear history"
+
+        # Enable auto-merge with rebase method (fast-forward, no merge commit)
+        gh pr merge "$PR_NUMBER" --auto --rebase
+
+        echo "✅ Auto-merge enabled - PR will fast-forward merge when approved"
+        echo "⚠️  Manual approval required before merge completes"
+
+    - name: Fast-Forward Merge (Immediate Auto-Merge)
+      if: steps.read-config.outputs.autoMerge == 'true'
+      shell: bash
+      run: |
+        SOURCE="${{ inputs.sourceBranch }}"
+        TARGET="${{ steps.read-config.outputs.targetBranch }}"
+        VERSION="${{ steps.get-version.outputs.version }}"
+
+        echo "🚀 Fast-forwarding $TARGET to $SOURCE (maintaining linear history)"
+
+        # Get the commit SHA from source branch
+        COMMIT_SHA=$(git rev-parse $SOURCE)
+        echo "Source commit: $COMMIT_SHA"
+
+        # Fetch target branch
+        git fetch origin $TARGET:$TARGET 2>/dev/null || true
+
+        # Checkout target branch
+        git checkout $TARGET
+
+        # Verify we can fast-forward (no divergent commits)
+        if git merge-base --is-ancestor $TARGET $SOURCE; then
+          echo "✅ Fast-forward is possible (linear history maintained)"
+        else
+          echo "❌ Cannot fast-forward - branches have diverged"
+          echo "Target branch has commits not in source branch"
+          exit 1
+        fi
+
+        # Fast-forward merge (no merge commit)
+        git merge --ff-only $SOURCE
+
+        # Push to remote
+        git push origin $TARGET
+
+        echo "✅ Fast-forwarded $TARGET to $COMMIT_SHA"
+        echo "📝 PR will be closed automatically for audit trail"
+
+    - name: Trigger Pipeline Workflow on Target Branch
+      if: steps.read-config.outputs.autoMerge == 'true'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        TARGET="${{ steps.read-config.outputs.targetBranch }}"
+        VERSION="${{ steps.get-version.outputs.version }}"
+        RUN_NUMBER="${{ inputs.run_number }}"
+
+        echo "🔄 Triggering pipeline workflow on $TARGET branch with version $VERSION"
+
+        if [ -n "$RUN_NUMBER" ]; then
+          echo "   Tracking original run number: $RUN_NUMBER"
+        fi
+
+        # Trigger the pipeline workflow on the target branch
+        # This is necessary because GITHUB_TOKEN pushes don't trigger workflows by default
+        # Pass the version and run_number so runs can be tracked across promotions
+        if [ -n "$RUN_NUMBER" ]; then
+          gh workflow run pipeline.yml --ref "$TARGET" --field version="$VERSION" --field run_number="$RUN_NUMBER"
+        else
+          gh workflow run pipeline.yml --ref "$TARGET" --field version="$VERSION"
+        fi
+
+        echo "✅ Pipeline workflow triggered on $TARGET with version $VERSION"
+
+    - name: Close PR and Delete Branch
+      if: steps.read-config.outputs.autoMerge == 'true'
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+      run: |
+        TEMP_BRANCH="${{ steps.create-temp.outputs.tempBranch }}"
+        PR_NUMBER="${{ steps.check-pr.outputs.prNumber || steps.create-pr.outputs.prNumber }}"
+
+        echo "🧹 Cleaning up temporary branch: $TEMP_BRANCH"
+
+        # Close the PR (it's already been fast-forward merged)
+        if [ -n "$PR_NUMBER" ]; then
+          gh pr close "$PR_NUMBER" --comment "Automatically merged via fast-forward. Closing PR and cleaning up release branch." || true
+          echo "✅ Closed PR #$PR_NUMBER"
+        fi
+
+        # Delete the temporary branch from remote
+        git push origin --delete "$TEMP_BRANCH" || echo "⚠️  Branch may already be deleted"
+
+        echo "✅ Deleted temporary branch $TEMP_BRANCH"
+
+    - name: Use Existing PR
+      if: steps.check-pr.outputs.exists == 'true'
+      shell: bash
+      run: |
+        PR_NUMBER="${{ steps.check-pr.outputs.prNumber }}"
+        PR_URL="${{ steps.check-pr.outputs.prUrl }}"
+
+        echo "ℹ️  Using existing PR #$PR_NUMBER"
+        echo "🔗 URL: $PR_URL"
+
+        # Note: Fast-forward merge happens in separate step if autoMerge is enabled

package/.github/example/workflows/job.analyze.code.yml

@@ -0,0 +1,26 @@
+name: CodeQL Analysis
+
+on:
+  workflow_call: 
+  workflow_dispatch: 
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [javascript, typescript]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      # - name: Initialize CodeQL
+      #   uses: github/codeql-action/init@v3
+      #   with:
+      #     languages: ${{ matrix.language }}
+      # - name: Perform CodeQL Analysis
+      #   uses: github/codeql-action/analyze@v3

package/.github/example/workflows/job.analyze.docker.yml

@@ -0,0 +1,32 @@
+name: Trivy Security Scan
+
+on:
+    workflow_call: 
+    workflow_dispatch:
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    container: aquasec/trivy:latest  # 🔹 Use Trivy's Docker image directly
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      # ✅ Scan all directories containing a Dockerfile for misconfigurations
+      - name: Scan Dockerfile Misconfigurations
+        run: |
+          echo "Scanning directories containing Dockerfiles..."
+          for dir in $(find . -name "Dockerfile" -exec dirname {} \; | sort -u); do
+            echo "Scanning $dir..."
+            trivy config --severity HIGH,CRITICAL --exit-code 1 "$dir"
+          done
+
+      # ✅ Scan images listed in Docker Compose files
+      - name: Scan Docker Compose Images
+        run: |
+          echo "Extracting images from docker-compose.yml files..."
+          images=$(grep -hPo '(?<=image: )\S+' **/docker-compose.yml | sort -u || true)
+          for image in $images; do
+            echo "Scanning $image..."
+            trivy image --exit-code 1 --severity HIGH,CRITICAL "$image"
+          done

package/.github/example/workflows/job.app.api.deploy.yml

@@ -0,0 +1,127 @@
+name: "API:Job:Deploy"
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: 'The version to deploy'
+        required: true
+        type: string
+      project_id:
+        description: 'The project ID for the environment'
+        required: true
+        type: string
+
+jobs:
+  deploy:
+    environment: ${{ github.ref_name == 'main' && 'production' || github.ref_name }}
+    env: 
+      ENV: ${{ github.ref_name == 'main' && 'production' || github.ref_name }}
+      API_DIR: "apps/api"
+      PROJECT_ID: ${{ inputs.project_id }}
+      REGION: "us-east4"
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Debug Environment Variables
+        run: |
+          echo "PROJECT_ID from env: $PROJECT_ID"
+          echo "Input project_id: ${{ inputs.project_id }}"
+          echo "All environment variables:"
+          env | sort
+            
+
+      - name: Get SHA for "migration" tag
+        id: get-migration-sha
+        run: |
+          if git rev-parse refs/tags/migration >/dev/null 2>&1; then
+            echo "MIGRATION_SHA=$(git rev-parse refs/tags/_migration-${{ env.ENV }})"
+            echo "MIGRATION_SHA=$(git rev-parse refs/tags/_migration-${{ env.ENV }})" >> $GITHUB_ENV
+          else
+            echo "MIGRATION_SHA=${GITHUB_SHA}" >> $GITHUB_ENV
+          fi
+
+      - name: Get changes in migrations folder
+        id: changed-files-migrations
+        uses: tj-actions/changed-files@v42
+        with:
+          files: apps/api/migrations/**
+          sha: ${{ env.MIGRATION_SHA }}
+
+
+      - name: Authenticate with Google
+        uses: 'google-github-actions/auth@v2'
+        with:
+          project_id: ${{ env.PROJECT_ID }}
+          credentials_json: ${{ secrets.GCP_CREDENTIALS }}
+
+      - name: Build and Push Container
+        uses: whoan/docker-build-with-cache-action@v5
+        with:
+          username: _json_key
+          password: ${{ secrets.GCP_CREDENTIALS }}
+          registry: ${{ vars.GAR_LOCATION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ vars.AR_REPO }}
+          image_name: api-${{ env.PROJECT_ID }}
+          image_tag: ${{ github.sha }}
+          context: .
+          dockerfile: ${{ env.API_DIR }}/Dockerfile
+
+      # - name: Deploy to Cloud Run with Migration
+      #   id: migration
+      #   if: steps.changed-files-migrations.outputs.any_changed == 'true' || github.event.inputs.migration_input == true
+      #   uses: google-github-actions/deploy-cloudrun@v2.0.0
+      #   with:
+      #     project_id: ${{ env.PROJECT_ID }}
+      #     service: api-${{ env.PROJECT_ID }}
+      #     region: ${{ env.REGION }}
+      #     image: ${{ vars.GAR_LOCATION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ vars.AR_REPO }}/api-${{ env.PROJECT_ID }}:${{ github.sha }}
+      #     env_vars: |
+      #       MIGRATION=${{ toJson(github.event.inputs.migration_input) || steps.changed-files-migrations.outputs.any_changed }}
+      #       NODE_CONFIG_ENV=${{ env.ENV }}
+      #       SEED=false
+      #     no_traffic: true
+
+      # - name: Create Migration tag 
+      #   if: steps.migration.outcome == 'success'
+      #   uses: actions/github-script@v7
+      #   with:
+      #     script: require('./libs/cicd/upsertTag.cjs')({ github, context, tag:"_migration-${{ env.ENV }}" })
+
+      # - name: Seed Data to Instance
+      #   id: seed
+      #   if: steps.changed-files-migrations.outputs.any_changed == 'true' || github.event.inputs.migration_input == true
+      #   uses: google-github-actions/deploy-cloudrun@v2.0.0
+      #   with:
+      #     project_id: ${{ env.PROJECT_ID }}
+      #     service: api-${{ env.PROJECT_ID }}
+      #     region: ${{ env.REGION }}
+      #     image: ${{ vars.GAR_LOCATION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ vars.AR_REPO }}/api-${{ env.PROJECT_ID }}:${{ github.sha }}
+      #     env_vars: |
+      #       MIGRATION=false
+      #       SEED=${{ github.ref_name == 'main' && 'false' || toJson(github.event.inputs.migration_input) || 'true' }}
+      #       NODE_CONFIG_ENV=${{ env.ENV }}
+      #     no_traffic: true
+
+      - name: Deploy to Cloud Run
+        uses: google-github-actions/deploy-cloudrun@v2.6.1
+        with:
+          project_id: ${{ env.PROJECT_ID }}
+          service: api-${{ env.PROJECT_ID }}
+          region: ${{ env.REGION }}
+          image: ${{ vars.GAR_LOCATION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ vars.AR_REPO }}/api-${{ env.PROJECT_ID }}:${{ github.sha }}
+          env_vars: |
+            MIGRATION=false
+            SEED=false
+            NODE_CONFIG_ENV=${{ env.ENV }}
+
+      
+      # - name: Create Deployed Tag
+      #   uses: actions/github-script@v7
+      #   with:
+      #     script: require('./libs/cicd/upsertTag.cjs')({ github, context, tag:"_deployed-${{ env.ENV }}" })
+     

package/.github/example/workflows/job.app.api.test.yml

@@ -0,0 +1,102 @@
+on:
+  workflow_call:
+  workflow_dispatch:
+
+env:
+  API_DIR: apps/api
+  DOCKER_REGISTRY: https://ghcr.io # the github registry
+  COMPOSE_FILE: apps/api/test/contracts/contract.docker-compose.yml
+
+jobs:
+  blueprint:
+    env:
+      CONTRACT_TYPE: "blueprint"
+    runs-on: ubuntu-latest
+    timeout-minutes: 7
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.DOCKER_REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Start stack
+        shell: bash
+        run: |
+          echo OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }} > ${{ env.API_DIR }}/.env
+          echo CONTRACT_TYPE=${{ env.CONTRACT_TYPE }} >> ${{ env.API_DIR }}/.env
+          docker compose --env-file ${{ env.API_DIR }}/.env -f ${{ env.COMPOSE_FILE }} up --exit-code-from newman
+        
+      - name: Stop stacks
+        if: always()
+        shell: bash
+        run: |
+          docker compose -f ${{ env.COMPOSE_FILE }} down
+  
+  plugin-loader:
+    env:
+      CONTRACT_TYPE: "plugin-loader"
+    runs-on: ubuntu-latest
+    timeout-minutes: 7
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.DOCKER_REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Start stack
+        shell: bash
+        run: |
+          echo OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }} > ${{ env.API_DIR }}/.env
+          echo CONTRACT_TYPE=${{ env.CONTRACT_TYPE }} >> ${{ env.API_DIR }}/.env
+          docker compose --env-file ${{ env.API_DIR }}/.env -f ${{ env.COMPOSE_FILE }} up --exit-code-from newman
+        
+      - name: Stop stacks
+        if: always()
+        shell: bash
+        run: |
+          docker compose -f ${{ env.COMPOSE_FILE }} down 
+
+  raw-parser:
+    env:
+      CONTRACT_TYPE: "raw-parser"
+    runs-on: ubuntu-latest
+    timeout-minutes: 7
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.DOCKER_REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Start stack
+        shell: bash
+        run: |
+          echo CONTRACT_TYPE=${{ env.CONTRACT_TYPE }} > ${{ env.API_DIR }}/.env
+          docker compose --env-file ${{ env.API_DIR }}/.env -f ${{ env.COMPOSE_FILE }} up parser newman --exit-code-from newman
+        
+      - name: Stop stacks
+        if: always()
+        shell: bash
+        run: |
+          docker compose -f ${{ env.COMPOSE_FILE }} down
+

package/.github/example/workflows/job.app.docs.deploy.yml

@@ -0,0 +1,40 @@
+name: "Docs:Deploy"
+
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - apps/docs/**/*
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+  workflow_call: 
+    inputs:
+      version:
+        description: 'The version to deploy'
+        required: true
+        type: string
+    
+jobs:
+  deploy:
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+    if: github.ref == 'refs/heads/main'
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download Build Artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: docs-build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4