It is not clear what values belong to the conclusion or the status fields of a workflow run

[compdemo0908]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/rest/actions/workflow-runs#list-workflow-runs-for-a-workflow

What changes are you suggesting?

Issue 1.

The following values presented on the article linked above:

Can be one of: completed, action_required, cancelled, failure, neutral, skipped, stale, success, timed_out, in_progress, queued, requested, waiting

Are not clearly separated between status and conclusion categories.

The first two lines make the whole paragraph ambiguous:

Returns workflow runs with the check run status or conclusion that you specify. For example, a conclusion can be success or a status can be in_progress

Which seem to indicate that conclusion could also be a query parameter

Expected outcome

Can you please redact the {status} parameter documentation of the API call (see article section):
https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/runs

And separate the values in the list above by assigning them to status and conclusion respectively.

Issue 2.

It also would be great to make sure that conclusion is not misrepresented as a query parameter for that specific API call on the first sentence by using ambiguous language.

Returns workflow runs with the check run status or conclusion that you specify

As we cannot specify a conclusion value as a query parameter, the result is the same as querying for all runs in the workflow. And there's no conclusion parameter indicated.

For example, for a cancelled workflow run the payload contains the following:

Query:
https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run

Response:

"status": "completed",
"conclusion": "cancelled",

Use case

We would like to take a 2 step process where:

1. We find out the status of an specific workflow run
2. Report and FAIL/SUCCEED based on the value in the conclusion

See additional information for more details.

Additional information

It is confusing to tell what to query for in the returned JSON payload when looking at an specific workflow run by id to find out if it was completed or not, since the only text that has an exhaustive list of statuses and conclusions is in the affected article and that text is ambiguous.

This is the query I'm actually using with short polling, the use case is that given a workflow run id, find out when it is completed and report the conclusion by calling this endpoint.

https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID

According to this API call:
https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run

Also, as you can see on the Response schema sections of each api call section the only example given is complete.

P.S.
Instead of recurring to the docs, I had to go outside of the Github docs to find out the disambiguation information I needed:
https://tabris.com/observing-workflow-run-status-on-github/

Value of the status property can be one of: “queued”, “in_progress”, or “completed”. When it’s “completed,” it makes sense to check if it finished successfully. We need a value of the conclusion property. Can be one of the “success”, “failure”, “neutral”, “cancelled”, “skipped”, “timed_out”, or “action_required”.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

@compdemo0908 Thanks for opening an issue and providing all these great details. I'll get this triaged for review! ⚡

[docubot]

Thank you for opening this issue! Updates to the REST/GraphQL API description must be made internally. I have copied your issue to an internal issue, so I will close this issue.

[docubot]

Thank you for opening this issue! Changes to the REST API schema can be requested in github/rest-api-description. I will transfer your issue over to that open source repo.

[CalvinWilkinson]

I personally agree with the original author of this issue. I have been dealing with the workflow runs API as of late and it has caused me some issues and confusion as to not knowing which JSON key can hold which value. The API documentation is also unclear and it is ambiguous.

Is there a list or something out their that tells us what values the status key can be and what values the conclusion key can be?

[mike-phillips]

@CalvinWilkinson fwiw at this point, see the final text of the issue:

Value of the status property can be one of: “queued”, “in_progress”, or “completed”. When it’s “completed,” it makes sense to check if it finished successfully. We need a value of the conclusion property. Can be one of the “success”, “failure”, “neutral”, “cancelled”, “skipped”, “timed_out”, or “action_required”.

[drasikhov]

There is still no clear disambiguation about this in the official API documentation. Come on, how difficult can it be to add this information? People keep wasting their time trying to get the correct answer and having to rely on 3rd parties info or experimenting with statuses.

[drasikhov]

@CalvinWilkinson fwiw at this point, see the final text of the issue:

Value of the status property can be one of: “queued”, “in_progress”, or “completed”. When it’s “completed,” it makes sense to check if it finished successfully. We need a value of the conclusion property. Can be one of the “success”, “failure”, “neutral”, “cancelled”, “skipped”, “timed_out”, or “action_required”.

@mike-phillips unfortunately that info is a bit outdated. Currents API docs now mention:

Only GitHub Actions can set a status of waiting, pending, or requested.

That looks like it can be applied only to status, although the "Only GitHub Actions can set a status" part is a bit unclear. Does that mean that this status can only be set from the action itself and there are some other non-GitHub Actions?

And also there is stale. And it's hard to say if that's applicable to status or conclusion.

[Errorbot1122]

Vary confusing API Docs... TBH vary little docs, that obviously show the need for trial and error, are better then bloated docs that seem complete, but vary much are not 😕