v0.2.0

Quality Graph 0.2.0 brings first-party GitLab support, reports that explain why checks failed, and more reliable GitHub dashboards across retries and declaration changes.

Your checks remain ordinary repository commands. Quality Graph handles orchestration, result collection and review governance around them.

GitLab, out of the box

The new quality-graph-gitlab package provides a supported installation and onboarding path:

uv tool install quality-graph-cli==0.2.0 --with quality-graph-gitlab==0.2.0
qg init --provider gitlab

Configure the instance URL and publisher account ID, then run qg generate and qg validate.

• Generate native GitLab jobs, dependencies and result artifacts for merge-request and branch pipelines.
• Publish one managed MR summary with execution and effective results, findings, job-log links and owned labels.
• Approve or revoke quality findings at node, file or finding level through /qg comments, without rerunning the checks just to update their effective status.
• Bind results to the exact project, commit, pipeline and job, including retries. Missing or mismatched evidence cannot establish success.
• Keep write credentials in a protected publisher project; consumer and fork code runs without the publisher token.
• Configure GitLab.com or self-managed instances, including nested namespaces and custom API endpoints.

The MR summary currently provides a table and comment-based controls; it does not render the GitHub dependency diagram or clickable approval controls. Executable release flows, merged-results pipelines and merge trains are not supported by this first GitLab integration.

Setup and migration guide · Runnable example

Reports with useful failure details

Producer report v0 lets custom checks emit metrics, findings, diagnostics and notes without constructing framework identity, provenance or approval controls. Quality Graph supplies that trusted metadata during collection. Full native result inputs remain supported.

• JUnit reports include test names and assertion traces, with full test/failure/skipped counts.
• Repository-relative JUnit file attributes enable file-level approvals.
• Large JUnit reports preserve full totals while constructing at most 10,000 findings and 100 diagnostic traces, with explicit omission counts.
• The repository check runner preserves separate in-process and Docker results. Infrastructure errors take priority over test traces, so a Docker health-check or cleanup failure remains visible after hundreds of test failures.
• Command output is rendered as diagnostic detail instead of duplicating failure text in the summary.

Producer contract and adapters

GitHub dashboards you can trace back to the job

• Authoritative retry results: artifacts are checked against the actual workflow job attempts. Retained results from an older execution cannot silently stand in for the current job.
• Direct log links: each Dashboard row links to the corresponding GitHub job, including the admitted attempt after a retry.
• Additive declaration changes: a PR can introduce checks while preserving every existing required check and governance setting. Added checks appear in the final Dashboard and must provide valid results; missing or failed results prevent success.
• Clearer publication failures: if artifact validation fails, the fallback explicitly distinguishes native job conclusions from verified results. Successful jobs alone do not make the aggregate successful.

Migration and compatibility

Upgrading from 0.1.10 does not require rewriting qg.yaml or replacing GitHub Result v0. GitLab adds Result v1 for its own provenance; producer report v0 is a separate, optional collection input. The source-file rename to qg.yaml happened in 0.1.8 and is not a new requirement introduced by this release.

Upgrade the CLI and each provider you use together to 0.2.0. For GitHub installations:

uv tool install quality-graph-cli==0.2.0 --with quality-graph-github==0.2.0

Update both provider.configuration.runtime.action and publisher-action to the immutable release commit, regenerate the workflows and validate them:

runtime:
  action: alchemmist/quality-graph@3b0cf7d8a33215d5a3bb5521b4e0e41c18e8cb7c
  publisher-action: alchemmist/quality-graph@3b0cf7d8a33215d5a3bb5521b4e0e41c18e8cb7c

qg generate
qg validate

Deploy the updated publisher through the trusted base branch before relying on new declaration-migration behavior. Changing its pin only inside a feature PR does not replace the publisher already running from the base branch.

Behavior changes to account for:

• Retry validation is stricter. Previously accepted stale or mismatched artifacts can now fail the aggregate. Rerun the affected checks to produce current evidence; do not reuse artifacts from another attempt.
• JUnit file paths must be repository-relative. Absolute paths and parent traversal are rejected. Configure report producers accordingly; source locations use line 1 because JUnit producers do not share a line-number convention.
• A passing report cannot hide a failed command. In particular, a JUnit report with no failed cases combined with a nonzero command exit is classified as a command failure rather than an approvable quality failure.
• Raw exit-code output moved to diagnostics. Integrations that consume summary as a copy of stdout should read diagnostic detail instead.

For GitLab, set a positive publisher-user-id before generating MR publication jobs, use HTTPS outside loopback, and configure the protected publisher before enforcing merge checks. Moving from GitHub also requires replacing GitHub-specific setup actions with shell commands and explicitly retiring the old workflows. The GitLab guide covers the supported differences.

Packaging and validation

All five distributions are published at 0.2.0: core, CLI, Python gates, GitHub and GitLab providers. GitLab is installed separately and does not require the GitHub provider.

The release adds a stateful GitLab HTTP testkit and a real local GitLab/Runner laboratory covering approvals, retries, cancellations, explicit skips, erased artifacts, head changes and fork MRs. Published CLI and GitLab packages were also installed together in a clean environment and passed initialization, generation and validation smoke checks.

Contributions: #72, #75, #77, #76.

Full changelog: v0.1.10 → v0.2.0

v0.1.10

What's Changed

• Migrate the repository release pipeline into qg.yaml by @alchemmist in #68
• Execute release flows and activate compatible declaration migration by @alchemmist in #67

Full Changelog: v0.1.9...v0.1.10

v0.1.9

Quality Graph v0.1.9

Quality Graph v0.1.9 separates reusable operations from explicit execution flows, strengthens result provenance and PR-only publication, and introduces a release-flow design contract. It also adds adopter discovery tooling, fixes this repository's trusted runtime configuration, and updates the documentation site.

This release covers all changes since v0.1.8, including changes committed directly to the default branch.

Reusable operations and explicit flows

An operation now owns its executable contract: command or action, profile, environment variables, result adapter, timeout, and local policy. A flow owns its trigger, node membership, dependency graph, concurrency, and presentation.

• Reuse one operation across PR, main, and release declarations without duplicating its executable contract.
• Give an operation a flow-local node identity through an explicit placement. Dependencies belong to the placement, so one flow's topology does not constrain another.
• PR flows preserve their declared DAG by default. Push/main flows run their explicitly selected checks in parallel by default; they can opt into graph dependencies.
• Mark an operation diff-only: true to prevent it from being placed outside a PR flow.
• Validate operation/profile references, unique identities, dependencies, cycles, trigger/presentation compatibility, and concurrency lanes. Even a flow using dependencies: none must declare a valid DAG.
• Reject alias-generated node titles that exceed the result protocol's length limit before execution.
• Compile explicit declarations into a version 1 manifest with separate operation and flow sections. The GitHub compiler supports one PR flow and one push flow per declaration, with arbitrary flow IDs, plus release design contracts.

See Operations and explicit flows. Implemented in #66.

Presentation and trustworthy result identity

PR presentation is now an explicit adapter rather than a mandatory part of every flow.

• presentation: github-pr enables the PR dashboard, annotations, labels, check reporting, and reversible approvals.
• presentation: none retains raw results, normal workflow visibility, and job summaries without PR-specific controls or annotation emission.
• Trusted publication and comment-command dispatch check the base-branch declaration before invoking PR presentation. Main flows do not invoke the PR publisher.
• merge.required: true requires an enabled PR presentation adapter.
• Explicit results carry paired provenance.flowId and provenance.operationId, alongside the placement's nodeId. Artifact validation rejects missing or mismatched flow/operation identity.
• Native producers can use qg result emit --flow-id ... --operation-id .... Generated jobs expose flow, operation, node, title, and graph-digest environment values.
• Approval controls remain derived framework state; producer-supplied controls are stripped when PR presentation is disabled.

Release-flow contracts

Release declarations support typed dispatch inputs, an exclusive concurrency lane, reusable operation placements, and environment checkpoints with approval and observation-window settings.

The provider design specifies durable checkpoints, authenticated and idempotent resumption, lane ownership across runs, promotion evidence, runner-free observation waits, terminal failure/cancellation, a future rollback extension, and release-oriented publication.

Release execution is not shipped in 0.1.9. These manifest entries are explicitly marked design-only; no deployment workflow, production integration, or runner-held sleep is generated. See the release-flow provider contract.

Migration and safer generated-file management

• Existing graph-v0 nodes, node events, and execution.<event>.dependencies remain supported. Legacy declarations keep manifest version 0.
• Explicit operations/flows cannot be mixed with legacy nodes/execution in the same declaration.
• Removing a flow or disabling PR presentation retires its compiler-owned workflow; qg validate reports obsolete generated files until regeneration.
• Retirement resolves candidate paths and rejects escapes through symlinked parent directories before reading or deleting files.
• Dangling retired-workflow symlinks are detected. Unmanaged files and symlinks are preserved, and generation reports an error instead of silently removing them.
• The published concurrency schema now matches the parser's identifier constraints.

Runtime compatibility fix and CI improvements

This repository's execution and trusted publisher pins were updated to the exact v0.1.8 runtime. The previous pin did not understand provider.configuration.merge, causing publisher failures, stale PR dashboards, and an aggregate check that remained in progress. The workflows and manifest were regenerated in #64.

A dedicated workflow-graph validation job now runs before formatting in the repository's quality DAG. The isolated mutation-test workspace also includes the adopter-discovery workspace member so locked dependency resolution succeeds.

New coverage exercises operation reuse, flow validation, complete compiler contracts, native result provenance, presentation isolation, artifact rejection, migration, and symlink handling. GitHub-facing scenarios use the stateful fake GitHub service through the production HTTP client, including the Docker adapter. The completed flow-refactor PR passed 450 fast tests and 50 integration scenarios, 100% changed-line coverage, and a fresh local mutation score of 90.77% against the unchanged 90% threshold.

Adopter discovery

Added the repository-local qg-find-adopters tool and make adopters-find / make users entry points in #63.

• Search GitHub code for the pinned Quality Graph Action and generated-workflow signature.
• Deduplicate repositories, exclude forks and archived projects, rank candidates by stars, and show discovery evidence.
• Mark repositories already in the adopter catalog; --new-only filters them out.
• Support configured HTTPS proxy routing and bounded redirects restricted to the GitHub API origin.
• Report incomplete search results and transport/API failures.
• make users loads GITHUB_TOKEN from the repository's .env and selects new candidates.

Discovery produces candidates for manual verification; it does not automatically add projects to the site. The tool is a separate workspace member, not a new command bundled into the main qg CLI. See Finding adopters.

Documentation and website

• Moved documentation, README links, and package homepage/documentation metadata to quality-graph.xyz.
• Added an ordered v0.1.8 upgrade guide covering the earlier qg.yaml filename migration, coordinated CLI/runtime upgrades, and required-check synchronization. Updated installation, quickstart, migration, and troubleshooting guidance.
• Added operations/flows, release-flow contracts, and adopter-discovery documentation to site navigation.
• Moved the landing-page adopter list into a validated docs/adopters.json catalog, added Devsyringe and its logo, and made the ticker non-interactive.
• Added homepage-only Umami analytics.
• Added the SVG/PNG/ICO favicon set, Apple touch icon, web app manifest, and updated favicon backgrounds.

Upgrading to 0.1.9

All four main distributions are versioned together: quality-graph-core, quality-graph-github, quality-graph-cli, and quality-graph-python.

uv tool install --force quality-graph-cli==0.1.9 --with quality-graph-github==0.1.9

Update the Action runtime to the exact release commit, including publisher-action if configured separately:

provider:
  name: github
  configuration:
    runtime:
      action: alchemmist/quality-graph@634e7f4f49e4c49a045b03e6ffc438946db60729
      publisher-action: alchemmist/quality-graph@634e7f4f49e4c49a045b03e6ffc438946db60729

Then run qg generate and qg validate, and commit the generated output. Existing v0.1.8 users do not need to rewrite their declarations into flows. Adopting explicit flows requires a compatible compiler and runtime, updated native-producer provenance, and the migration steps in the flows guide. Installations older than v0.1.8 must also follow the filename migration guide.

Full changelog: v0.1.8...v0.1.9

v0.1.8

Quality Graph v0.1.8

Quality Graph v0.1.8 introduces explicit synchronization of GitHub merge requirements, makes dashboard publication more reliable, and expands result diagnostics and approval controls.

This release contains an intentional breaking change: the graph specification has moved from quality-graph.yml to qg.yaml with no compatibility fallback.

Breaking change: rename the graph specification

qg.yaml is now the only accepted source specification filename. Quality Graph no longer reads quality-graph.yml.

• Repositories containing only quality-graph.yml receive a migration error.
• Repositories containing both filenames are rejected; Quality Graph never chooses one implicitly.
• qg init creates qg.yaml.
• CLI commands and trusted GitHub publisher/command runtimes read qg.yaml exclusively.
• Generated workflow filenames remain unchanged, including .github/workflows/quality-graph.yml.

Migrate the file before running the upgraded CLI:

git mv quality-graph.yml qg.yaml

GitHub required-check synchronization

The graph specification can now declare whether the stable aggregate Quality Graph check is a merge requirement:

provider:
  name: github
  configuration:
    merge:
      required: true

Apply the setting explicitly with:

GITHUB_REPOSITORY=owner/repository qg github required-checks sync

Synchronization is never performed by qg generate or normal workflow execution. The command:

• supports classic branch protection and repository rulesets;
• preserves unrelated checks, GitHub App bindings, review requirements, restrictions, bypass actors, and other protection settings;
• removes only the Quality Graph-owned context when the opt-in is disabled;
• prints the planned diff before mutation;
• performs no write when settings are already current;
• rejects ambiguous or organization-managed required-check ownership instead of partially updating repository settings.

The token needs repository Administration: write permission. Organization-owned rulesets must be updated by an organization administrator with organization-level Administration permission.

More reliable dashboards

Dashboard publication now has a single, recoverable lifecycle:

• the requested watcher can finalize a completed workflow from validated result artifacts;
• completed events remain an idempotent repair path;
• live and final publication update one stable synthetic Quality Graph check instead of creating duplicates;
• stale and superseded watchers cannot overwrite newer results;
• graph-topology changes no longer leave a watcher waiting forever for removed nodes;
• workflow-run discovery follows GitHub pagination instead of inspecting only the first page.

Richer diagnostics and approval controls

Exit-code result adapters can now capture UTF-8 command output and include it in summaries and diagnostics:

run: |
  mkdir -p reports
  set -o pipefail
  make check 2>&1 | tee reports/check.log
results:
  exit-code: reports/check.log
policy:
  approvals:
    node: true

Node approval controls are available in Job Summaries and the managed dashboard when enabled by policy. Invalid captured-output encoding is reported as an adapter failure.

Integration test infrastructure

The repository now includes a reusable stateful fake GitHub with in-process and Docker adapters, request history, pagination, delays, fault injection, reset/snapshot controls, and deterministic repository, workflow, artifact, comment, label, and check state.

Contributor test lanes are now organized as:

• make t-fast for fast tests;
• make t-medium for integration scenarios, including the container-backed adapter when Docker Compose is available.

Upgrade guide

1. Rename the specification before invoking Quality Graph 0.1.8:

   git mv quality-graph.yml qg.yaml

2. Upgrade the CLI and GitHub provider together:

   uv tool install --force \
     quality-graph-cli==0.1.8 \
     --with quality-graph-github==0.1.8

   If the repository directly depends on quality-graph-core or quality-graph-python, upgrade those packages to 0.1.8 as well.

3. Update the immutable Action runtime pins in qg.yaml:

   provider:
     name: github
     configuration:
       runtime:
         action: alchemmist/quality-graph@b947f26e97ccf1c755050dfe38d98cbb688edb69
         publisher-action: alchemmist/quality-graph@b947f26e97ccf1c755050dfe38d98cbb688edb69

4. Regenerate and validate managed files:

   qg generate
   qg validate

5. Review and commit qg.yaml, generated workflows, .quality-graph/manifest.json, and any managed .prettierignore changes.

6. Optionally enable merge.required and run the explicit required-check synchronization command with an administrative token.

Included pull requests

• #56 — Fix publisher lifecycle finalization
• #59 — Rename the graph specification to qg.yaml
• #61 — Synchronize GitHub required checks from qg.yaml
• #62 — Restore the stateful fake GitHub integration test system

Full changelog: v0.1.7...v0.1.8

v0.1.7

What's Changed

• Make the generated workflow default branch configurable by @alchemmist in #49
• Preserve job states when artifact validation fails by @alchemmist in #51
• Generate event-specific execution graph projections by @alchemmist in #53
• Add configurable upload artifact action pin by @alchemmist in #54

Full Changelog: v0.1.6...v0.1.7

Quality Graph v0.1.6

Quality Graph v0.1.6 is the recommended upgrade for users of v0.1.2 and later. It consolidates the Job Summary, dashboard lifecycle, generated-artifact, documentation, and release reliability fixes delivered across the v0.1.3–v0.1.6 recovery releases.

Highlights

Framework-owned Job Summaries

Quality Graph now composes complete GitHub Job Summaries centrally:

• producer-supplied Markdown remains domain-specific content;
• findings include stable IDs and source locations;
• metrics, diagnostics, and notes use the shared renderer;
• finding-, file-, and node-level controls are derived from graph policy;
• apply and reverse /qg commands share one canonical implementation with the dashboard;
• administrator actions are placed in a collapsed section at the bottom;
• bounded rendering links to the result artifact when actions are omitted.

Native result producers no longer need to duplicate Quality Graph presentation or governance logic.

Race-free live dashboards

Live dashboard state now follows authoritative GitHub job lifecycle:

• parallel nodes no longer overwrite one another;
• reruns are handled through both requested and in_progress events;
• completed nodes no longer revert to waiting;
• terminal live snapshots cannot overwrite the final artifact-derived dashboard;
• superseded watchers revalidate freshness before every write;
• partial results remain visible when downstream jobs are skipped.

Safer publisher rollout

Execution and publication runtimes can be pinned independently:

• runtime.action remains part of execution provenance;
• runtime.publisher-action upgrades the trusted default-branch publisher without invalidating existing artifacts;
• both actions must come from the same GitHub repository;
• pull-request jobs remain read-only and never receive the dashboard write token.

Generated artifact contract

Generated files now carry an explicit managed-file notice. The compiler also:

• emits formatter-compatible YAML;
• manages generated paths through an idempotent .prettierignore block;
• exposes generated paths through qg generated-files;
• keeps workflows, manifests, examples, and snapshots deterministic.

Documentation and package metadata

• Added the public documentation website: https://alchemmist.github.io/quality-graph/
• Expanded installation, quickstart, migration, configuration, security, troubleshooting, and release documentation.
• Added homepage and documentation links to every PyPI package.

Bug fixes

• Fixed stale dashboard updates during parallel workflow execution.
• Fixed final dashboards being overwritten by late live updates.
• Fixed workflow reruns not starting the live watcher.
• Fixed missing and partial artifact handling.
• Fixed generated YAML failing formatter or yamllint contracts.
• Fixed mutation checks using an inconsistent test environment.
• Fixed native producers being able to supply non-policy controls.
• Fixed unsafe Markdown escaping in administrator controls.
• Fixed unnecessary managed-comment writes.
• Fixed release version bumps leaving test literals and internal dependency pins behind.
• Fixed package smoke tests being tied to a previous release version.
• Added bounded retries for transient Go checksum and tool-download failures during CI releases.

What users need to do

1. Upgrade the CLI and GitHub provider

uv tool install --force \
  quality-graph-cli==0.1.6 \
  --with quality-graph-github==0.1.6

If you depend directly on quality-graph-core or quality-graph-python, update those packages to 0.1.6 as well.

2. Update the pinned Action runtime

Update quality-graph.yml:

provider:
  name: github
  configuration:
    runtime:
      action: alchemmist/quality-graph@c73c58fb1c5064546b40f481decdb7bc12c5e9fe
      publisher-action: alchemmist/quality-graph@c73c58fb1c5064546b40f481decdb7bc12c5e9fe

Quality Graph intentionally does not publish a moving Action tag. Keep using the immutable commit SHA.

3. Regenerate managed files

qg generate
qg validate

Commit every changed generated file, including:

• .github/workflows/quality-graph.yml
• .github/workflows/quality-graph-publish.yml
• .quality-graph/manifest.json
• .prettierignore, if changed

Do not edit generated files manually.

4. Migrate custom native producers

Remove manually generated finding IDs and /qg commands from result.summary. Producers should emit custom Markdown, semantic findings, metrics, diagnostics, annotations, and notes. Quality Graph now owns stable finding labels, policy-derived controls, canonical commands, and administrator layout.

5. Ensure node titles are unique

The GitHub provider now requires unique node titles so authoritative GitHub job states can map back to stable graph node IDs.

Full changelog

v0.1.2...v0.1.6

v0.1.4

Full Changelog: v0.1.3...v0.1.4

v0.1.2

What's Changed

• fix GitHub Release creation and publish v0.1.2 by @alchemmist in #34

Full Changelog: v0.1.1...v0.1.2