Skip to Content
🚀 Gentoro OneMCP is open source!
DocumentationReferenceCI/CD Pipeline

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment. The pipeline provides comprehensive testing across all components and platforms.

Pipeline Stages

The CI/CD pipeline consists of three main stages:

1. Unit Tests

Fast feedback for code quality across the core Java service.

Trigger: Every push and pull request.

2. Build & Service Validation

Build artifacts and validate full system deployment:

  • Builds the OneMCP Java application
  • Builds the CLI package
  • Verifies the service can start successfully

Status: Optional (resilient to transient failures)

3. Docker Build & Container Validation

Build and test containerized deployment:

  • Builds Docker images for both AMD64 and ARM64
  • Validates container functionality on both architectures
  • Exercises the container entrypoint
  • Verifies multi-platform compatibility

Platforms: linux/amd64, linux/arm64

Pipeline Features

Multi-platform Support

The pipeline tests both AMD64 and ARM64 architectures to ensure compatibility across different deployment environments (cloud servers, Apple Silicon, etc.).

Resilient Design

Integration and service validation stages are optional to prevent external dependency failures from blocking the entire pipeline. Critical stages (unit tests, Docker build) are required.

Artifact Management

Build artifacts are shared between stages for efficiency:

  • Java JARs are built once and reused
  • Node.js packages are cached
  • Docker layers are cached for faster builds

Container Validation

Automated testing of Docker container functionality:

  • Service startup validation
  • Health check verification
  • Inter-service communication testing
  • Process mode validation (validate, regression, etc.)

Running Locally

To run the same tests that run in CI/CD locally:

Unit Tests

cd packages/server && mvn test

Service Validation

Installing OneMCP CLI in CI/CD:

# Download CLI binary (Linux AMD64)
curl -LO https://github.com/Gentoro-OneMCP/onemcp/releases/download/cli-v0.0.3/onemcp-linux-amd64.tar.gz
tar -xzf onemcp-linux-amd64.tar.gz
sudo mv onemcp /usr/local/bin/
 
# Verify installation
onemcp --help
 
# Check system requirements
onemcp doctor

Running validation:

# Start OneMCP server (Docker required)
onemcp chat <<EOF
Show total sales for 2024
exit
EOF
 
# Check server status
onemcp status
 
# View logs if needed
onemcp logs

Container Validation

# Build Docker images
./scripts/docker/build-base.sh latest
./scripts/docker/build-product.sh latest
 
# Validate containers
./scripts/docker/validate-containers.sh latest linux/amd64
 
# For ARM64 (on Apple Silicon)
./scripts/docker/validate-containers.sh latest linux/arm64

CI/CD Best Practices

Pull Request Workflow

  1. Create feature branch: git checkout -b feature/my-feature
  2. Make changes and commit: Follow conventional commit format
  3. Push and create PR: CI pipeline runs automatically
  4. Review results: Check all stages pass
  5. Merge after approval: Squash and merge to main

Commit Message Format

Follow Conventional Commits :

feat(component): add new feature
fix(component): fix bug
docs(component): update documentation
test(component): add tests
chore(component): maintenance tasks

Examples:

feat(agent): add support for Claude 3.5 Sonnet
fix(app): resolve MCP response parsing error
docs(guides): add foundation validation guide
test(integration): add MCP endpoint integration tests

Debugging Pipeline Failures

Unit Test Failures

# Run tests locally with verbose output
cd packages/server && mvn test -X
 
# Run specific test
mvn test -Dtest=MyTestClass#myTestMethod

Service Validation Failures

# Tail OneMCP service logs
onemcp logs app -f
 
# Run service validation with debug logging
cd packages/server && mvn test -Dtest="*IntegrationTest" -X

Docker Build Failures

# Build with verbose output
docker build --progress=plain -f Dockerfile .
 
# Check specific platform
docker buildx build --platform linux/amd64 -f Dockerfile .

Container Validation Failures

# Run validation with debug mode
./scripts/docker/validate-containers.sh latest linux/amd64 --debug
 
# Check container logs
docker logs <container-id>
 
# Interactive shell for debugging
docker run -it --entrypoint /bin/bash admingentoro/gentoro:latest

GitHub Actions Configuration

The pipeline is defined in .github/workflows/ directory:

  • ci.yml - Main CI/CD pipeline
  • deploy-docs.yml - Documentation deployment

Secrets Required

Configure these secrets in GitHub repository settings:

  • OPENAI_API_KEY - For integration tests (optional)
  • GEMINI_API_KEY - For integration tests (optional)
  • ANTHROPIC_API_KEY - For integration tests (optional)
  • DOCKER_HUB_USERNAME - For Docker image publishing
  • DOCKER_HUB_TOKEN - For Docker image publishing

Environment Variables

Configure these in GitHub Environments:

  • NEXT_PUBLIC_GTM_ID - Google Tag Manager ID for docs site

Monitoring and Metrics

Pipeline Metrics

Track these metrics to monitor pipeline health:

  • Build time: Total time for all stages
  • Success rate: Percentage of successful runs
  • Flaky tests: Tests that fail intermittently
  • Cache hit rate: Docker layer and dependency cache effectiveness

Viewing Results

  • GitHub Actions: Repository → Actions tab
  • Test Reports: Available as artifacts in each run
  • Coverage Reports: Published to workflow summary
  • Docker Image Tags: Check Docker Hub for published images

Next Steps

Last updated on
Java Packages