Remote Work Tools

Remote teams can’t rely on a team lead catching every style issue in review. Automated quality gates enforce standards consistently: lint, test coverage, security scanning, and complexity checks all block merges when they fail. This guide sets up a complete gate pipeline for GitHub teams.

Prerequisites

Before you begin, make sure you have the following ready:

Step 1: Layer 1: Pre-Commit Hooks (Local, Fast)

Stop bad code before it’s pushed:

# Install pre-commit
pip install pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-json
      - id: check-merge-conflict
      - id: detect-private-key
      - id: check-large-files
        args: ['--maxkb=500']

  - repo: https://github.com/psf/black
    rev: 23.12.1
    hooks:
      - id: black

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
        args: [--fix]

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

# Install hooks
pre-commit install
pre-commit install --hook-type commit-msg

# Run against all files once
pre-commit run --all-files

# Update hooks
pre-commit autoupdate

Step 2: Layer 2: SonarQube for Code Analysis

# docker-compose.yml (SonarQube server)
version: "3.8"

services:
  sonarqube:
    image: sonarqube:10.3-community
    container_name: sonarqube
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://sonar_db:5432/sonar
      - SONAR_JDBC_USERNAME=sonar
      - SONAR_JDBC_PASSWORD=${SONAR_DB_PASSWORD}
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
    ports:
      - "9000:9000"
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    restart: unless-stopped
    depends_on:
      - sonar_db

  sonar_db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=sonar
      - POSTGRES_PASSWORD=${SONAR_DB_PASSWORD}
      - POSTGRES_DB=sonar
    volumes:
      - sonar_db_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  sonar_db_data:

docker compose up -d
# Access at http://localhost:9000 (admin/admin, change immediately)

# sonar-project.properties (in project root)
sonar.projectKey=my-service
sonar.projectName=My Service
sonar.projectVersion=1.0
sonar.sources=src
sonar.tests=tests
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.version=3.11

# Quality gate thresholds (set in SonarQube UI or via API)
# Coverage: min 80%
# Duplications: max 3%
# Maintainability rating: A
# Reliability rating: A
# Security rating: A
# Security hotspots reviewed: 100%

Step 3: Layer 3: GitHub Actions Quality Gate

# .github/workflows/quality.yml
name: Quality Gate

on:
  pull_request:
    branches: [main, develop]

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: pip

      - name: Install dependencies
        run: pip install -r requirements.txt -r requirements-dev.txt

      - name: Lint with ruff
        run: ruff check . --output-format github

      - name: Type check with mypy
        run: mypy src/ --show-error-codes

      - name: Run tests with coverage
        run: |
          pytest --cov=src \
                 --cov-report=xml \
                 --cov-report=term-missing \
                 --cov-fail-under=80 \
                 -v

      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage.xml

  sonarqube:
    runs-on: ubuntu-latest
    needs: lint-test
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Download coverage
        uses: actions/download-artifact@v4
        with:
          name: coverage

      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@master
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

      - name: Check SonarQube Quality Gate
        uses: SonarSource/sonarqube-quality-gate-action@master
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: fs
          scan-ref: .
          severity: HIGH,CRITICAL
          exit-code: 1
          format: sarif
          output: trivy-results.sarif

      - name: Upload Trivy results to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif

Step 4: Layer 4: Branch Protection Rules

Configure in GitHub repo settings (or via API):

# Via GitHub CLI
gh api repos/yourorg/yourrepo/branches/main/protection \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  -f required_status_checks='{"strict":true,"contexts":["lint-test","sonarqube","security"]}' \
  -f enforce_admins=false \
  -f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
  -f restrictions=null \
  -f required_linear_history=true \
  -f allow_force_pushes=false \
  -f allow_deletions=false

Settings to enable:

Step 5: Layer 5: PR Size Limits

Large PRs resist review. Automate a size check:

# .github/workflows/pr-size.yml
name: PR Size Check

on:
  pull_request:

jobs:
  check-size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Check PR size
        run: |
          ADDITIONS=$(git diff --stat origin/${{ github.base_ref }}...HEAD | tail -1 | grep -oP '\d+ insertion' | grep -oP '\d+' || echo 0)
          DELETIONS=$(git diff --stat origin/${{ github.base_ref }}...HEAD | tail -1 | grep -oP '\d+ deletion' | grep -oP '\d+' || echo 0)
          TOTAL=$((ADDITIONS + DELETIONS))

          echo "Lines changed: +${ADDITIONS} -${DELETIONS} (total: ${TOTAL})"

          if [ "$TOTAL" -gt 500 ]; then
            echo "::warning::PR has ${TOTAL} line changes. Consider splitting into smaller PRs."
          fi

          if [ "$TOTAL" -gt 1000 ]; then
            echo "::error::PR exceeds 1000 line changes. Please split this PR."
            exit 1
          fi

Step 6: Reporting to Slack

# Add to quality.yml
  notify:
    needs: [lint-test, sonarqube, security]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Quality gate summary
        uses: slackapi/slack-github-action@v1.25.0
        with:
          payload: |
            {
              "text": "${{ needs.lint-test.result == 'success' && needs.sonarqube.result == 'success' && needs.security.result == 'success' && ':white_check_mark: Quality gate passed' || ':x: Quality gate failed' }} — PR #${{ github.event.number }}\n${{ github.event.pull_request.html_url }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

Step 7: Enforcing Commit Message Standards

Inconsistent commit messages make it impossible to generate meaningful changelogs or trace bugs through history. Add a commit-msg hook that enforces Conventional Commits format:

# In .pre-commit-config.yaml, add:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.2.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: [feat, fix, docs, style, refactor, perf, test, chore, ci, build]

This blocks commits like fix stuff but allows fix(auth): handle expired JWT tokens correctly. Your CI/CD pipeline can then run conventional-changelog to auto-generate release notes on every merge to main.

Step 8: Caching for Fast Feedback Loops

Remote developers tolerate slow feedback loops poorly — a 10-minute CI run kills momentum. Cache aggressively:

# In .github/workflows/quality.yml, improve the lint-test job:
      - name: Cache pip packages
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Cache pre-commit hooks
        uses: actions/cache@v4
        with:
          path: ~/.cache/pre-commit
          key: ${{ runner.os }}-pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}

For Python projects this alone cuts install time from 90 seconds to under 10. Apply the same pattern to npm (~/.npm), Maven (~/.m2), or Gradle (~/.gradle) caches.

Step 9: Language-Specific Gate Configurations

JavaScript / TypeScript Projects

# .github/workflows/quality-js.yml (parallel to the Python version)
jobs:
  lint-test-js:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: npm

      - run: npm ci

      - name: ESLint
        run: npx eslint . --ext .ts,.tsx,.js --max-warnings 0

      - name: TypeScript type check
        run: npx tsc --noEmit

      - name: Tests with coverage
        run: npx vitest run --coverage

      - name: Check coverage threshold
        run: |
          COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
          echo "Line coverage: ${COVERAGE}%"
          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
            echo "::error::Coverage ${COVERAGE}% is below the 80% threshold"
            exit 1
          fi

Go Projects

      - name: golangci-lint
        uses: golangci/golangci-lint-action@v4
        with:
          version: v1.55

      - name: Test with race detector
        run: go test -race -coverprofile=coverage.out ./...

      - name: Check coverage
        run: |
          COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | tr -d '%')
          echo "Coverage: ${COVERAGE}%"
          [ $(echo "$COVERAGE >= 80" | bc) -eq 1 ] || (echo "::error::Coverage below 80%"; exit 1)

Step 10: Rollout Strategy for Existing Codebases

Dropping a strict quality gate on a legacy codebase generates hundreds of failures and demoralizes the team. Use a ratchet approach instead:

  1. Audit first: Run ruff check . --statistics or eslint --format json | jq '.[] | .errorCount' | paste -sd+ | bc to count total violations.
  2. Set current state as baseline: Configure tools to only fail on new violations. SonarQube’s “new code” mode does this natively — it only gates on code changed since a defined baseline date.
  3. Add --diff-filter to pre-commit: Run checks only on files touched in the commit, not the entire repo.
  4. Tighten monthly: Lower thresholds by 10% each month. Track progress in a shared dashboard so the team sees improvement over time.

This converts the quality gate from an obstacle into a metric that visibly improves — which changes team culture around code quality faster than enforcement alone.

Step 11: Configure Quality Gate Notifications Without Noise

Spam every PR failure to Slack and engineers mute the channel. Tune notifications:

  notify:
    needs: [lint-test, sonarqube, security]
    if: always() && github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    steps:
      - name: Notify only on failure
        if: contains(needs.*.result, 'failure')
        uses: slackapi/slack-github-action@v1.25.0
        with:
          payload: |
            {
              "text": ":x: Quality gate failed on PR #${{ github.event.number }} — ${{ github.event.pull_request.title }}\n${{ github.event.pull_request.html_url }}\nFailed jobs: lint-test=${{ needs.lint-test.result }}, sonarqube=${{ needs.sonarqube.result }}, security=${{ needs.security.result }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

Only failures alert the channel. Passes are recorded in the PR timeline but produce no Slack noise. This keeps the #engineering channel useful instead of a stream of green checkmarks.

Troubleshooting

Configuration changes not taking effect

Restart the relevant service or application after making changes. Some settings require a full system reboot. Verify the configuration file path is correct and the syntax is valid.

Permission denied errors

Run the command with sudo for system-level operations, or check that your user account has the necessary permissions. On macOS, you may need to grant terminal access in System Settings > Privacy & Security.

Connection or network-related failures

Check your internet connection and firewall settings. If using a VPN, try disconnecting temporarily to isolate the issue. Verify that the target server or service is accessible from your network.

Explore Our Developer Guides

© 2026 theluckystrike Developer Guides