[Schema Inaccuracy] Undocumented "Pending" State for a Check Suite

[Avenel]

Schema Inaccuracy

Hello,

This inaccuracy is about a missing state of a Check Suite which is not included in the schema (for reference: Check Suite API Documentation). The documented states for Check Suite API response are "queued", "in_progress", and "completed". However, I have encountered an additional state, namely "pending".

In addition I have seen this state (and some more) in the GraphQL API documentation for a CheckSuiteState Enum.

Expected

The state pending and the other missing states documented in the CheckState Enum are in the schema for all occurrences (e.g., in the REST API call for getting a list of all Check Suites) of the property status of a Check Suite.

Reproduction Steps

This "pending" state can be induced by implementing a concurrency within a workflow. This action prevents the same workflow from being executed simultaneously. Here's an example of how this might be set up in YAML:

name: Do something

on:
  push:
    branches:
    - main
    
concurrency: test

jobs:
  one:
    runs-on: ubuntu-latest
    name: Do it
    steps:
    - name: Checkout repository
      uses: actions/checkout@v3
    - name: Wait
      run: |
        sleep 120

When this workflow is triggered twice, the API response includes the "pending" state:

{
  "id": 9170123123,
  "node_id": "CS_kwSOJbvS3c8AAAADsy2zEw",
  "head_branch": "main",
  "head_sha": "3bcc59988530adbb6e031f1b526a763e7418d920",
  "status": "pending",
  "conclusion": null,
  "url": "https://api.github.com/repos/my-test-repo/wf-test/check-suites/15291018543",
  ...
  "pull_requests": [],
  "app": {
    "id": 15238,
    "slug": "github-actions",
    ...
  }
}

Thank you in advance for looking into this.

Best Regards.

[shiftkey]

@Avenel apologies for the delay in replying. I've reached out to the feature team to confirm this field is expected, and hopefully we can get the docs updated in the coming days.

[KetchupOnMyKetchup]

@Avenel @shiftkey -

Hi there, I'm part of the feature team owning this API.

There are 2 types of Check Suites to consider:

• dotcom general Check Suites
• Actions specific Check Suites

pending is a valid Check Suite state for Actions specific Check Suites only.

I don't think we should add it to the enum (mentioned in description here - https://github.com/github/c2c-actions-support/issues/3114) since its not true for regular non-Actions Check Suites.

But we think that it would be really good to add a note on the API Docs that pending is a valid state for Actions specific Check Suites. It seems that when the new state was introduced, adding the note to the docs was forgotten at that time. Please let me know how I can assist. Thank you!

[KetchupOnMyKetchup]

Created issue on our backlog and will prioritize for our next Doc-a-thon which will be next quarter. Thank you so much for surfacing this!

https://github.com/github/actions-build/issues/265

[Avenel]

Hello @KetchupOnMyKetchup,

Thank you for your contribution to this discussion. I'm seeking some clarification to better understand the context of your answer. Could you please explain in more detail the differences between a "dotcom general Check Suite" and a "Actions specific Check Suite"?

In addition, it would be helpful if you could provide the API routes for each type, in case they differ. Or a different way to differentiate them using the API.

Best Regards.

[brittanyellich]

Hi @Avenel ,

I recently picked up this issue to close it out, but wanted to respond to your question. A "dotcom general Check Suite" is referring to a check suite created using the Checks API, while an Actions specific Check Suite is a check suite created by GitHub Actions. GitHub Actions uses check suites and can set some additional statuses that aren't available to be set using the Checks API (pending, waiting, and requested).

Thank you so much for submitting this issue!