Tutorial: ci-cd

ci-cd

CI/CD & Quality Assurance

Automated pipelines are essential for maintaining the health of a modern micro-service. We use GitHub Actions and Codecov to automate our Quality Assurance (QA) processes.

GitHub Actions CI

Our CI workflow (defined in .github/workflows/ci.yml) is triggered on every push and pull request to the main branch.

Cross-Version Testing

We test our service against all currently supported Node.js LTS versions:

  • Node.js 20
  • Node.js 22
  • Node.js 24

This ensures that our dependencies and code are compatible with different environments.

The Pipeline Steps

  1. Checkout: Pull the source code.
  2. Setup Node.js: Install the specific Node.js version and cache dependencies.
  3. Install: Run npm ci for a clean, reproducible installation.
  4. Test: Run the full test suite (npm test), including integration tests with Testcontainers.
  5. Coverage: If the tests pass on the "main" version (Node.js 24), the coverage report is uploaded.

Code Coverage with Codecov

We use Codecov to visualize and track our code coverage over time.

  • Why?: It provides a clear dashboard to see which lines of code are missing tests and helps ensure that PRs don't lower the overall coverage.
  • Integration: The codecov/codecov-action in our CI pipeline automatically uploads the results generated by Jest.

Documentation Deployment

The documentation you are reading now is also automatically deployed using GitHub Actions. Whenever changes are pushed to the docs/ folder, a dedicated workflow (.github/workflows/deploy-docs.yml) builds and publishes the site to GitHub Pages.

Enabling GitHub Pages (Crucial Step)

To make the documentation deployment work, you must ensure that GitHub Pages is enabled in your repository. If you encounter a "Get Pages site failed" or "HttpError: Not Found" in your Actions logs, it is almost certainly because this step was skipped.

  1. Go to your repository Settings.
  2. Select Pages from the sidebar.
  3. Under Build and deployment > Source, ensure GitHub Actions is selected.

Educational Note: The default GITHUB_TOKEN used by GitHub Actions does not have administrative permissions to automatically enable GitHub Pages. This is why manual activation is required. Understanding the permission boundaries of automated tools and knowing how to configure platform settings in the UI are fundamental skills for DevOps and CI/CD engineers.

Why automate?

  • Prevention: Catch bugs and breaking changes before they reach production.
  • Consistency: Ensure that every change meets the same high quality standards.
  • Efficiency: Save developer time by automating repetitive testing and deployment tasks.