Skip to content

GitHub Actions Workflows

Automated CI/CD, quality checks, and ClickUp integration for AzmX projects

Overview

This document describes the four GitHub Actions workflows used in the invoicing-apis repository and other AzmX projects. These workflows automate ClickUp task updates, enforce code quality standards, and ensure all changes meet testing requirements.

Workflows in Context

These GitHub Actions workflows handle steps 4-5 of your complete development lifecycle (PR creation and merge). They are part of a larger flow from task assignment to QA approval.

Your complete development lifecycle:

  1. Task assigned → IN PROGRESS
  2. Create branch
  3. Develop & test locally
  4. Create PR → GitHub Actions automate: PR READY status, tests, coverage checks ✅
  5. Merge PR → GitHub Actions automate: PR MERGED status ✅
  6. Auto-deploy to dev (5-10 minutes, external mechanism)
  7. Test in dev → READY FOR QA
  8. QA testing → UNDER TESTING
  9. QA approval → DONE

This document covers: Technical details of workflows that power steps 4-5.

For complete workflow: See GitHub-ClickUp Workflow: Complete Development Lifecycle.

Workflow Summary

Workflow Trigger Purpose Blocking
clickup-pr-created.yml PR opened/reopened → develop Updates ClickUp to "PR READY" No
clickup-pr-merged.yml PR merged → develop Updates ClickUp to "PR MERGED" No
pr-checks.yml PR → develop or main Runs tests + enforces 75% coverage Yes
build.yml PR or push → develop/main SonarCloud quality analysis Optional

Workflow Trigger Visualization

graph LR
    A[Developer creates PR] --> B{Target branch?}
    B -->|develop| C[ClickUp PR Ready]
    B -->|develop| D[PR Checks]
    B -->|main| D
    B -->|develop or main| E[SonarCloud Build]

    F[PR merged to develop] --> G[ClickUp PR Merged]

    C --> H[Status: PR READY]
    G --> I[Status: PR MERGED]
    D --> J[Tests + Coverage 75%]
    E --> K[Code Quality Analysis]

Prerequisites

Before using these workflows, ensure you have:

  • ClickUp integration configured (see GitHub-ClickUp Quick Start)
  • Repository secrets configured in GitHub Settings
  • Branch protection rules enabled on develop and main
  • SonarCloud project created (for quality analysis)

ClickUp Automation

These workflows automatically update ClickUp task statuses based on PR lifecycle events. This keeps your project board in sync with development progress without manual updates.

ClickUp Status Flow

graph LR
    A[DEVELOPMENT] -->|PR opened| B[PR READY]
    B -->|PR merged| C[PR MERGED]
    C --> D[READY FOR QA]

    style B fill:#90EE90
    style C fill:#87CEEB

Note: The automated statuses are "PR READY" and "PR MERGED" (uppercase display in ClickUp).

PR Ready Workflow

File: .github/workflows/clickup-pr-created.yml

Triggers when: - Pull request is opened to develop branch - Pull request is reopened to develop branch

What it does: 1. Extracts ClickUp task ID from branch name (must contain CU-{id}) 2. Updates the task status to "PR READY" 3. Adds a comment to the task with the PR link 4. Links the GitHub PR to the ClickUp task

Branch naming requirement:

Your branch name must include the ClickUp task ID:

# ✅ Valid branch names
feature/CU-123-add-user-authentication
bugfix/CU-456-fix-invoice-calculation
hotfix/CU-789-patch-security-issue

# ❌ Invalid - workflow will skip
feature/add-user-authentication
bugfix/invoice-calculation

Environment variable:

STATUS_PR_CREATED = "pr created"

Important: The environment variable uses lowercase ("pr created"), but ClickUp displays it as uppercase ("PR READY"). This is expected behavior.

Example workflow execution:

# Simplified workflow logic
on:
  pull_request:
    types: [opened, reopened]
    branches:
      - develop

jobs:
  update-clickup:
    runs-on: ubuntu-latest
    steps:
      - name: Extract ClickUp ID
        # Extracts CU-123 from branch name

      - name: Update Status
        # Updates task to "PR READY"

PR Merged Workflow

File: .github/workflows/clickup-pr-merged.yml

Triggers when: - Pull request is merged (closed + merged = true) to develop branch

What it does: 1. Extracts ClickUp task ID from the merged branch name 2. Updates the task status to "PR MERGED" 3. Adds a merge confirmation comment with PR details 4. Timestamps the merge event in ClickUp

Environment variable:

STATUS_PR_MERGED = "pr merged"

Workflow logic:

# Simplified workflow logic
on:
  pull_request:
    types: [closed]
    branches:
      - develop

jobs:
  update-clickup:
    if: github.event.pull_request.merged == true
    # Only runs if PR was actually merged, not just closed

What happens after merge:

The workflow automatically moves your task from "PR READY" → "PR MERGED" status. Your QA team can then move tasks to "READY FOR QA" when deployment is complete.

Configuration

Setting environment variables:

  1. Go to your repository settings on GitHub
  2. Navigate to Settings → Secrets and variables → Actions → Variables
  3. Add repository variables:
  4. STATUS_PR_CREATED = "pr created"
  5. STATUS_PR_MERGED = "pr merged"

Repository secrets required:

These workflows require repository secrets to authenticate with ClickUp. Contact your tech lead to ensure these are configured properly.

For detailed ClickUp integration setup:

See GitHub-ClickUp Quick Start for complete configuration instructions.

Quality Checks Workflow

File: .github/workflows/pr-checks.yml

This workflow ensures all code changes meet quality standards before merging. It runs automated tests and enforces minimum code coverage requirements.

When It Runs

on:
  pull_request:
    branches:
      - develop
      - main

The workflow runs on every pull request to develop or main branches. It's a blocking check - your PR cannot be merged until it passes.

What It Does

The workflow runs two parallel jobs:

1. Test Job - Sets up Python environment - Installs dependencies - Runs the full pytest suite - Reports test results

2. Coverage Job - Runs pytest with coverage tracking - Enforces 75% minimum coverage - Generates coverage report - Fails if coverage is below threshold

Workflow Execution

graph TD
    A[PR Ready] --> B{pr-checks.yml}
    B --> C[Test Job]
    B --> D[Coverage Job]
    C --> E[Run pytest]
    D --> F[Run pytest --cov]
    F --> G{Coverage >= 75%?}
    G -->|Yes| H[✅ Pass]
    G -->|No| I[❌ Fail - PR blocked]
    E --> J{Tests pass?}
    J -->|Yes| H
    J -->|No| I

Running Checks Locally

Before pushing your PR, run the same checks locally:

# Run tests
pytest -v

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

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

Coverage threshold: The --cov-fail-under=75 flag ensures your local environment matches CI requirements.

Understanding Results

✅ All checks passed: 

Test job: ✓ All tests passed
Coverage job: ✓ 82% coverage (>= 75% required)

❌ Tests failed: 

Test job: ✗ 3 tests failed
Coverage job: ✓ 78% coverage
Fix the failing tests before merge.

❌ Coverage failed: 

Test job: ✓ All tests passed
Coverage job: ✗ 68% coverage (< 75% required)
Add more tests to increase coverage.

Required Secrets

This workflow requires repository secrets to be configured. These are managed by your tech lead and include database credentials, API keys, and other environment-specific values.

SonarCloud Quality Analysis

File: .github/workflows/build.yml

This workflow performs static code analysis to identify code smells, security vulnerabilities, bugs, and maintainability issues.

When It Runs

on:
  push:
    branches:
      - develop
      - main
  pull_request:
    branches:
      - develop
      - main

Runs on: - Every pull request to develop or main - Every push to develop or main branches

What It Analyzes

SonarCloud checks your code for: - Bugs: Potential runtime errors - Vulnerabilities: Security weaknesses - Code Smells: Maintainability issues - Duplications: Copy-pasted code - Test Coverage: Integration with coverage reports

Quality Gates

Quality gates are configured in the SonarCloud dashboard. Typical requirements: - No new bugs on new code - No new vulnerabilities on new code - Coverage on new code >= 75% - Code duplication < 3%

Configuration

The workflow is configured with: - SONAR_TOKEN: Authentication token (repository secret) - sonar-project.properties: Project-specific settings

Making it required:

While optional by default, we recommend adding SonarCloud as a required status check for the main branch. See the Branch Protection Setup section below.

Viewing Results

After the workflow runs: 1. Click the SonarCloud check in your PR 2. Review the detailed analysis report 3. Fix any critical or high-priority issues 4. Re-push to trigger a new analysis

Branch Protection Setup

Configure branch protection rules to enforce workflow requirements.

Develop Branch Settings

Navigate to: Settings → Branches → Branch protection rules → develop

Recommended configuration:

Require a pull request before merging: ✓
  Required approvals: 1
  Dismiss stale approvals: ✓

Require status checks to pass before merging: ✓
  Required checks:
    - test (from pr-checks.yml)
    - coverage (from pr-checks.yml)
    - SonarCloud Code Analysis (optional)
  Require branches to be up to date: ✓

Require conversation resolution before merging: ✓

Do not allow bypassing the above settings: ✓

Main Branch Settings

Navigate to: Settings → Branches → Branch protection rules → main

Recommended configuration:

Require a pull request before merging: ✓
  Required approvals: 2
  Dismiss stale approvals: ✓

Require status checks to pass before merging: ✓
  Required checks:
    - test (from pr-checks.yml)
    - coverage (from pr-checks.yml)
    - SonarCloud Code Analysis (required)
  Require branches to be up to date: ✓

Require conversation resolution before merging: ✓

Do not allow bypassing the above settings: ✓
  Include administrators: ✓

Key differences for main: - Requires 2 approvals (vs 1 for develop) - SonarCloud is required (vs optional for develop) - Includes administrators in enforcement

Troubleshooting

ClickUp Workflow Skipped

Problem: ClickUp workflow shows "skipped" status

Solution: - Check your branch name includes CU-{id} format - Verify the task ID exists in ClickUp - Ensure environment variables are set correctly (STATUS_PR_CREATED, STATUS_PR_MERGED)

Tests Failing in CI

Problem: Tests pass locally but fail in GitHub Actions

Solution: 

# Run tests in same environment
pytest -v

# Check for environment-specific issues
# - Database connections
# - File paths
# - Timezone differences

Coverage Below 75%

Problem: Coverage check fails with "Coverage too low"

Solution: 

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

# Open report to find uncovered code
open htmlcov/index.html

# Add tests for uncovered functions/branches
# Focus on new code you added

SonarCloud Failing

Problem: SonarCloud check fails or shows quality gate errors

Solution: - Click the SonarCloud check details in your PR - Review the dashboard for specific issues - Fix critical and high-priority issues first - Common fixes: - Remove code duplications - Add type hints - Fix security hotspots - Improve test coverage

Workflow Secrets Missing

Problem: Workflow fails with authentication errors

Solution: - Contact your tech lead to configure repository secrets - Verify secrets are available in the correct repository - Check secret names match workflow expectations

Force-Push After PR Ready

Problem: Force-pushed to branch, now ClickUp workflow won't run again

Solution: - Close and reopen the PR to trigger clickup-pr-created.yml again - Or manually update the ClickUp status

Questions or issues? Contact your tech lead or post in the #dev-support Slack channel.