single-commit-enforcement.yml

name: Single Commit Per Branch Enforcement

on:
  push:
    branches-ignore: [release, main, develop]
  pull_request:
    branches: [release, main]
    types: [opened, synchronize, reopened]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  enforce-single-commit:
    runs-on: ubuntu-latest
    name: 🔒 Single Commit Policy Validation

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Validate Single Commit Policy
        id: validate
        env:
          # Passed through env, never interpolated into the script body: an
          # expression is substituted into the script TEXT before the shell
          # parses it, so a backtick or $( ) in any of these executes on the
          # runner. Reachable by anyone who can open a PR — a commit subject is
          # free text, and git accepts backticks, $( ) and ; in branch names.
          # https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections
          EVENT_NAME: ${{ github.event_name }}
          BASE_REF: ${{ github.base_ref }}
          HEAD_REF: ${{ github.head_ref }}
          REF_NAME: ${{ github.ref_name }}
          HEAD_REPO_ID: ${{ github.event.pull_request.head.repo.id }}
          BASE_REPO_ID: ${{ github.event.repository.id }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          # Determine the base branch and current branch
          if [ "$EVENT_NAME" = "pull_request" ]; then
            BASE_BRANCH="origin/$BASE_REF"
            BRANCH_NAME="$HEAD_REF"
            
            # Handle external vs internal contributors differently using repository IDs for security
            if [ "$HEAD_REPO_ID" != "$BASE_REPO_ID" ]; then
              # External contributor - use the PR head SHA directly
              CURRENT_BRANCH="HEAD"
              echo "📡 External contributor detected"
              echo "🔍 Head repository ID: $HEAD_REPO_ID"
              echo "🔍 Base repository ID: $BASE_REPO_ID"
              echo "🔍 Using PR head SHA: $HEAD_SHA"
              
              # For external PRs, checkout the actual PR commit (not the merge commit)
              echo "🔄 Checking out PR head commit for validation..."
              git checkout "$HEAD_SHA"
              CURRENT_BRANCH="HEAD"
            else
              # Internal branch - can checkout the actual branch
              echo "🏠 Internal contributor detected"
              echo "🔄 Switching to actual PR head branch for validation..."
              git checkout "origin/$HEAD_REF"
              CURRENT_BRANCH="origin/$HEAD_REF"
            fi
          else
            BASE_BRANCH="origin/release"
            CURRENT_BRANCH="HEAD"
            BRANCH_NAME="$REF_NAME"
          fi

          echo "🔍 Validating single commit policy..."
          echo "Base branch: $BASE_BRANCH"
          echo "Current branch: $BRANCH_NAME"

          # Ensure we have the latest refs
          git fetch origin

          # Count commits ahead of base branch
          COMMIT_COUNT=$(git rev-list --count $CURRENT_BRANCH ^$BASE_BRANCH 2>/dev/null || echo "0")

          echo "commits_ahead=$COMMIT_COUNT" >> $GITHUB_OUTPUT
          echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
          echo "base_branch=$BASE_BRANCH" >> $GITHUB_OUTPUT

          echo "📊 Commits ahead of base: $COMMIT_COUNT"

          # Validate commit count
          if [ $COMMIT_COUNT -eq 0 ]; then
            echo "✅ Branch is up to date with base branch"
            echo "status=up_to_date" >> $GITHUB_OUTPUT
          elif [ $COMMIT_COUNT -eq 1 ]; then
            echo "✅ Branch contains exactly 1 commit - POLICY COMPLIANT"
            echo "status=compliant" >> $GITHUB_OUTPUT
            
            # Get the single commit details
            COMMIT_HASH=$(git rev-list -1 $CURRENT_BRANCH ^$BASE_BRANCH)
            COMMIT_MSG=$(git log -1 --pretty=format:"%s" $COMMIT_HASH)
            COMMIT_AUTHOR=$(git log -1 --pretty=format:"%an" $COMMIT_HASH)
            
            echo "📝 Commit: $COMMIT_MSG"
            echo "👤 Author: $COMMIT_AUTHOR"
            echo "🔑 Hash: $COMMIT_HASH"
            
            echo "commit_message=$COMMIT_MSG" >> $GITHUB_OUTPUT
            echo "commit_hash=$COMMIT_HASH" >> $GITHUB_OUTPUT
            echo "commit_author=$COMMIT_AUTHOR" >> $GITHUB_OUTPUT
            
          else
            echo "❌ POLICY VIOLATION: Branch contains $COMMIT_COUNT commits"
            echo "status=violation" >> $GITHUB_OUTPUT
            
            # Get details of all commits for the error message
            echo "📋 Commits in this branch:"
            git log --oneline $CURRENT_BRANCH ^$BASE_BRANCH
          fi

      - name: Validate Commit Message Format
        if: steps.validate.outputs.status == 'compliant'
        env:
          # A commit subject is free text. Interpolated directly it became a
          # shell fragment: a subject containing backticks ran their contents
          # on the runner and the step died with exit 127 -- reported as
          # "commit message doesn't follow semantic format", which is both a
          # false verdict and a command execution.
          COMMIT_MSG: ${{ steps.validate.outputs.commit_message }}
        run: |
          echo "🔍 Validating commit message format: '$COMMIT_MSG'"

          # Check semantic commit format: type(scope): description  
          if ! echo "$COMMIT_MSG" | grep -qE "^[a-z]+\([^)]+\): .+"; then
            echo "❌ Commit message doesn't follow semantic format"
            echo "Expected: type(scope): description"
            echo "Received: $COMMIT_MSG"
            echo ""
            echo "Valid examples:"
            echo "  feat(auth): add OAuth2 authentication flow"
            echo "  fix(api): resolve null pointer exception in user service"
            echo "  docs(readme): update installation instructions"
            exit 1
          fi

          echo "✅ Commit message format is valid"

      - name: Reject CI-Skip Directives
        if: steps.validate.outputs.status == 'compliant'
        env:
          COMMIT_HASH: ${{ steps.validate.outputs.commit_hash }}
        run: |
          # The format check above reads only the subject line (%s). GitHub reads
          # the WHOLE message, body included, so a skip directive quoted in a body
          # -- e.g. while documenting semantic-release's own commit template --
          # silently suppresses every workflow for the resulting push. That has
          # already happened once on `release`: the merge ran no CI at all, and
          # nothing reported it, because a skipped run looks identical to a run
          # that was never required.
          FULL_MSG=$(git log -1 --pretty=format:%B "$COMMIT_HASH")

          if echo "$FULL_MSG" | grep -qiE '\[(skip ci|ci skip|no ci|skip actions|actions skip)\]'; then
            echo "❌ POLICY VIOLATION: commit message contains a CI-skip directive"
            echo ""
            echo "Offending line(s):"
            echo "$FULL_MSG" | grep -niE '\[(skip ci|ci skip|no ci|skip actions|actions skip)\]' | sed 's/^/    /'
            echo ""
            echo "GitHub honours [skip ci], [ci skip], [no ci], [skip actions] and"
            echo "[actions skip] anywhere in a commit message -- subject or body."
            echo "Merging this would push a commit that runs no workflows at all,"
            echo "including the checks required to protect this branch."
            echo ""
            echo "🔧 TO FIX:"
            echo "  If you were quoting the directive rather than intending it,"
            echo "  break up the literal text -- write 'skip-ci' or 'skip<space>ci'"
            echo "  instead -- or move the explanation to the pull request body,"
            echo "  which GitHub does not scan."
            echo ""
            echo "    git commit --amend"
            echo "    git push --force-with-lease"
            echo ""
            echo "  If you genuinely need to skip CI, say so on the pull request"
            echo "  and have someone merge it deliberately -- it should not be a"
            echo "  side effect of how a commit message happens to be worded."
            exit 1
          fi

          echo "✅ No CI-skip directives in commit message"

      - name: Check for Merge Commits
        if: steps.validate.outputs.status == 'compliant'
        env:
          OUT_BASE_BRANCH: ${{ steps.validate.outputs.base_branch }}
        run: |
          BASE_BRANCH="$OUT_BASE_BRANCH"

          # Check for merge commits in the branch
          MERGE_COMMITS=$(git rev-list --merges HEAD ^$BASE_BRANCH)
          if [ -n "$MERGE_COMMITS" ]; then
            echo "❌ POLICY VIOLATION: Branch contains merge commits"
            echo "Merge commits are not allowed in feature branches."
            echo "Please rebase your branch instead of merging."
            echo ""
            echo "To fix:"
            echo "  git rebase $BASE_BRANCH"
            echo "  git push --force-with-lease"
            exit 1
          fi

          echo "✅ No merge commits found"

      - name: Provide Squash Instructions
        if: steps.validate.outputs.status == 'violation'
        env:
          OUT_COMMIT_COUNT: ${{ steps.validate.outputs.commits_ahead }}
          OUT_BRANCH_NAME: ${{ steps.validate.outputs.branch_name }}
        run: |
          COMMIT_COUNT="$OUT_COMMIT_COUNT"
          BRANCH_NAME="$OUT_BRANCH_NAME"

          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
          echo "🚫 SINGLE COMMIT POLICY VIOLATION"
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
          echo ""
          echo "❌ Branch '$BRANCH_NAME' contains $COMMIT_COUNT commits"
          echo "✅ NeuroLink requires exactly 1 commit per branch"
          echo ""
          echo "🔧 TO FIX - Squash your commits:"
          echo ""
          echo "1. Interactive rebase to squash commits:"
          echo "   git rebase -i HEAD~$COMMIT_COUNT"
          echo ""
          echo "2. In the editor, change 'pick' to 'squash' (or 's') for all commits except the first"
          echo "3. Save and close the editor"
          echo "4. Edit the commit message in the next editor"
          echo "5. Force push the squashed commit:"
          echo "   git push --force-with-lease"
          echo ""
          echo "🎯 Alternative - Reset and recommit:"
          echo "   git reset --soft HEAD~$COMMIT_COUNT"
          echo "   git commit -m 'type(scope): your combined commit message'"
          echo "   git push --force-with-lease"
          echo ""
          echo "📋 Current commits that need squashing:"
          git log --oneline HEAD~$COMMIT_COUNT..HEAD
          echo ""
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

          exit 1

      - name: Check Comment Permissions
        if: steps.validate.outputs.status == 'compliant'
        env:
          HEAD_REPO_ID_CHECK: ${{ github.event.pull_request.head.repo.id }}
          BASE_REPO_ID_CHECK: ${{ github.event.repository.id }}
        id: check-permissions
        run: |
          # Check if this is an external contributor PR using repository IDs for security
          if [ "$HEAD_REPO_ID_CHECK" != "$BASE_REPO_ID_CHECK" ]; then
            echo "🔒 External contributor PR detected - comment posting will be skipped due to GitHub security restrictions"
            echo "can_comment=false" >> $GITHUB_OUTPUT
          else
            echo "🏠 Internal contributor PR - comment posting enabled"
            echo "can_comment=true" >> $GITHUB_OUTPUT
          fi

      - name: Find existing comment
        if: steps.validate.outputs.status == 'compliant' && steps.check-permissions.outputs.can_comment == 'true'
        uses: peter-evans/find-comment@v3
        id: find-comment
        continue-on-error: true
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: "github-actions[bot]"
          body-includes: Single Commit Policy

      - name: Post Minimal Success Comment
        if: steps.validate.outputs.status == 'compliant' && steps.check-permissions.outputs.can_comment == 'true'
        uses: peter-evans/create-or-update-comment@v4
        continue-on-error: true
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.pull_request.number }}
          comment-id: ${{ steps.find-comment.outputs.comment-id }}
          body: |
            ## ✅ Single Commit Policy - COMPLIANT

            **Status**: Policy requirements met • 1 commit • Valid format • Ready for merge

            <details>
            <summary>📊 View validation details</summary>

            ### 📝 Commit Details
            - **Hash**: `${{ steps.validate.outputs.commit_hash }}`
            - **Message**: ${{ steps.validate.outputs.commit_message }}
            - **Author**: ${{ steps.validate.outputs.commit_author }}

            ### ✅ Validation Results
            - Single commit requirement met
            - No merge commits in branch
            - Semantic commit message format verified
            - Ready for squash merge to release branch

            </details>

            ---
            *🤖 Automated validation by NeuroLink Single Commit Enforcement*
          edit-mode: replace

      - name: Generate Policy Summary
        if: always()
        env:
          OUT_STATUS: ${{ steps.validate.outputs.status }}
        run: |
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
          echo "🔒 NEUROLINK SINGLE COMMIT POLICY ENFORCEMENT SUMMARY"
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

          STATUS="$OUT_STATUS"
          case $STATUS in
            "compliant")
              echo "✅ STATUS: POLICY COMPLIANT"
              echo "✅ Single commit requirement satisfied"
              echo "✅ Ready for merge to release branch"
              ;;
            "violation")
              echo "❌ STATUS: POLICY VIOLATION" 
              echo "❌ Multiple commits detected"
              echo "🔧 Squashing required before merge"
              ;;
            "up_to_date")
              echo "ℹ️  STATUS: BRANCH UP TO DATE"
              echo "ℹ️  No new commits to validate"
              ;;
            *)
              echo "⚠️  STATUS: UNKNOWN"
              ;;
          esac

          echo ""
          echo "📋 Policy Requirements:"
          echo "  • Exactly 1 commit per branch"
          echo "  • Semantic commit message format: type(scope): description" 
          echo "  • No merge commits allowed"
          echo "  • Squash merge enforced at branch protection level"
          echo ""
          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"