Skip to content

CI_CD_GUIDE.md

Latest commit

 

History

History
368 lines (261 loc) · 9.24 KB

CI_CD_GUIDE.md

File metadata and controls

368 lines (261 loc) · 9.24 KB
Raw

CI/CD Guide for predict4java

Overview

The predict4java project uses GitHub Actions for continuous integration and deployment. This guide explains the CI/CD setup, workflows, and how to work with them.

Workflows

1. Java CI with Maven (maven-ci.yml)

Triggers:

  • Push to master branch
  • Pull requests to master branch

Jobs:

Test Job

  • Purpose: Run unit tests across multiple Java versions
  • Java Versions: 11, 17, 21
  • Steps:
    1. Checkout code
    2. Set up JDK
    3. Run tests with mvn clean test
    4. Generate JaCoCo coverage report (Java 11 only)
    5. Upload coverage to Codecov (Java 11 only)

Why multiple Java versions?

  • Java 11: Minimum supported version (project baseline)
  • Java 17: Current LTS version
  • Java 21: Latest LTS version

This ensures compatibility across all supported Java versions.

Quality Job

  • Purpose: Run code quality checks
  • Java Version: 11 (baseline)
  • Steps:
    1. Checkout code
    2. Set up JDK 11
    3. Run Checkstyle (mvn checkstyle:check)
    4. Run SpotBugs (mvn compile spotbugs:check)
    5. Generate quality reports (mvn site)

Note: Quality checks use continue-on-error: true to allow builds to complete even with style violations. This is appropriate for scientific code with many mathematical constants.

Build Job

  • Purpose: Build final artifacts and verify
  • Java Version: 11 (baseline)
  • Dependencies: Requires test and quality jobs to complete
  • Steps:
    1. Checkout code
    2. Set up JDK 11
    3. Build with mvn clean package
    4. Verify JAR files exist
    5. Upload build artifacts (retained for 30 days)

Artifacts Generated:

  • predict4java-1.2.0.jar - Main library
  • predict4java-1.2.0-sources.jar - Source code
  • predict4java-1.2.0-javadoc.jar - API documentation

2. CodeQL Analysis (codeql-analysis.yml)

Triggers:

  • Push to master branch
  • Pull requests to master branch
  • Scheduled: Every Friday at 5:00 AM UTC

Purpose: Security vulnerability scanning

Steps:

  1. Checkout code
  2. Initialize CodeQL
  3. Autobuild project
  4. Perform security analysis

Coverage Reporting

Codecov Integration

The project uses Codecov for coverage tracking and visualization.

Setup:

  1. Sign up at https://codecov.io/
  2. Add the repository
  3. Get the upload token
  4. Add token to GitHub Secrets as CODECOV_TOKEN

Coverage Badge:

[![codecov](https://codecov.io/gh/g4dpz/predict4java/branch/master/graph/badge.svg)](https://codecov.io/gh/g4dpz/predict4java)

Current Coverage:

  • Instruction Coverage: 94%
  • Branch Coverage: 78%
  • Total Tests: 149

Viewing Coverage Reports

Locally:

mvn clean test jacoco:report
open target/site/jacoco/index.html

On Codecov: Visit https://codecov.io/gh/g4dpz/predict4java

Dependency Management

Dependabot Configuration

Dependabot automatically checks for dependency updates and creates pull requests.

Configuration (.github/dependabot.yml):

  • Maven Dependencies: Checked weekly on Mondays
  • GitHub Actions: Checked weekly on Mondays
  • PR Limits: 5 for Maven, 3 for GitHub Actions

Labels Applied:

  • dependencies - All dependency updates
  • maven - Maven dependency updates
  • github-actions - GitHub Actions updates

Commit Message Format:

  • Maven: chore(deps): update dependency-name to version
  • Actions: ci(deps): update action-name to version

Reviewing Dependabot PRs

  1. Check the PR description for changelog and compatibility notes
  2. Review the diff to understand what changed
  3. Wait for CI checks to pass
  4. Merge if all tests pass and changes are compatible

Build Status Badges

Add these badges to your README.md:

[![Build Status](https://github.com/g4dpz/predict4java/workflows/Java%20CI%20with%20Maven/badge.svg)](https://github.com/g4dpz/predict4java/actions)
[![codecov](https://codecov.io/gh/g4dpz/predict4java/branch/master/graph/badge.svg)](https://codecov.io/gh/g4dpz/predict4java)

Local Development

Running Tests Locally

# Run all tests
mvn clean test

# Run specific test
mvn test -Dtest=PassPredictorTest

# Run tests with coverage
mvn clean test jacoco:report

Running Quality Checks Locally

# Checkstyle
mvn checkstyle:check

# SpotBugs
mvn compile spotbugs:check

# All quality reports
mvn site

Building Locally

# Build without tests
mvn clean package -DskipTests

# Build with all checks
mvn clean verify

# Build release artifacts (requires GPG)
mvn clean package -P release

Troubleshooting

Test Failures

Issue: Tests fail intermittently Solution: Check for race conditions or timing-dependent tests

Issue: ThreadSafetyTest fails intermittently Solution: The flaky test has been removed from the suite

Build Failures

Issue: Checkstyle violations fail the build Solution: Checkstyle is configured with failsOnError=false. Check the report and fix critical issues.

Issue: SpotBugs errors Solution: Review the SpotBugs report and fix legitimate bugs. Some false positives can be suppressed.

Coverage Issues

Issue: Coverage not uploading to Codecov Solution:

  1. Verify CODECOV_TOKEN is set in GitHub Secrets
  2. Check the workflow logs for upload errors
  3. Ensure JaCoCo report is generated before upload

Issue: Coverage decreased Solution: Add tests for uncovered code paths. Focus on branch coverage.

CI/CD Best Practices

For Contributors

  1. Run tests locally before pushing
  2. Check code style with Checkstyle
  3. Review coverage for new code
  4. Wait for CI to pass before requesting review
  5. Fix failing tests immediately

For Maintainers

  1. Review CI logs for warnings
  2. Monitor coverage trends on Codecov
  3. Keep dependencies updated via Dependabot
  4. Address security alerts from CodeQL
  5. Maintain build speed by optimizing tests

Workflow Customization

Adding New Java Versions

Edit .github/workflows/maven-ci.yml:

strategy:
  matrix:
    java: [ '11', '17', '21', '23' ]  # Add new version

Changing Test Frequency

Edit the workflow triggers:

on:
  push:
    branches: [ master, develop ]  # Add branches
  pull_request:
    branches: [ master ]
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM

Adding Quality Gates

Add to the build job:

- name: Check coverage threshold
  run: |
    mvn jacoco:check \
      -Djacoco.haltOnFailure=true \
      -Djacoco.instructionRatio=0.90 \
      -Djacoco.branchRatio=0.75

Secrets Management

Required Secrets

Add these in GitHub Settings → Secrets and variables → Actions:

Secret Purpose How to Get
CODECOV_TOKEN Upload coverage reports https://codecov.io/
OSSRH_USERNAME Maven Central deployment https://issues.sonatype.org/
OSSRH_PASSWORD Maven Central deployment https://issues.sonatype.org/
GPG_PRIVATE_KEY Sign artifacts gpg --export-secret-keys
GPG_PASSPHRASE Unlock GPG key Your GPG passphrase

Adding Secrets

# Via GitHub CLI
gh secret set CODECOV_TOKEN

# Via GitHub Web UI
# Settings → Secrets and variables → Actions → New repository secret

Performance Metrics

Current Build Times

  • Test Job (per Java version): ~2-3 minutes
  • Quality Job: ~3-4 minutes
  • Build Job: ~2-3 minutes
  • Total Pipeline: ~5-7 minutes (parallel execution)

Optimization Tips

  1. Use caching: Maven dependencies are cached automatically
  2. Parallel execution: Jobs run in parallel when possible
  3. Skip unnecessary steps: Use -DskipTests for non-test builds
  4. Fail fast: Set fail-fast: false to see all failures

Monitoring and Alerts

GitHub Actions Dashboard

View workflow runs: https://github.com/g4dpz/predict4java/actions

Filters:

  • By workflow: Select specific workflow
  • By branch: Filter by branch name
  • By status: Success, failure, in progress

Email Notifications

GitHub sends emails for:

  • Failed workflow runs on your commits
  • Failed scheduled workflows
  • Security alerts from CodeQL

Configure: Settings → Notifications → Actions

Release Process

Automated Checks

Before releasing, ensure:

  1. ✅ All CI checks pass
  2. ✅ Coverage meets thresholds (94% instruction, 78% branch)
  3. ✅ No security vulnerabilities from CodeQL
  4. ✅ All Dependabot PRs reviewed
  5. ✅ Build artifacts generated successfully

Manual Release Steps

See DEPLOYMENT_GUIDE.md for Maven Central deployment.

Support

Getting Help

  • Workflow Issues: Check GitHub Actions logs
  • Test Failures: Review test output and coverage reports
  • Build Problems: Check Maven output and dependency tree
  • Security Alerts: Review CodeQL findings

Useful Links

Conclusion

The CI/CD pipeline ensures code quality, test coverage, and build reliability. All checks run automatically on every push and pull request, providing fast feedback to developers.

For questions or issues, open a GitHub issue or contact dave@g4dpz.me.uk.