qqq-orb

CircleCI orb for QQQ framework projects.

For centralized pipeline ownership, see standardized manifest-driven pipelines. The initial QBit profile uses a small .qqq-ci.yml and a setup entry point; existing direct job callers remain supported. For centrally managed patch adoption and exact-version rollback, see managed patch updates.

For: Teams using CircleCI to build, test, and publish QQQ applications Status: Stable (v0.6.x)

Why This Exists

QQQ projects share common CI/CD patterns: build with Maven, run tests, publish to Maven Central or npm. Setting this up from scratch means duplicating workflow configuration across every repository.

This orb provides pre-built jobs for the complete QQQ development lifecycle. Add a few lines of YAML and your project has automated testing, version management, and publishing.

Features

• 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

# .circleci/config.yml
version: 2.1
orbs:
  qqq-orb: kingsrook/qqq-orb@0.6

workflows:
  build_and_test:
    jobs:
      - qqq-orb/mvn_test_only

  publish_snapshot:
    when:
      equal: [develop, << pipeline.git.branch >>]
    jobs:
      - qqq-orb/mvn_publish:
          context: qqq-maven-registry-credentials
          branch_type: snapshot

Usage

Available Jobs

Job	Purpose
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
static_analysis	Run SpotBugs and PMD static analysis
security_scan	Run Gitleaks, Semgrep, OWASP Dependency Check, and CycloneDX SBOM

npm Trusted Publishing

For npm Trusted Publishing, set npm_trusted_publishing: true and use a supported executor such as node_version: "24.21" on node_publish. Configure the package's npm Trusted Publisher for the exact CircleCI organization, project, pipeline definition and VCS origin, and allow direct npm publish. The job requires Node >=22.14.0 and npm >=11.5.1, obtains an OIDC identity at publish time, and does not run npm whoami or need NPM_TOKEN. Existing token authentication remains the default. Trusted mode requires no project .npmrc or npm credential/config-path environment settings; it ignores user/global npm config and clears conventional token variables to prevent token fallback. CircleCI does not currently provide npm provenance attestations. A successful real publication, not a dry run, verifies the trust relationship.

Branch Types

Branch	Version Format
develop	1.5.0-SNAPSHOT
release/1.5	1.5.0-RC.1
main	1.5.0 (requires tag)
hotfix/1.5.1	1.5.1
feature/*	1.5.0-feature-abc1234-SNAPSHOT

The Maven version step verifies the effective project.version, not only the revision property. For older POMs with a literal project version, it uses Maven's version plugin to align project and reactor coordinates with the calculated version. A mismatch after updating fails before publication.

Java Version

Maven jobs run on Ubuntu machine executors with Temurin JDK. Default is Java 21. To use Java 17:

jobs:
  - qqq-orb/mvn_test_only:
      java_version: "17"

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

Variable	Purpose
MAVEN_USERNAME	Sonatype username
MAVEN_PASSWORD	Sonatype password
GPG_PRIVATE_KEY_B64	Base64-encoded GPG key
GPG_KEYNAME	GPG key ID
GPG_PASSPHRASE	GPG passphrase
GITHUB_TOKEN	GitHub API token

Orb Publishing

QBit CI maintenance

The QBit profile runs Maven verification without publishing when a single-parent ci: ... or ci(scope): ... commit changes only .qqq-ci.yml, .circleci/config.yml, .github/workflows/codeql.yml, or .github/workflows/release-rc.yml. This applies on main, develop, release, and hotfix branches. The normal test job still runs, including on branches normally excluded from feature tests, and reports through the required verify workflow.

Tags, merge commits (including release automation), application changes, other files, empty diffs, and unavailable history retain normal publishing behavior. This lets central configuration updates avoid unnecessary application versions without introducing per-repository maintenance workflows.

The orb auto-publishes via CircleCI:

Branch	Action
develop	Publishes kingsrook/qqq-orb@dev:snapshot
main	Auto-increments version and publishes production release
vX.Y.Z tag	Manual production release (legacy)

Version bumps on main default to patch. Include [minor] or [major] in a commit message to bump accordingly.

Project Status

Maturity: Stable, used across all QQQ repositories Breaking changes: See CHANGELOG.md

Contributing

git clone git@github.com:QRun-IO/qqq-orb.git
cd qqq-orb
make test-all

See QQQ Contribution Guidelines.

License

Apache-2.0