Pre-Push Hook

Test execution and build verification before pushing to remote repository, preventing broken code from reaching shared branches.

Purpose

The pre-push hook is the final quality gate before code reaches the remote repository. It ensures:

Tests Pass - All unit and integration tests must pass
Build Succeeds - Production build completes without errors
Branch Naming - Enforces branch naming conventions
Submodule Sync - Verifies submodules are committed and pushed
Protected Branches - Prevents direct push to main/master

Priority: P0 - Critical for pilot release Impact: Prevents broken code from reaching shared branches and CI/CD pipeline

Trigger

Event: pre-push (git hook) Blocking: Yes - Push will fail if checks don't pass Timeout: 120 seconds (2 minutes, configurable for test suites) Bypass: git push --no-verify

Checks Performed

Test Execution (P0)

Python Tests - Run pytest with coverage threshold
JavaScript Tests - Run jest/vitest test suite
Rust Tests - Run cargo test
Integration Tests - Run integration test suite
Coverage Threshold - Enforce minimum coverage (default: 70%)

Build Verification (P0)

Python Build - Validate package builds successfully
JavaScript Build - Run npm/yarn build
Rust Build - Run cargo build --release
TypeScript - Verify tsc compiles without errors
Docker Build - Validate Dockerfile builds (if present)

Branch Protection (P0)

Branch Naming - Enforce naming conventions (feature/, fix/, etc.)
Protected Branches - Block direct push to main/master/develop
Force Push Prevention - Warn on force push attempts

Submodule Checks (P1)

Submodule Status - Verify all submodules committed
Submodule Push - Ensure submodules pushed before parent
Submodule Sync - Check for detached HEAD states

CI Status (P1)

Remote CI Status - Check if last CI run passed
PR Status - Verify associated PR checks pass
Build Artifacts - Validate required artifacts exist

Installation

Method 1: Pre-commit Framework (Recommended)

# Add to .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: coditect-pre-push
        name: CODITECT Pre-push
        entry: bash .coditect/hooks/pre-push
        language: system
        pass_filenames: false
        stages: [push]

      - id: submodule-check
        name: Submodule Push Check
        entry: bash .coditect/hooks/pre-push-submodule-check.sh
        language: system
        pass_filenames: false
        stages: [push]

# Install push hook
pre-commit install --hook-type pre-push

Method 2: Direct Git Hook

# Copy hook script
cp .coditect/hooks/pre-push .git/hooks/pre-push
chmod +x .git/hooks/pre-push

Method 3: Husky (npm projects)

# Add pre-push hook
npx husky add .husky/pre-push "bash .coditect/hooks/pre-push"

Configuration

Environment Variables

Variable	Default	Description
`CODITECT_SKIP_TESTS`	`false`	Skip test execution
`CODITECT_SKIP_BUILD`	`false`	Skip build verification
`CODITECT_COVERAGE_THRESHOLD`	`70`	Minimum test coverage %
`CODITECT_PROTECTED_BRANCHES`	`main,master,develop`	Branches to protect
`CODITECT_TIMEOUT`	`120`	Hook timeout in seconds
`CI`	`false`	Skip some checks in CI

.coditect/hooks.yaml

pre-push:
  enabled: true
  timeout: 120
  checks:
    tests: true
    build: true
    branch_naming: true
    protected_branches: true
    submodules: true
    ci_status: false  # Disable if no CI
  coverage:
    threshold: 70
    fail_under: true
  protected_branches:
    - main
    - master
    - develop
    - release/*
  branch_patterns:
    allowed:
      - feature/*
      - fix/*
      - hotfix/*
      - docs/*
      - refactor/*
      - test/*
      - chore/*

Bypass

Skip All Checks

git push --no-verify

Skip Specific Checks

# Skip tests only
CODITECT_SKIP_TESTS=true git push

# Skip build only
CODITECT_SKIP_BUILD=true git push

# Push to protected branch (requires reason)
CODITECT_FORCE_PROTECTED=true CODITECT_FORCE_REASON="hotfix-critical" git push

Emergency Push

# For critical hotfixes (logged for audit)
git push --no-verify
# Then immediately open PR for review

Examples

Success Output

$ git push origin feature/user-auth

CODITECT Pre-push Hook v1.0.0
================================

Branch: feature/user-auth → origin/feature/user-auth
Commits: 3 new commits

[1/5] Branch Validation...
  ✅ Branch name valid: feature/user-auth
  ✅ Not pushing to protected branch

[2/5] Running Tests...
  ✅ pytest: 47 passed, 0 failed (12.3s)
  ✅ Coverage: 78% (threshold: 70%)

[3/5] Build Verification...
  ✅ Python build successful
  ✅ TypeScript compilation clean

[4/5] Submodule Check...
  ✅ All submodules committed
  ✅ No detached HEAD states

[5/5] Final Validation...
  ✅ No merge conflicts
  ✅ Commits signed

================================
✅ All pre-push checks passed!
================================

Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Writing objects: 100% (10/10), 2.45 KiB | 2.45 MiB/s, done.

Failure Output - Tests

$ git push origin feature/broken-auth

CODITECT Pre-push Hook v1.0.0
================================

[2/5] Running Tests...
  ❌ TEST FAILURES DETECTED - PUSH BLOCKED

  pytest output:
  FAILED tests/test_auth.py::test_login - AssertionError
  FAILED tests/test_auth.py::test_logout - KeyError: 'session'

  2 failed, 45 passed (15.2s)

================================
❌ Pre-push checks FAILED
================================

Fix failing tests before pushing:
  pytest tests/test_auth.py -v

Or bypass with (not recommended):
  git push --no-verify

Failure Output - Protected Branch

$ git push origin main

CODITECT Pre-push Hook v1.0.0
================================

[1/5] Branch Validation...
  ❌ PROTECTED BRANCH - PUSH BLOCKED

  Cannot push directly to 'main'.
  This branch requires pull request review.

================================
❌ Pre-push checks FAILED
================================

Create a feature branch instead:
  git checkout -b feature/my-changes
  git push -u origin feature/my-changes

Then create a pull request for review.

Failure Output - Submodules

$ git push origin main

CODITECT Pre-push Hook v1.0.0
================================

[4/5] Submodule Check...
  ❌ SUBMODULE NOT PUSHED - PUSH BLOCKED

  Submodule 'submodules/core/coditect-core' has commits
  that haven't been pushed to origin.

  Local:  abc1234 (ahead of origin by 2 commits)
  Remote: def5678

================================
❌ Pre-push checks FAILED
================================

Push submodule first:
  cd submodules/core/coditect-core
  git push
  cd ../../..
  git push

Troubleshooting

Tests Taking Too Long

Symptom: Pre-push timeout during tests Solution:

# Run only fast unit tests, skip integration
CODITECT_TEST_ARGS="--ignore=tests/integration" git push

# Or increase timeout
CODITECT_TIMEOUT=300 git push

# Or mark slow tests
# In pytest: @pytest.mark.slow
# Then: CODITECT_TEST_ARGS="-m 'not slow'" git push

Build Failing Locally But Passes in CI

Symptom: Local build fails, CI succeeds Solution:

# Clean build artifacts
rm -rf dist/ build/ node_modules/.cache/

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
# or
npm ci

# Try build again
npm run build

Submodule Issues

Symptom: "Submodule has local changes" Solution:

# Check submodule status
git submodule status

# If changes need to be committed
cd submodules/problematic
git add -A && git commit -m "message" && git push
cd ../..

# If changes should be discarded
git submodule update --init --recursive

Force Push Needed

Symptom: Need to force push (rebase, amend) Solution:

# Force push with verification
git push --force-with-lease

# Force push bypassing hook (use carefully)
git push --force --no-verify

# Note: Force push to protected branches is always blocked

Performance

Check	Typical Time	Max Time
Branch Validation	100ms	500ms
Python Tests	10-30s	60s
JavaScript Tests	5-15s	45s
Build Verification	5-20s	60s
Submodule Check	500ms	5s
Total	20-60s	120s

Optimization Tips:

Use pytest-xdist for parallel test execution
Cache dependencies between runs
Skip slow integration tests (run in CI)
Use incremental builds where possible

pre-commit-hook - Code quality before commit
post-checkout-hook - Environment setup
ci-integration-hook - GitHub Actions integration

Implementation Scripts

The implementation scripts are at:

.coditect/hooks/pre-push (main script - to be created)
.coditect/hooks/pre-push-submodule-check.sh (submodule validation)
.coditect/hooks/production-cleanup-pre-push.sh (production cleanup)

Changelog

v1.0.0 - December 8, 2025

Initial comprehensive documentation
Defined test and build verification
Added branch protection rules
Created submodule sync checks
Added troubleshooting guide

Purpose​

Trigger​

Checks Performed​

Test Execution (P0)​

Build Verification (P0)​

Branch Protection (P0)​

Submodule Checks (P1)​

CI Status (P1)​

Installation​

Method 1: Pre-commit Framework (Recommended)​

Method 2: Direct Git Hook​

Method 3: Husky (npm projects)​

Configuration​

Environment Variables​

.coditect/hooks.yaml​

Bypass​

Skip All Checks​

Skip Specific Checks​

Emergency Push​

Examples​

Success Output​

Failure Output - Tests​

Failure Output - Protected Branch​

Failure Output - Submodules​

Troubleshooting​

Tests Taking Too Long​

Build Failing Locally But Passes in CI​

Submodule Issues​

Force Push Needed​

Performance​

Related Hooks​

Implementation Scripts​

Changelog​

v1.0.0 - December 8, 2025​