Stale check runs

I’m planning to create an app that uses the Check Runs API. The checks performed on the code will not be automated, and thus could take a very long time to complete. I noticed that if a check is in progress for more than 14 days GitHub will automatically mark the run as stale (https://developer.github.com/v3/checks/runs/). I have a couple of questions about stale check runs:

  1. Can I still update the run status once it is marked as stale?
  2. If the check is required for merging into a protected branch, will the check be still be required after it is marked as stale?

:wave: hello there @danthedaniel, and welcome to the GitHub Support Community! :tada:

  1. Can I still update the run status once it is marked as stale?

Once a check run transitions from the in_progress state to completed state, it’s not possible to modify its status nor its conclusion further. Also, only GitHub can change a check run conclusion to stale as documented in the parameters section for creating a check run.

  1. If the check is required for merging into a protected branch, will the check be still be required after it is marked as stale?

Yes. If a check is required as a part of a protected branch’s settings, the check must pass as noted in About required status checks. A check run with a stale conclusion is not the same as a check run with a success conclusion. I hope this helps!

1 Like

But what about when a check run transitions from in_progress to stale? Can I modify the status then?

But what about when a check run transitions from in_progress to stale ? Can I modify the status then?

@danthedaniel - Great follow-up question!

Every check run has a status and a conclusion.

A status can be one of the following values: queued, in_progress, or completed. Unless otherwise specified, queued is its default status.

Here’s the order in which a status value can change:

  • queued :arrow_right: in_progress :arrow_right: completed

If a check run’s status has a value of either queued or in_progress respectively, its conclusion value will be null.

Here’s why: it’s only when a check run’s status is updated to completed that a conclusion must be provided.

The value of conclusion can be one of the following values:

  • success
  • failure
  • neutral
  • cancelled
  • skipped
  • timed_out
  • action_required
  • stale (:warning: only GitHub can update a check run’s conclusion to this value.)

Thus, when a check run’s status’ value is completed and its conclusion's value is stale, it’s not possible to update that check run with a different conclusion.

If you have a specific use case for which you would find it helpful to update a check run’s conclusion after the conclusion has been determined, we encourage you to share that with our product team our official product feedback form. That’s the best place to share requests like these in consideration for future iterations of GitHub features.

1 Like

Thanks for explaining!

1 Like

Actually I have another follow up question. If a run is marked stale can I create a new check run (from the same app) on the same commit as the original check run?

Basically what I want is some way to be able to require a check run from my GitHub app even though it could take > 2 weeks to perform. The tool I’m planning to build would block merging a PR until a certain label is applied to all associated issues (if there’s another way to do this please let me know).

Because a check suite can have more than one check run, you should be able to create as many check runs from the same application as you’d like on the same commit. I’d be curious to see if that isn’t the case!

Ahh, thanks for sharing that context! One of my colleagues developed a GitHub App called Semantic Pull Request that might be of interest:

Its sole purpose is to ensure that pull requests follow the Conventional Commits spec. It’s built on Probot, a framework for building GitHub Apps in Node.js. You could check out its implementation and possibly adapt it for your project.

I thought it also might be worth sharing––on a cursory search of Probot’s List of Apps, I noticed that there’s a pr_label_enforcer app that enforces certain labels on a PR before merging by using status checks (source @ https://github.com/fossapps/pr_label_enforcer). I can’t say that I’ve used that particular application nor am I able to provide support for either (since I’m neither a maintainer nor owner), but have used semantic-pull-requests in other projects and it works like a charm. :ok_hand:

I hope this helps as some helpful resources to check out as you go about with your project! :raised_hands:

Thank you so much! I should have searched around more because PR Label Enforcer looks like just what I need.

1 Like