qqq-orb/README.md

# qqq-orb

CircleCI orb for QQQ framework projects.

For centralized pipeline ownership, see [standardized manifest-driven pipelines](docs/GENERATED-PIPELINES.md).
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](docs/managed-patch-updates.md).

**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

```yaml
# .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](https://docs.npmjs.com/trusted-publishers/) 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:

```yaml
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](CHANGELOG.md)

## Contributing

```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

Apache-2.0