Compare commits

...
10 Commits
Author SHA1 Message Date
james.maes 342646a856 docs: update README for machine executor and Docker support 2025-12-28 11:29:06 -06:00
james.maes c43666fb4c feat: switch to machine executor for Docker support
Replace cimg/openjdk Docker executor with Ubuntu machine executor
that has native Docker support. This enables Testcontainers and
LocalStack Docker extension tests to run properly in CI.

- Create install_java command to install Temurin JDK and Maven
- Add optional Node.js installation for frontend builds
- Update all Maven jobs to use machine executor
2025-12-28 11:15:06 -06:00
james.maes eff82e0ffd revert: remove setup_remote_docker (not needed) 2025-12-28 08:56:46 -06:00
james.maes a1c797d897 feat: add setup_remote_docker for Docker-dependent tests 2025-12-28 08:46:14 -06:00
james.maes 76f37ad23a build(claude): added settings 2025-12-28 08:33:16 -06:00
james.maes b1523223d0 Merge main into develop 2025-12-28 08:32:17 -06:00
james.maes 09db303b9b fix(git): use CircleCI checkout for SSH/known_hosts handling 2025-12-28 08:31:35 -06:00
james.maes eedc21aeff fix(git): add GitHub SSH host key before clone 2025-12-28 08:23:58 -06:00
james.maes f23015ff1e fix(orb): update URLs to valid QRun-IO GitHub repo 2025-12-28 08:22:31 -06:00
james.maes b4a6aa0d4c docs: update for v0.4.0 release
- Add CHANGELOG entry for v0.4.0
- Update README to follow QQQ repo standards
- Add CLAUDE.md for Claude Code guidance
2025-12-28 08:15:58 -06:00
13 changed files with 312 additions and 128 deletions

No files matched your search

+27
View File
@@ -0,0 +1,27 @@
{
"permissions": {
"allow": [
"mcp__github__get_pull_request",
"Bash(gh release view:*)",
"Bash(gh release list:*)",
"Bash(gh api:*)",
"Bash(gh release:*)",
"mcp__github__get_file_contents",
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git checkout:*)",
"Bash(git merge:*)",
"Bash(git push:*)",
"mcp__circleci-mcp-server__get_build_failure_logs",
"mcp__circleci-mcp-server__get_latest_pipeline_status",
"WebFetch(domain:app.circleci.com)",
"mcp__circleci-mcp-server__get_job_test_results",
"Bash(curl:*)",
"Bash(make validate:*)",
"Bash(circleci orb publish:*)",
"Bash(git reset:*)",
"Bash(git pull:*)",
"Bash(git fetch:*)"
]
}
}
+20
View File
@@ -5,6 +5,26 @@ All notable changes to QQQ Orb will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.4.0] - 2025-12-28
### Added
- Java 21 support with configurable executor - New `java` executor using `cimg/openjdk` with version parameter (default: 21.0)
- Automatic GitHub release creation for releases and release candidates
- RC support for GitHub releases (published as pre-releases)
### Changed
- License changed to AGPL-3.0 with QRun-IO copyright
- Maven jobs now use the new `java` executor (resource_class: large)
- Node jobs use `default` executor with configurable version
### Fixed
- Version calculation now uses `CIRCLE_BRANCH` environment variable before falling back to git ref parsing
- Frontend build cache steps separated by key for proper cache isolation
- npm module cache now properly saved in frontend builds
### Migration
Projects needing Java 17 can explicitly set `java_version: "17.0"` in their workflow config.
## [0.3.8] - 2025-09-29
### Added
+82
View File
@@ -0,0 +1,82 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
CircleCI orb for QQQ framework projects. Provides pre-built jobs for building, testing, and publishing Maven and Node.js projects using GitFlow branching strategy.
## Build Commands
```bash
make pack # Pack orb to target/qqq-orb-packed.yml
make validate # Pack and validate orb
make test # Pack and validate (alias for validate)
make test-scripts # Run calculate_version.sh test suite
make test-all # Run all tests (orb + scripts)
make lint # Run yamllint, shellcheck, and CircleCI validation
make dev # Development workflow: pack, validate, show status
make clean # Remove target/ and tests/test_data/
make publish-snapshot # Publish to kingsrook/qqq-orb@dev:snapshot
make publish-release # Interactive production release with git tagging
```
## Running Individual Tests
```bash
./tests/run_tests.sh # Standard test run
./tests/run_tests.sh --verbose # Verbose output
./tests/run_tests.sh --ci # CI mode (minimal output)
./tests/test_calculate_version.sh # Direct test suite execution
```
## Architecture
### Directory Structure
- `src/@orb.yml` - Main orb definition entry point
- `src/commands/` - Reusable orb commands (YAML files that include scripts)
- `src/jobs/` - Complete job definitions combining commands
- `src/executors/` - Docker executor definitions (java.yml, default.yml)
- `src/scripts/` - Bash scripts included in commands
- `tests/` - Test suite for calculate_version.sh
### Key Components
**Executors:**
- `java` - cimg/openjdk image with configurable version (17.0, 21.0), resource_class: large
- `default` - cimg/node image for Node.js projects
**Jobs:**
- `mvn_publish` - Full publish workflow (build, version, test, deploy, git ops, GitHub release)
- `mvn_test_only` - Build and test for feature branches
- `mvn_frontend_publish` / `mvn_frontend_test_only` - Same with frontend support
- `node_publish` / `node_test_only` - Pure Node.js workflows
**Version Calculation:**
The core logic is in `src/scripts/calculate_version.sh`. It determines version based on branch type:
- `develop` -> `X.Y.Z-SNAPSHOT`
- `release/*` -> `X.Y.Z-RC.N`
- `main` (tagged) -> `X.Y.Z`
- `hotfix/*` -> Patch version bump
- `feature/*` -> `X.Y.Z-feature-{name}-{hash}-SNAPSHOT`
### Orb Packing
The orb uses CircleCI's "unpacked" format. YAML files in `src/` are packed into a single `target/qqq-orb-packed.yml`. Commands reference scripts via `<<include(scripts/scriptname.sh)>>` syntax.
### CI Pipeline
`.circleci/config.yml` runs lint/pack/review/shellcheck, then continues to `.circleci/test-deploy.yml` which runs command tests and publishes on release tags (`v*.*.*`).
## Linting Requirements
- YAML: yamllint for commands/jobs/examples
- Shell: shellcheck for all .sh files in src/scripts/ and tests/
- Orb: `circleci orb validate` for orb syntax
## Required Context Variables for Publishing
- `MAVEN_USERNAME`, `MAVEN_PASSWORD` - Sonatype credentials
- `GPG_PRIVATE_KEY_B64`, `GPG_KEYNAME`, `GPG_PASSPHRASE` - GPG signing
- `GITHUB_TOKEN` - GitHub API access
+39 -85
View File
@@ -2,8 +2,8 @@
CircleCI orb for QQQ framework projects.
**For:** Teams using CircleCI to build, test, and publish QQQ applications
**Status:** Stable (v0.3.8)
**For:** Teams using CircleCI to build, test, and publish QQQ applications
**Status:** Stable (v0.4.0)
## Why This Exists
@@ -13,40 +13,34 @@ This orb provides pre-built jobs for the complete QQQ development lifecycle. Add
## Features
- **Maven and npm Support** - Builds Java and Node.js projects
- **GitFlow Integration** - Automated versioning based on branch type
- **Publishing Automation** - Maven Central and npm registry publishing
- **Test Coverage** - JaCoCo integration with coverage reporting
- **Version Calculation** - Semantic versioning with SNAPSHOT, RC, and release support
- **Maven and npm support** - Builds Java and Node.js projects
- **Docker-native execution** - Machine executor with Docker pre-installed for Testcontainers/LocalStack
- **GitFlow integration** - Automated versioning based on branch type
- **Publishing automation** - Maven Central and npm registry publishing
- **Test coverage** - JaCoCo integration with coverage reporting
- **Version calculation** - Semantic versioning with SNAPSHOT, RC, and release support
- **Java 21 default** - Temurin JDK with configurable version (17, 21)
## Quick Start
### Prerequisites
- CircleCI account
- Repository connected to CircleCI
- `qqq-maven-registry-credentials` context with publishing credentials
### Basic Configuration
**Prerequisites:** CircleCI account, repository connected to CircleCI
```yaml
# .circleci/config.yml
version: 2.1
orbs:
qqq-orb: kingsrook/qqq-orb@2.1
qqq-orb: qrun-io/qqq-orb@0.4
workflows:
build_and_test:
jobs:
- qqq-orb/build
- qqq-orb/test:
requires: [qqq-orb/build]
- qqq-orb/mvn_test_only
publish_snapshot:
when:
equal: [develop, << pipeline.git.branch >>]
jobs:
- qqq-orb/publish:
- qqq-orb/mvn_publish:
context: qqq-maven-registry-credentials
branch_type: snapshot
```
@@ -57,9 +51,12 @@ workflows:
| Job | Purpose |
|-----|---------|
| `build` | Compile project |
| `test` | Run tests with coverage |
| `publish` | Build and publish artifacts |
| `mvn_test_only` | Build and test Maven projects |
| `mvn_publish` | Build, test, and publish Maven artifacts |
| `mvn_frontend_test_only` | Build and test Maven projects with npm frontend |
| `mvn_frontend_publish` | Build, test, and publish Maven projects with npm frontend |
| `node_test_only` | Build and test Node.js projects |
| `node_publish` | Build, test, and publish Node.js packages |
### Branch Types
@@ -71,48 +68,19 @@ workflows:
| `hotfix/1.5.1` | `1.5.1` |
| `feature/*` | `1.5.0-feature-abc1234-SNAPSHOT` |
### Full GitFlow Configuration
### Java Version
Maven jobs run on Ubuntu machine executors with Temurin JDK. Default is Java 21. To use Java 17:
```yaml
workflows:
test_only:
when:
not:
or:
- equal: [develop, << pipeline.git.branch >>]
- equal: [main, << pipeline.git.branch >>]
- matches: { pattern: "^release/.*", value: << pipeline.git.branch >> }
jobs:
- qqq-orb/build
- qqq-orb/test:
requires: [qqq-orb/build]
publish_snapshot:
when:
equal: [develop, << pipeline.git.branch >>]
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: snapshot
publish_release_candidate:
when:
matches: { pattern: "^release/.*", value: << pipeline.git.branch >> }
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: release_candidate
publish_release:
when:
equal: [main, << pipeline.git.branch >>]
jobs:
- qqq-orb/publish:
context: qqq-maven-registry-credentials
branch_type: release
jobs:
- qqq-orb/mvn_test_only:
java_version: "17"
```
## Configuration
### Docker Support
Maven jobs use machine executors with Docker pre-installed. Tests using Testcontainers, LocalStack, or other Docker-dependent frameworks work without additional configuration.
### Required Context Variables
@@ -125,40 +93,26 @@ workflows:
| `GPG_PASSPHRASE` | GPG passphrase |
| `GITHUB_TOKEN` | GitHub API token |
### Project Requirements
Maven projects need a `pom.xml` with a `<revision>` property. The orb updates this property during builds.
## Development
```bash
# Validate orb
make validate
# Run tests
make test-all
# Publish dev version
make publish-snapshot
```
## Project Status
Stable and used across all QQQ repositories.
### Roadmap
**Maturity:** Stable, used across all QQQ repositories
**Breaking changes:** See [CHANGELOG.md](CHANGELOG.md)
**Roadmap:**
- GitHub Actions support
- Parallel test execution
- Container image publishing
## Contributing
1. Fork the repository
2. Create a feature branch
3. Run `make test-all`
4. Submit a pull request
```bash
git clone git@github.com:QRun-IO/qqq-orb.git
cd qqq-orb
make test-all
```
See [QQQ Contribution Guidelines](https://github.com/Kingsrook/qqq/blob/develop/CONTRIBUTING.md).
## License
MIT - Kingsrook, LLC
AGPL-3.0 - QRun-IO
+3 -3
View File
@@ -4,11 +4,11 @@ version: 2.1
description: >
QQQ Orb to handle the branching, testing, releasing, and auto updating of
all maven and npm based projects within the Kingsrook/QRunIO Repo world.
all Maven and npm based projects within the QRun-IO ecosystem.
display:
home_url: "https://www.qrun.io"
source_url: "https://github.com/Kingsrook/qqq-orb"
home_url: "https://github.com/QRun-IO/qqq-orb"
source_url: "https://github.com/QRun-IO/qqq-orb"
orbs:
browser-tools: circleci/browser-tools@1.4.7
+7 -6
View File
@@ -1,11 +1,12 @@
description: >
Full checkout of the repository
- Clones the repository
- Checks out the commit specified by CIRCLE_SHA1
Full checkout of the repository with complete git history.
Uses CircleCI's checkout (handles SSH keys and known_hosts)
then fetches full history for version calculation.
steps:
- checkout
- run:
name: Full checkout
name: Fetch full git history
command: |
git clone "$CIRCLE_REPOSITORY_URL" .
git checkout "$CIRCLE_SHA1"
git fetch --unshallow || true
git fetch --tags || true
+30
View File
@@ -0,0 +1,30 @@
description: >
Installs Eclipse Temurin JDK and Maven on Ubuntu machine executor.
Sets JAVA_HOME and updates PATH for subsequent steps.
Optionally installs Node.js for frontend builds.
Also verifies Docker is available (required for Testcontainers/LocalStack tests).
parameters:
java_version:
type: string
default: "21"
description: >
Java major version to install (e.g., "17", "21").
Uses Eclipse Temurin (AdoptOpenJDK successor) distribution.
install_node:
type: boolean
default: false
description: "Whether to also install Node.js (for frontend builds)"
node_version:
type: string
default: "20"
description: "Node.js major version to install (e.g., '18', '20')"
steps:
- run:
name: Install Java << parameters.java_version >> and build tools
environment:
PARAM_JAVA_VERSION: << parameters.java_version >>
PARAM_INSTALL_NODE: << parameters.install_node >>
PARAM_NODE_VERSION: << parameters.node_version >>
command: <<include(scripts/install_java.sh)>>
+11 -11
View File
@@ -1,18 +1,18 @@
description: >
Java/OpenJDK executor using CircleCI's cimg/openjdk image.
Provides Java runtime with Maven and Gradle pre-installed.
Use the 'tag' parameter to select Java version (17.0, 21.0, etc).
docker:
- image: 'cimg/openjdk:<<parameters.tag>>'
Java/OpenJDK machine executor with Docker support.
Uses Ubuntu 22.04 VM with Docker pre-installed.
Java is installed via the install_java command.
Required for tests that use Testcontainers or LocalStack Docker extensions.
parameters:
tag:
default: "21.0"
image:
default: ubuntu-2204:current
description: >
Java/OpenJDK version tag. Common values: 17.0, 21.0.
See https://hub.docker.com/r/cimg/openjdk/tags for all available tags.
Use '-node' suffix for Node.js support (e.g., '21.0-node').
Ubuntu machine image tag. Use 'current' for latest or pin to specific
version like 'ubuntu-2204:2023.02.1' for reproducibility.
type: string
machine:
image: '<<parameters.image>>'
resource_class: large
+12 -6
View File
@@ -1,23 +1,29 @@
description: >
Unified publishing job for all branch types
Unified publishing job for all branch types with frontend
Handles version management, building, testing, and publishing based on branch type
Supports: snapshot, release_candidate, release, and hotfix workflows
executor:
name: java
tag: << parameters.java_version >>
executor: java
parameters:
java_version:
type: string
default: "21.0-node"
description: "Java/OpenJDK version with Node.js (e.g., '17.0-node', '21.0-node')."
default: "21"
description: "Java major version to install (e.g., '17', '21')"
node_version:
type: string
default: "20"
description: "Node.js major version to install (e.g., '18', '20')"
branch_type:
type: string
default: "snapshot"
description: "Branch type: snapshot, release_candidate, release, or hotfix"
steps:
- install_java:
java_version: << parameters.java_version >>
install_node: true
node_version: << parameters.node_version >>
- git_full_checkout
- mvn_manage_version
- frontend_build
+12 -6
View File
@@ -1,20 +1,26 @@
description: >
Complete test-only workflow for feature branches
Complete test-only workflow for feature branches with frontend
Runs build, test, API version check, and documentation generation
Used by: test_only workflow for feature branches
Triggers: Any push to branches NOT matching develop, main, release/*, hotfix/*
executor:
name: java
tag: << parameters.java_version >>
executor: java
parameters:
java_version:
type: string
default: "21.0-node"
description: "Java/OpenJDK version with Node.js (e.g., '17.0-node', '21.0-node')."
default: "21"
description: "Java major version to install (e.g., '17', '21')"
node_version:
type: string
default: "20"
description: "Node.js major version to install (e.g., '18', '20')"
steps:
- install_java:
java_version: << parameters.java_version >>
install_node: true
node_version: << parameters.node_version >>
- git_full_checkout
- frontend_build
- frontend_test
+7 -6
View File
@@ -1,17 +1,15 @@
description: >
Unified publishing job for all branch types
Handles version management, building, testing, and publishing based on branch type
Supports: snapshot, release_candidate, release (tagged), feasture (tagged) and hotfix workflows
Supports: snapshot, release_candidate, release (tagged), feature (tagged) and hotfix workflows
executor:
name: java
tag: << parameters.java_version >>
executor: java
parameters:
java_version:
type: string
default: "21.0"
description: "Java/OpenJDK version (e.g., '17.0', '21.0'). See cimg/openjdk tags."
default: "21"
description: "Java major version to install (e.g., '17', '21')"
branch_type:
type: string
default: "snapshot"
@@ -26,6 +24,9 @@ parameters:
description: "Whether to publish AsciiDoc documentation"
steps:
- install_java:
java_version: << parameters.java_version >>
- git_full_checkout
- mvn_build
+5 -5
View File
@@ -4,21 +4,21 @@ description: >
Used by: test_only workflow for feature branches
Triggers: Any push to branches NOT matching develop, main, release/*, hotfix/*
executor:
name: java
tag: << parameters.java_version >>
executor: java
parameters:
java_version:
type: string
default: "21.0"
description: "Java/OpenJDK version (e.g., '17.0', '21.0'). See cimg/openjdk tags."
default: "21"
description: "Java major version to install (e.g., '17', '21')"
check_middleware_api_versions:
type: boolean
default: false
description: "Whether to run middleware API version checks"
steps:
- install_java:
java_version: << parameters.java_version >>
- git_full_checkout
- mvn_build
- mvn_verify
+57
View File
@@ -0,0 +1,57 @@
#!/bin/bash
set -euo pipefail
# Install Java and Maven on Ubuntu machine executor
# Uses Eclipse Temurin (AdoptOpenJDK successor) for reliable JDK installation
# Optionally installs Node.js via NodeSource repository
JAVA_VERSION="${PARAM_JAVA_VERSION:-21}"
INSTALL_NODE="${PARAM_INSTALL_NODE:-false}"
NODE_VERSION="${PARAM_NODE_VERSION:-20}"
echo "Installing Java ${JAVA_VERSION} and Maven..."
# Add Eclipse Temurin repository
sudo apt-get update -qq
sudo apt-get install -y -qq wget apt-transport-https gpg maven curl
# Add Temurin GPG key
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
# Add repository
echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
# Install Java
sudo apt-get update -qq
sudo apt-get install -y -qq "temurin-${JAVA_VERSION}-jdk"
# Set JAVA_HOME
JAVA_HOME="/usr/lib/jvm/temurin-${JAVA_VERSION}-jdk-amd64"
echo "export JAVA_HOME=${JAVA_HOME}" >> "${BASH_ENV}"
echo "export PATH=${JAVA_HOME}/bin:\$PATH" >> "${BASH_ENV}"
# Install Node.js if requested
if [ "${INSTALL_NODE}" = "true" ]; then
echo ""
echo "Installing Node.js ${NODE_VERSION}..."
curl -fsSL "https://deb.nodesource.com/setup_${NODE_VERSION}.x" | sudo -E bash -
sudo apt-get install -y -qq nodejs
echo ""
echo "Node.js version:"
node --version
echo "npm version:"
npm --version
fi
# Verify installation
echo ""
echo "Java version:"
java -version
echo ""
echo "Maven version:"
mvn --version
echo ""
echo "Docker version:"
docker --version
echo ""
echo "Installation completed successfully"