Skip to content

CI/CD Requirements for Pull Requests

Quick reference: What you need to know before creating a PR

Who: All developers When: Before every PR Time: 2 minutes to review, 5 minutes to run checks

Your Complete Development Lifecycle

This document focuses on CI/CD requirements (steps 4-5). For the complete flow from task assignment to QA approval, see GitHub-ClickUp Workflow: Complete Development Lifecycle.

Quick Overview:

  1. Task assigned → Update to IN PROGRESS
  2. Create branch (from ClickUp or manually with CU-{id})
  3. Develop & test locally
  4. Create PR → Automated: PR CREATED ✅ ← You are here (CI/CD starts)
  5. PR merged → Automated: PR MERGED ✅ ← CI/CD completes
  6. Auto-deploy to dev (5-10 minutes)
  7. Test in dev → Update to READY FOR QA
  8. QA testing → UNDER TESTING
  9. QA approval → DONE (or loop back if issues found)

This guide covers: What happens during steps 4-5 (PR creation and merge automation).

What Gets Automated vs Manual

Automated: - ✅ Test execution (pytest suite) - ✅ Code coverage validation (75% minimum) - ✅ ClickUp status updates (PR CREATED, PR MERGED) - ✅ SonarCloud quality analysis (optional)

Manual: - ❌ Code review and approval - ❌ Post-deploy status updates (READY FOR QA, DONE) - ❌ QA testing coordination

Pre-PR Checklist

Required Items

  • [ ] Branch name includes ClickUp task ID (feature/CU-abc123-description)
  • [ ] All tests pass locally (pytest -v)
  • [ ] Coverage is ≥75% (see command below)
  • [ ] No merge conflicts with target branch
  • [ ] Code follows team standards (type hints, clear names, no dead code)

Run Same Checks as CI

# Run all checks at once
pytest --cov=. --cov-report=html --cov-fail-under=75 -v

# View coverage report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Automated Status Updates

Your Action ClickUp Status Automated? Notes
Create PR to develop → PR CREATED ✅ Yes GitHub Actions workflow
Merge PR to develop → PR MERGED ✅ Yes GitHub Actions workflow
Deploy to dev → READY FOR QA ❌ Manual Update in ClickUp
QA testing → UNDER TESTING ❌ Manual QA updates status
QA approves → DONE ❌ Manual QA updates status

Note: Only PR CREATED and PR MERGED are automatic. Everything else requires manual updates in ClickUp.

Automation requires: Branch name MUST contain CU-{taskId} (e.g., feature/CU-abc123-description). Workflows skip silently if missing.

What Blocks Your PR from Merging

1. ❌ Failing Tests

Solution: 

pytest -v  # Run locally to reproduce
# Fix issues and push again

2. ❌ Coverage Below 75%

Solution: 

pytest --cov=. --cov-report=html --cov-fail-under=75 -v
open htmlcov/index.html  # View what's not covered
# Add tests for uncovered code

3. ❌ Missing Code Review Approvals

Requirements: - develop branch: 1 approval - main branch: 2 approvals

4. ⚠️ SonarCloud Quality Gate

Optional for develop, required for main - Click SonarCloud check in PR for details - Fix critical and high-priority issues - Common: duplications, missing type hints, security hotspots

5. ❌ Merge Conflicts

Solution: 

git fetch origin
git merge origin/develop  # or origin/main
# Resolve conflicts, test, commit, push

Running Checks Locally

Install Dependencies

pip install -r requirements-dev.txt
# or: poetry install --with dev

Run Tests

# Basic test run
pytest -v

# With coverage (same as CI)
pytest --cov=. --cov-report=html --cov-fail-under=75 -v

# View HTML report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

# Coverage for specific module
pytest --cov=app.invoices --cov-report=term-missing -v

# Run only tests that match CI
pytest -m "not skip_file_path_issues" --cov=. --cov-fail-under=75 -v

Quick Check Before PR

# Run all checks at once
pytest --cov=. --cov-report=html --cov-fail-under=75 -v && \
git fetch origin && \
git merge origin/develop && \
echo "✅ Ready to create PR"

When Workflows Fail

If Tests Fail

Debug steps: 

# 1. Run tests locally
pytest -v

# 2. Check GitHub Actions tab in PR for exact error
# Click "Details" next to failed check

# 3. Common issues:
# - Import errors
# - Database connection problems
# - Missing environment variables

# 4. Fix and push
git add .
git commit -m "Fix failing tests"
git push

If Coverage Fails

Debug steps: 

# 1. Generate coverage report
pytest --cov=. --cov-report=html --cov-fail-under=75 -v

# 2. Open HTML report
open htmlcov/index.html

# 3. Look for red/orange lines in YOUR new code

# 4. Add tests for uncovered functions/branches

# 5. Verify improvement
pytest --cov=. --cov-report=term-missing

If ClickUp Doesn't Update

Debug steps: 

# 1. Check branch name format
git branch --show-current
# Should be: feature/CU-abc123-description

# 2. Check GitHub Actions → Checks tab → clickup-pr-created

# 3. Common issues:
# - Branch name missing "CU-{id}"
# - Task ID doesn't exist in ClickUp
# - Workflow skips silently (no error)

# 4. Fix: Create new branch with correct format
git checkout -b feature/CU-abc123-correct-name
git push origin feature/CU-abc123-correct-name

Understanding the CI/CD Flow

When you create a PR to develop: 1. GitHub Actions run automatically (ClickUp update, tests, coverage, SonarCloud) 2. You wait for: ✅ Tests pass, ✅ Coverage ≥75%, ✅ 1 approval 3. You merge when: All checks green, conversations resolved

When you merge to develop: 1. GitHub Actions updates ClickUp to "PR MERGED" 2. Manual: Deploy to dev → Update ClickUp to "READY FOR QA" → Notify QA

Detailed workflows: - GitHub Actions Workflows - Complete workflow details - GitHub-ClickUp Workflow - Daily usage guide - GitHub-ClickUp Quick Start - One-time setup guide

Standards: - Git Workflow - Branch and PR processes - Git Branch Naming - Naming conventions - Git Commit Standards - Commit format - Pull Request Template - PR standards

Questions? Ask in #dev-support Slack or contact your tech lead.