Skip to main content
Dynamic CI can skip a job on every push of a pull request. Run Before Queue makes sure a job has run on the pull request’s head commit before the pull request enters the merge queue, in order to avoid merge queue evictions. When you submit a pull request, Trunk holds it in Not Ready, starts each Run Before Queue job that did not run on the head commit, and lets it in once those jobs have started.
Run Before Queue is in beta. Reach out on Slack to have it turned on for your organization.

Prerequisites

  • Trunk Merge Queue for the repository. Run Before Queue runs only for pull requests submitted to it.
  • Dynamic CI on for the repository: Enforced, or Learning with the pull request on the allow list. In Learning mode, a pull request that isn’t on the allow list enters the queue without Run Before Queue.
  • GitHub Actions: the Trunk app installed with Actions: read & write, and trunk-io/dynamic-ci@v1.
  • Buildkite:
  • The job’s setting. In Configuration → Jobs, set Run Before Queue to On the head commit.

Run the Dynamic CI gate once, ahead of every job

Run Before Queue supports only the fan-out gate: one Dynamic CI job (GitHub Actions) or upload step (Buildkite) ahead of the others, whose plan request covers every job. This is the setup the getting started pages describe. A gate step inside each job is not supported. On Buildkite, that is the plugin’s mode: step.
Every job that reads the gate’s output must list dynamic-ci in needs:. A job that doesn’t is never skipped, so it runs again in every rerun Trunk starts.

How Trunk runs the jobs

Run Before Queue starts once the pull request is submitted and GitHub reports it mergeable. Trunk waits for any run of the workflow or pipeline already in progress on the head commit to finish, however long it takes, and never cancels it. Each workflow or pipeline is handled on its own, so a slow one does not hold up another. A job that already ran on the head commit, passed or failed, is not run again.
Trunk reruns the whole workflow on the head commit. In that rerun, the Run Before Queue jobs run, and so does every job they needs:, directly or through other jobs. Jobs you forced in that workflow run too. Every other job is skipped, including a job that already failed on the head commit.
A matrix job runs every variation. Pull requests from forks aren’t supported. Dynamic CI runs every job on them. Once Run Before Queue has started for a pull request, each later push runs its Run Before Queue jobs, and the jobs they need, in that push’s own CI while the pull request is still submitted. Once the pull request is submitted, Run Before Queue runs a job even when its schedule is Always Skip.

While the pull request is held

The pull request stays in Not Ready, and its readiness says Starting Run Before Queue jobs: … until the jobs start. Then the Trunk web app shows a passed row, Run Before Queue jobs started: …, and the line goes away in the browser extension and the CLI. If it says Run Before Queue status is unavailable right now, there is nothing to do: the merge queue still checks it before the pull request enters the queue.

When a job counts as started

A job has started once it reaches the Dynamic CI gate in Trunk’s run. The queue then admits the pull request without waiting for the job to finish.
  • A required job still gates the pull request through its own status check, as every required check does. If it fails, the pull request stays in Not Ready.
  • A job that isn’t required doesn’t hold the pull request once it has started, whatever its result.
If your workflow skips the job after the gate, for example with its own if:, the job still counts as started.

Failed to start

When Trunk can’t start the jobs, the pull request stays in Not Ready and its readiness says Run Before Queue failed to start and why. Subscribers to Not Ready notifications in Slack get a message too. Common causes are a workflow that didn’t run on the head commit (a paths or branches filter, or a manual-only workflow), a run in progress that didn’t finish within 24 hours, missing access (the Trunk app’s Actions: write, or the Buildkite token’s write_builds), and jobs that didn’t begin running within an hour. To unblock the pull request, do one of these:
  • Force the jobs and rerun. Force Run the jobs, then click Run N jobs now. Trunk cancels any run in progress on the head commit and starts a new one.
  • Push. The push’s own CI runs the Run Before Queue jobs.

Jobs

Turn on Run Before Queue for a job.

Merge queues

How Dynamic CI behaves on merge queue runs.