Skip to main content

​
Overview

This project uses GitHub Actions to automate continuous integration, testing, and security scanning. All workflows are located in .github/workflows/ and trigger automatically on relevant events.
Workflows run automatically on push and pull request events to ensure code quality and security before merging.

​
Available Workflows

​
CI Workflow

The primary CI workflow (ci.yml) runs on every push to main and on all pull requests. It handles installation, linting, testing, and security checks for Python projects. Triggers:
  • Push to main branch
  • Pull requests targeting main branch
What it does:
1

Checkout Code

Uses actions/checkout@v4 to clone the repository
2

Setup Python

Installs Python 3.12 using actions/setup-python@v5
3

Install Dependencies

Upgrades pip and wheel, then installs project dependencies from pyproject.toml with dev extras
4

Run Quality Checks

Executes multiple tools:
  • Ruff: Fast Python linter
  • Black: Code formatter verification
  • Mypy: Static type checking
  • Pytest: Unit tests with coverage
  • Bandit: Security issue scanner
  • Safety: Dependency vulnerability checker
name: CI
on:
  push: { branches: [ main ] }
  pull_request: { branches: [ main ] }
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install
        run: |
          python -m pip install -U pip wheel
          if [ -f pyproject.toml ]; then pip install -e ".[dev]" || true; fi
      - name: Lint/Test (Python)
        run: |
          if [ -f pyproject.toml ]; then
            pip install ruff black mypy pytest pytest-cov bandit safety || true
            ruff check . || true
            black --check . || true
            mypy src/ || true
            pytest || true
            bandit -r src/ || true
            safety check -r <(pip freeze) --full-report || true
          else
            echo "No pyproject found. Skipping python checks."
          fi
The CI workflow uses || true to prevent failures from blocking the pipeline during initial setup. For production use, remove these to enforce quality gates.

​
Security Workflow

The security workflow (security.yml) provides additional security scanning using Trivy to detect vulnerabilities in Docker images. Triggers:
  • Pull requests targeting main branch
What it does:
1

Checkout Code

Clones the repository for scanning
2

Build Docker Image

Builds a Docker image from the Dockerfile if one exists, tagged as local/test:pr
3

Scan with Trivy

Runs Aqua Security’s Trivy scanner to detect:
  • Critical and high severity vulnerabilities
  • Security issues in base images and dependencies
  • Common misconfigurations
name: Security checks
on:
  pull_request: { branches: [ main ] }
jobs:
  trivy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build image if Dockerfile exists
        uses: docker/build-push-action@v6
        with:
          context: .
          push: false
          load: true
          tags: local/test:pr
      - name: Trivy image scan
        if: hashFiles('Dockerfile') != ''
        uses: aquasecurity/[email protected]
        with:
          image-ref: local/test:pr
          format: table
          exit-code: '0'
          ignore-unfixed: true
          severity: 'CRITICAL,HIGH'
The security workflow only runs if a Dockerfile exists in your repository. It’s automatically skipped for non-containerized projects.

​
Customizing Workflows

​
Adding New Jobs

To add a new job to the CI workflow, extend the jobs section: 
jobs:
  ci:
    # ... existing CI job
  
  deploy:
    runs-on: ubuntu-latest
    needs: ci  # Wait for CI to pass
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: |
          # Your deployment commands

​
Changing Python Version

Update the Python version in .github/workflows/ci.yml:12: 
- uses: actions/setup-python@v5
  with:
    python-version: "3.11"  # Change from 3.12

​
Adding More Security Scans

Extend the security workflow with additional scanners: 
- name: Run Snyk
  uses: snyk/actions/python@master
  env:
    SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}

​
Configuring Branch Protection

To require workflows to pass before merging:
1

Navigate to Settings

Go to your repository Settings → Branches
2

Add Branch Protection Rule

Click “Add rule” for the main branch
3

Enable Status Checks

Check “Require status checks to pass before merging” and select:
  • ci
  • trivy
4

Save Changes

Click “Create” or “Save changes” to enforce the rules

​
Troubleshooting

The mypy static type checker may fail if type hints are missing or incorrect. To fix:
  1. Add type hints to your functions
  2. Configure mypy in pyproject.toml:
[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false
When Trivy detects vulnerabilities:
  1. Review the scan output in the Actions tab
  2. Update base images in your Dockerfile
  3. Update vulnerable dependencies
  4. For unfixed vulnerabilities, document accepted risks
Note: ignore-unfixed: true skips vulnerabilities without available patches.
If workflows exceed the timeout limit:
  1. Add caching for dependencies:
- uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
  1. Parallelize jobs using matrix strategies
  2. Optimize test execution time

​
Workflow Badges

Add status badges to your README to display workflow status: 
![CI](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/ci.yml/badge.svg)
![Security](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/security.yml/badge.svg)
Replace YOUR_ORG and YOUR_REPO with your repository details.

​
Best Practices

Fast Feedback

Run fastest checks first (linting) before slower ones (tests)

Fail Fast

Remove || true from checks to catch issues early

Cache Dependencies

Use actions/cache to speed up subsequent runs

Secure Secrets

Store sensitive data in GitHub Secrets, never in code

Build docs developers (and LLMs) love

Get started for freeTalk to us