Documentation

Pull request checks

What Helen’s Foundry posts on a pull request, and why it sometimes posts nothing. Setup takes three ordered steps, and a check appears only after all three are done.

No check appeared at all

Silence almost always means the repository is not connected. Connecting GitHub is not enough: connecting the repository is the step that admits it to the review pipeline. Open Settings → Integrations and look at the GitHub card — it reads Partial while an organization has no connected repository. Then tick your repository in that organization's Repositories list.

Open Integrations →

Connect a repository

Do these steps in order to get checks on your pull requests. The next section explains each condition in detail.

  1. 1 Connect GitHub from the account that owns the repository. On GitHub, select Install. For an organization, an owner must approve the connection. A personal account approves it for itself.
  2. 2 In Settings → Integrations → GitHub, choose “Connect GitHub” to link the account to this workspace.
  3. 3 Tick your repository in that organization’s Repositories list. Connecting the repository is what admits it to the review pipeline.
  4. 4 Open a pull request and link the ticket it implements in the description. Helen checks it on the next event.
Open Integrations

Working alone on a personal repository

  1. 1 Create your workspace. One member is enough, and a personal repository needs no GitHub organization.
  2. 2 Connect GitHub from your personal GitHub account. Then connect the repository as in the steps above.
  3. 3 Expect a neutral first check. A new workspace has nothing for a pull request to link, and the check says so.
  4. 4 Build your foundation. Then create the ticket your next pull request implements, and link it in the description.
Build your foundation What the first check means →

What has to be true

These four things must happen, in this order. Each card names where the step is done, the permission it needs, and what the pull request looks like while the step is outstanding.

  1. 1

    Connect GitHub from the account

    Where
    GitHub, on the organization or personal account that owns the repository. On GitHub, select Install.
    Who can do it
    A GitHub owner of the organization. A personal account approves the connection for itself.
    If it is missing
    GitHub sends nothing, so no check appears. Settings → Integrations shows no connection for the account.
    Connect an organization →
  2. 2

    Connect GitHub to this workspace

    Where
    Settings → Integrations → GitHub → Connect GitHub.
    Who can do it
    An Admin on this workspace.
    If it is missing
    The account approved the connection on GitHub, but no workspace claims it. No check appears, and Integrations shows no connection.
  3. 3

    Connect the repository

    Where
    Settings → Integrations → GitHub, in that organization's Repositories list.
    Who can do it
    An Admin on this workspace.
    If it is missing
    No check appears. The GitHub card reads Partial and names the account with no connected repository. This is the step teams miss most often.
  4. 4

    Open or update a pull request after connecting

    Where
    GitHub.
    Who can do it
    Anyone who can open or edit a pull request.
    If it is missing
    Pull requests that were already open when you connected the repository stay silent until a new event arrives.

Steps 2 and 3 are deliberately separate. A GitHub connection proves only that GitHub can deliver the event; a workspace must connect each repository before any pull-request data is read.

The checks to expect

Once the repository is connected, each workspace connected to it publishes its own rows on the pull request, named after that workspace's slug. Each workspace's linked check is its traceability gate; require it in branch protection to block merges on it.

Per workspace

Your workspace slug replaces the placeholder below.

hf.dev / linked / <workspace-slug>
Whether the pull request links an execution-tier artifact, and whether the change has drifted from it.

A red linked check is not a broken integration

A pull request that links no artifact still gets a linked check; it does not go missing. Where the workspace has work to link, the check fails. That red mark is the traceability gate holding, and it clears as soon as the description links the work the change implements.

A new workspace is the exception. If it has no artifacts yet, or no execution-tier artifact, the check is neutral and names the next step. The author did nothing wrong.

Read it the other way round: an absent check is a setup problem, and a failing check is a content problem.

This workspace has no artifacts yet.

Neutral

The description links no artifact, and the workspace has none yet. The first check on a new workspace reads this way. GitHub treats neutral as passing.

Fix: Build your foundation first. Helen drafts it from your repository, and you ratify what is correct.

This workspace has no execution-tier artifact to link.

Neutral

The description links no artifact, and the workspace holds context artifacts but no execution-tier work. GitHub treats neutral as passing.

Fix: Create the project or ticket this pull request implements.

No Helen’s Foundry artifact is linked.

Failure

The description carries no artifact link, and the change needs one.

Fix: Add a link to the project or ticket the change implements.

No execution-tier artifact is linked.

Failure

The description links artifacts, but all of them are context. None is execution-tier.

Fix: Keep the context links and add one execution-tier artifact.

The linked artifact IDs do not resolve in this workspace.

Failure

The links are well formed, but the artifacts do not exist in this workspace. They were deleted, or they belong to another workspace.

Fix: Link an artifact from the workspace connected to this repository.

This pull request does not require an artifact link.

Neutral

The description has a line that starts with no-link: and gives a reason. GitHub treats neutral as passing.

Fix: Nothing is required. Add a link if the change implements planned work.

What counts as a link

  • • A link is a URL that contains /artifact/<uuid>. Put it anywhere in the pull request description.
  • • A bare UUID does not link. The /artifact/ segment is what the check matches.
  • • The host does not matter. Production, preview, and relative links all match.
  • • A link in a commit message or a comment does not count. The check reads the description.

Add a line like this

Implements [Ticket: Fix signup redirect](https://hf.dev/artifact/00000000-0000-4000-8000-000000000000)

The authoring guide covers which artifacts satisfy the gate and how to link several at once.

Connecting does not check pull requests that are already open

Connecting a repository takes effect from the next event onward. It does not reach back over pull requests that were open when you connected it, so those stay silent until something changes on them.

These pull request actions start a check:

openedsynchronizereopenededited

Wake up a pull request you already opened

Any one of these is enough.

  • • Edit the pull request description.
  • • Push another commit to the branch.
  • • Close the pull request and reopen it.