Why CI/CD?
Before we dive into the setup, let’s briefly cover why CI/CD is so critical:
- Automated Testing: Running tests automatically ensures code is stable with every change.
- Consistency: CI/CD enforces standards (linting, formatting) across the codebase.
- Reliability: Automated checks and tests minimize human error and improve code reliability.
- Rapid Feedback: Developers receive immediate feedback on code quality, allowing issues to be caught early.
In ReadmeGenie, we leveraged GitHub Actions as our CI/CD tool. It integrates smoothly with GitHub repositories and offers flexibility and automation through YAML configuration files.
The CI/CD Pipeline for ReadmeGenie
Our CI/CD pipeline includes the following automated steps:
- Linting and Formatting Checks: We run Ruff and Black to ensure code style and consistency.
-
Unit Testing: We use
unittest
to verify that code changes don’t break existing functionality. - Coverage Analysis: We use Coverage.py to ensure that the code meets our coverage threshold before a commit is allowed.
- Pre-Commit Hooks: We added hooks to enforce local quality checks before pushing changes.
Overview of the GitHub Actions Workflow
The CI workflow is defined in .github/workflows/python-app.yml
. Here’s a breakdown of what each part of the workflow does:
1. Triggering the Workflow
The workflow runs on every push and pull request to the main
branch. This ensures that all code changes undergo validation before merging into production.
name: Python application
on:
push:
branches: ["main"]
pull_request:
branches: ["main"]
2. Setting Up the Python Environment
We configure GitHub Actions to use Python 3.12.x, ensuring consistency with our local development environment. This step installs the specific Python version and prepares the environment for dependency installation.
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python 3.12.x
uses: actions/setup-python@v3
with:
python-version: "3.12.x"
3. Installing Dependencies
The next step is to install project dependencies. Here, we upgrade pip
and install requirements.txt
file, it will install additional dependencies specified there.
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install flake8 pytest
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
4. Running Linting and Code Quality Checks
Linting is a crucial part of our workflow, ensuring the code adheres to specified quality standards. We run flake8 with options to flag syntax errors, undefined names, and complexity issues.
- name: Lint with flake8
run: |
# stop the build if there are Python syntax errors or undefined names
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
5. Running Tests with Coverage Analysis
For unit tests, we use pytest
to run all test cases. Additionally, we use coverage
to track which lines of code are tested, ensuring that our test suite meets the defined coverage threshold of 75%.
The following commands run the tests and generate a coverage report, highlighting any gaps in test coverage. This is essential for quality assurance, as untested code is a potential source of future bugs.
- name: Test with pytest
run: |
pytest
- name: Test functions and coverage
run: |
coverage run --source=. -m unittest discover -s tests
coverage report -m --fail-under=75
This coverage check ensures a high standard of code quality by enforcing that at least 75% of the codebase is covered by tests. If coverage falls below this threshold, the commit will not be allowed.
Integrating Pre-Commit Hooks
In addition to CI/CD, we set up pre-commit hooks to enforce code quality locally before any changes are pushed to the repository. These hooks:
- Run Ruff for linting and Black for formatting.
- Enforce a minimum coverage threshold by running the tests with coverage locally.
Here’s how we added the coverage check as a pre-commit hook in .pre-commit-config.yaml
:
repos:
- repo: local
hooks:
- id: check-coverage
name: Check Coverage
entry: bash -c "coverage run --source=. -m unittest discover -s tests && coverage report -m --fail-under=75"
language: system
Challenges and Lessons Learned
Setting up CI/CD required a deep understanding of how different tools (flake8, pytest, coverage) interact within GitHub Actions. Here are some challenges we faced and the solutions we implemented:
Handling Divergent Local and Remote Configurations
We encountered issues with environment variable conflicts, especially in testing API integration and configuration handling. Using @patch.dict
and other mocking techniques in unittest
allowed us to simulate the environment effectively.
Testing Coverage and Thresholds
The biggest challenge was ensuring adequate test coverage. Using coverage.py
with --fail-under=75
in both GitHub Actions and pre-commit hooks helped enforce this standard.
Future Improvements
To make the CI/CD pipeline more robust, we plan to:
- Add Deployment Stages: Automate deployment to a staging or production environment after tests pass.
- Automate Code Quality Badges: Add dynamic badges to display coverage, linting status, and test results in the README.
- Expand Coverage Requirements: Increase the coverage threshold as we improve tests and cover more edge cases.
Takeaway
Through this project, I realized the importance of establishing robust testing and CI/CD practices early on. If I were to start again, I’d focus on writing comprehensive tests from the beginning and incrementally expanding and improving them as the project progresses. This approach would prevent missing branches or untested areas and ensure that all new code integrates smoothly into a well-covered codebase.
Top comments (0)