Merge queue CI

The merge queue validates the candidate that will land against its target bookmark. Native candidate identity and ancestry follow JJ. Start with source control and landing if you are new to Composal Changes.

For the number of candidates that can validate at once, see Runners and concurrency.

Work with draft Changes

com submit publishes Changes ready for review, including an existing draft you resubmit. Use com submit --draft only when you want unfinished work to remain a draft. com sync preserves draft status unless you explicitly change it.

On a draft Change page, select Mark ready when you want review without joining the merge queue. Organization members with access to the repository can mark an open Change ready.

You can also press Land Change, Land Changes, or Land When Ready directly. Composal marks the drafts in the displayed submitted-together stack or group ready, then applies the usual queue, approval, CI and bookmark protection rules. Marking ready does not approve a Change or bypass a failing check. If a remaining requirement prevents admission, the Changes stay ready for review and the page shows the reason.

From the CLI, com submit (or the explicit com submit --ready) marks selected revisions ready without landing. Add -r <JJ-change-id> to select a specific revision. Land normally with com land '#42' when you want to enter the queue.

Move urgent work ahead of waiting changes

Organization administrators and owners can select High priority when landing a Change or stack. The server admits the whole submitted-together scope once and places it ahead of waiting entries, immediately after any merge already in progress. Normal priority joins the back of the queue. The Change page shows the accepted priority and queue position.

With a CLI release that supports priority, use:

com land '#42' --priority high

Use Move to front on an existing queue entry to move its entire stack or explicitly grouped Changes. An entry already at the earliest safe position does not move again. Repeating an admission request with the same priority returns its existing entry without another jump; changing that request's priority is refused. Use Move to front for an intentional later move.

Moving work preserves any in-progress merge and its CI proof. Waiting candidates whose ordered predecessors change are rebuilt and may need fresh CI, so use priority for urgent work rather than repeatedly rearranging the queue. Approvals, required checks, and target freshness still apply. Priority controls placement, and later urgent requests can move ahead of earlier ones.

For a native, Composal-primary top-only queue, land the whole stack or explicit group together to validate one combined candidate. Each required workflow runs once for that candidate. Eligible queues with the adjacent batch preview enabled can also combine separate waiting requests.

Request full CI

Organization administrators and owners can choose Run Full CI on an eligible queue entry, or use a CLI version that includes this command:

com queue status
com queue validate-full '#42'

Replace #42 with your Change number; a queue entry ID is also accepted. If your CLI does not recognize validate-full, use a release that includes the command or the web control when available. The control requires server support and is offered only for eligible entries.

Run Full CI requests fresh execution of all applicable workflows even when the candidate SHA is unchanged. It keeps the entry's position, Changes, approvals, and landing intent. The request persists through retries and candidate rebuilds for that entry. Repeating it requests fresh jobs again. Dependent queue validations may be invalidated and rebuilt; those followers do not inherit the full-CI override.

The action supports queued, validating, or ready ordinary native entries in a Composal-primary top-only queue. It is unavailable for merging, terminal, or needs-attention entries and unsupported selective-CI queue scopes. A paused queue remains paused. Full CI still uses configured artifact/compiler caches and still enforces external required checks; it does not mean a cold-cache build or a bypass of landing policy.

Reuse queue tests on trunk

Queue-to-trunk result reuse is a preview under development and is not enabled by default. Its purpose is to avoid running the same successful tests again just because the validated candidate landed on trunk. It is separate from dependency caching.

For eligible workflows triggered by both change and push, Composal checks the native JJ publication receipt, exact candidate commit, workflow and job inputs, secret versions, and runner image and resources. A matching job appears as successful with Reused queue validation and a link to the original run and logs. It consumes no additional runner lease. Push-only jobs, including deployments, still execute.

Once native publication is acknowledged, a pending deployment or another newly queued check does not erase the passing queue receipt. You can see deployment progress while matching test results are reused. Before acknowledgement, pending required checks still block landing; a new required failure still invalidates result reuse.

The batch extension uses the same rule for a group of landing requests: only the shared CI runs that passed for the complete, published candidate can supply results to trunk. A successful smaller retry cannot supply results for a different combination of Changes. Trunk waits for publication acknowledgement and completion of the group landing before considering reuse. This extension requires both adjacent batching and trunk result reuse to be enabled by your platform administrator; neither is enabled by default.

Keep test commands independent of the event when you want their results reused. Jobs with changed inputs, unavailable execution evidence, or an explicit retry run normally. The initial preview also runs artifact-producing jobs and their dependents again; artifact result reuse is not yet supported. A repeated delivery of the same publication does not create another run, while a separate publication of the same commit is evaluated separately.

Inspect shared batch CI

Adjacent landing batches are an organization-scoped opt-in preview, off by default. Ask your platform administrator to enable the preview for an eligible native, Composal-primary top-only queue. On compatible deployments, already-waiting requests with matching validation requirements can share one final candidate and one run of each required workflow. A stack or submitted-together group remains indivisible. A lone request does not wait for more work to accumulate.

For example, three compatible waiting requests can share one final test run. After the complete candidate lands, matching push-triggered tests can reuse that result without another runner, while push-only deployment jobs still execute. This reduces duplicate execution; the elapsed time saved depends on your workflows and runner capacity.

In the merge queue, expand Shared batch to see its ordered landing scopes, open each Change, and follow View shared CI to the complete candidate's checks. Every participating entry points to the same validation. A Previous batch records an earlier attempt; it does not authorize the current candidate or mean that its checks passed. Released attempts keep their membership and available CI link for diagnosis.

With a compatible CLI, com queue status shows the same shared or previous batch, ordered Change references, and the shared candidate. Use com ci status --commit <candidate> to inspect its checks, keeping the same --org and --repo context as the queue command. com queue status --json retains the batch membership and authoritative checks_target. A previous batch is diagnostic history; its result does not replace the entry’s current checks.

To make effective use of batching, keep workflow inputs explicit and include shared dependencies in the suite manifest. Let normal queue order determine compatible neighbors. Use high priority for urgent work, not to rearrange unrelated Changes into a batch. If shared CI fails, Composal may retry smaller combinations of independent landing scopes within its work budget; it does not split your submitted stack or treat an isolated pass as proof that the original combination was safe.

Refresh generated files before landing

Generated-file reconciliation refreshes generated output on the candidate before its final CI runs. This helps when a Change updates an input such as a schema and the generated files need to reflect the candidate that will actually land.

Availability: this is an organization-scoped preview, off by default. A platform administrator must enable it on a compatible deployment. The preview supports ordinary Changes and submitted-together stacks in a native, Composal-primary, top-only queue. A stack runs its generator once against the combined candidate before final CI. Reconciliation across adjacent, independent landing requests remains part of the batch preview awaiting rollout.

First land a dedicated workflow on the target bookmark, for example .vex/workflows/reconcile.yml:

name: Refresh generated API files
on:
  mergequeue:
    files: ["api/schema/**"]
    conflict: ["api/generated/**"]
    outputs: ["api/generated/**"]
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - run: python3 scripts/generate_api.py

Use files for input changes that should trigger generation, conflict for generated-file conflicts the workflow can resolve, and outputs for the files it may write. Supply an explicit output allowlist and at least one input or conflict selector. Keep mergequeue as the workflow's only trigger and use exactly one job.

Composal loads the workflow and its write permissions from the pinned target revision, then runs it over the candidate in an isolated job on shared system runners. Keep generation deterministic and able to run offline within ten minutes, using tools and dependencies already available in the workspace or runner image. Organization secrets, local actions, job dependencies, matrices and workflow concurrency groups are unavailable in this initial profile.

Composal accepts only allowlisted output changes, records them in a native Composal System commit, and runs ordinary candidate CI on that exact result. The generator itself is not an ordinary required check. Generation failure, unresolvable conflicts or failed final CI leave the target unchanged. Incoming edits to the generator workflow take effect only after that configuration lands on the target.

If generation fails, retry the landing through the merge queue. A generator cannot be retried as a standalone CI run because its output permissions and receipt belong to that queue candidate.

Keep an ordinary validation workflow alongside the generator. Trigger eligible tests on both change and push to use the queue-result reuse described in queue-to-trunk result reuse. Keep push-only deployment jobs separate so landing still deploys the validated result.

Next: inspect runs and troubleshoot delays.