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:
- A Buildkite API token in Settings → Organization → Buildkite with the scopes in the Buildkite setup. If you connected Buildkite before, reconnect with a new token that has them.
- The Dynamic CI plugin v0.1.10 or later.
- 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’smode: step.
- GitHub Actions
- Buildkite
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.- GitHub Actions
- Buildkite
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.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:,
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 (apaths 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.
Related
Jobs
Turn on Run Before Queue for a job.
Merge queues
How Dynamic CI behaves on merge queue runs.