Testapps Backend App Example

Overview

This repository contains a simple example REST Java application that demonstrates a comprehensive, enterprise-grade CI/CD pipeline built with GitHub Actions. The pipeline provides automated build, test, promotion, and deployment capabilities with a focus on proper version management, environment control, and deployment safety.

Pipeline Features

Core Capabilities

• Semantic Versioning: Automated versioning using Semantic Release with support for conventional commits
• Environment Progression: Managed promotion through dev, QA, and production environments
• Preflight Validation: Pre-deployment validation of code quality and standards
• Robust Tagging: Comprehensive Git tagging for traceability and audit
• Safety Mechanisms: Infinite loop detection and controlled workflow progression
• Multiple Execution Modes: Support for release, CI testing, and dry-run modes

Workflow Architecture

The pipeline consists of several interconnected workflows:

1. Bootstrap (bootstrap.yml)

   • Entry point for the CI/CD pipeline
   • Detects execution mode (release, ci-test, dry-run)
   • Manages semantic versioning with conventional commits
   • Establishes key pipeline variables for downstream workflows

2. Build (build.yml)

   • Handles code compilation and Docker image creation
   • Optimizes build process with intelligent caching and hash-based rebuild detection
   • Builds Maven artifacts and packages them into Docker images
   • Tags built artifacts and pushes them to container registry

3. Deploy (deploy.yml)

   • Handles deployment to specified environments
   • Performs version compatibility checks to prevent downgrades
   • Supports zero-downtime deployment with automated health checks
   • Includes automatic rollback capability on deployment failure
   • Tags deployment results for traceability

4. Environment Test (env-test.yml)

   • Validates deployed versions in target environments
   • Runs environment-specific test suites based on configurations
   • Manages test results and provides detailed reporting
   • Tags test outcomes and determines eligibility for promotion

5. Promote (promote.yml)

   • Manages the promotion of validated builds between environments
   • Implements approval workflows for production deployments
   • Ensures compliance with promotion policies and rules
   • Maintains promotion history through detailed tagging

6. Pull Request (pr.yml)

   • Enforces merge strategy using label-driven validation (squash or regular)
   • Validates commit messages against conventional commit format
   • Runs preflight checks on commits before allowing merge
   • Integrates with code review processes

7. Preflight Check (preflight-check.yml)

   • Reusable workflow for code quality validation
   • Performs validations against specified Git references
   • Verifies tags exist on the main branch
   • Runs quality checks before promotion
   • Provides consistent quality gates across workflows

8. Tag Repository (tag-git.yml)

   • Reusable workflow for standardized Git tagging
   • Manages Git tagging for traceability and audit purposes
   • Supports both annotated and lightweight tags
   • Includes optional force tagging capability
   • Maintains versioning consistency throughout the pipeline

9. Infinite Loop Detection (detect-infinite-loop.yml)

   • Safety mechanism to prevent workflow infinite loops
   • Monitors for circular workflow triggers and repetitive executions
   • Automatically cancels detected loops to prevent resource waste
   • Provides alerting for potential pipeline configuration issues

Environment Configuration

Environments are defined in devops/environments.yml with specific test requirements per environment:

• dev: Automated smoke tests, health-check
• qa: Automated smoke tests, health-checks, plus manual UAT testing
• prod: Production smoke tests and health-checks

Getting Started

Prerequisites

• Java 21
• Maven
• Git

Local Development

1. Clone the repository

   git clone https://github.com/acntech/testapps-backend-app-example.git
   cd testapps-backend-app-example
   

2. Build the application

   mvn clean package
   

3. Run preflight checks

   ./devops/scripts/preflight-check.sh
   

Pipeline Usage

Creating a Release

1. Push changes to the main branch with conventional commit messages:

   • feat: add new feature (triggers minor version bump)
   • fix: resolve issue (triggers patch version bump)
   • feat!: breaking change (triggers major version bump)

2. The pipeline will automatically:

   • Determine the new version
   • Tag the repository
   • Deploy to the dev environment
   • Run tests and promote through environments according to the defined progression

Running CI Tests

For testing changes before merging to main:

1. Push to a branch named ci/*
2. The pipeline will run in ci-test mode with a timestamp-based version
3. Applications will be deployed to the dev and qa environments with name '[app-name]-ci-test-[env]'

Manual Workflow Execution

All workflows support manual execution through the GitHub Actions UI with appropriate parameters.

Contributing

When contributing to this project:

1. Create a feature branch
2. Make your changes
3. Create a pull request with the appropriate merge strategy label:
   • merge-squash: For squashing all commits into one
   • merge-regular: For preserving the commit history

Security Features

The pipeline includes several security-focused features:

• Personal Access Token (PAT) support for privileged operations
• Controlled environment access
• Pre-deployment validation
• Automatic infinite loop detection

Testing

The repository includes test scripts for various environments in the devops/tests directory.

---

This is an example application demonstrating enterprise CI/CD patterns with GitHub Actions.