Skip to content
Source
Sign inSign up

Pull requests from a fork

You opened a pull request from your fork, and its CI run says "This run is waiting for a maintainer to approve it."

The maintainers have not read your code yet. So CI runs it at the lowest trust level, untrusted, and only after a person with write access approves the run.

Why your run waits

  • Your run is untrusted because you have no write access to the base repository. It starts only when a person with write access approves it.
  • Each push to your branch starts a new run, and each new run waits for its own approval.
  • If screening holds your pull request, no run starts until a maintainer shows the pull request.
  • After the approval, your jobs wait in a queue. By default, at most 4 of your untrusted jobs run at the same time. Together they get at most 4 hours of container time each UTC day. The software factory jobs on your pull request count toward these limits too. A job past these limits waits. It does not fail.

What your run can do

Your run:

  • Runs the code of your commit, and reads the repository.
  • Gets the untrusted value of each secret that its jobs ask for, as a placeholder (tss_ph_ and 40 letters and digits). The forge swaps the placeholder for the value only in a request header to a host that the secret is bound to.
  • Reaches only the hosts that the base branch lists for the job.
  • Reads the cache, and writes only the cache of your pull request.

Your run cannot:

  • Get the trusted or the protected value of a secret.
  • Push, comment, or change issues and pull requests. Its run token only reads.
  • Use a secret, a host or a permission that your pull request adds to a workflow. The run shows a warning, and the job runs without it until a maintainer merges the change.
  • Send a placeholder to another host, or put one in a URL. The forge refuses the request and records a leak attempt.

If a job needs a secret that has no untrusted value, the job is skipped, with the reason. The rules for each level are in Trust levels and secrets.

Let CI fix your branch

Some jobs end with a fixup() step, for example a formatter. The forge then commits the change to the head branch in your fork, when all of these are true:

  • Your head branch is still at the commit that the run tested.
  • The patch is at most 5 MiB, and it changes nothing in .source/.
  • Your pull request allows edits from maintainers. This is on by default.

If one of them is false, the pull request shows the patch as a suggestion with an Apply button. You can apply it, because you have write access to your fork.

The new commit starts a new untrusted run. That run also waits for an approval.

To stop maintainers and CI from changing your branch, clear Allow edits from maintainers on the pull request page. You can also run this command:

src ci maintainer-edits 7 --off

Reproduce a failing job

On the run page, each job that started shows a command under "Run this job on your machine". The command runs the job with the matrix cell, inputs and needs of that run.

  1. Set the forge variables. TSS_REPO is the base repository, not your fork.

    export TSS_FORGE_URL=https://forge.example/api/v1
export TSS_TOKEN=<your personal access token>
export TSS_REPO=acme/app

  2. Check out the commit of the run:

    git fetch origin <commit>
git checkout --detach <commit>

  3. Run the command that you copied from the run page:

    src ci run --repro '<run>/test (shard: 2)'

To run a job without the forge, put your own values in .env. Then give the workflow and the job to src ci run:

echo 'NX_CLOUD_ACCESS_TOKEN=<your own token>' >> .env
src ci run pr test
  • Secrets come from the environment, then from .env. If a required secret has no value, the command stops before any job runs.
  • The run has the trust level local. Unless you add --live, writes to the forge are a dry run.
  • A fixup() step writes a patch file, and prints the git apply command for it.

Do not commit .env. More about local runs is in Run CI on your machine.

A required check with a name that starts with hidden: comes from a hidden workflow. Such a check shows no log. Its result shows a summary, and a command under "Reproduce it locally" that a maintainer wrote.

Get your pull request to green

  1. Push a fix to your branch.
  2. Wait for a maintainer to approve the new run.
  3. Read Required checks above the merge button of the pull request.
  4. If your branch is not up to date, push a merge of the base branch into it.

When each required check shows Passed, your pull request is green, and a maintainer can merge it.