Workflow run schema is incomplete

[roy-work]

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?apiVersion=2022-11-28#list-workflow-runs-for-a-repository

What part(s) of the article would you like to see updated?

The JSON schema should actually describe the type of various fields, but the enums are incomplete. For example,

          "status": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "completed"
            ]
          },
          "conclusion": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "neutral"
            ]
          },

We'd like to filter workflow runs to "all completed runs on this branch". So, probably we need to filter on conclusion, but on what value? conclusion here is a enum, but what variants it has (i.e., what values it might carry) aren't described. We know from the example that "neutral" is a possibility, and from querying the API I know "success" is one too. Presumably there's a "cancelled" and a "failed"; the point is this is exactly what the docs, and in particular, a schema, should cover. JSONSchema supports this directly with the "enum" validation, so something like,

          "conclusion": {
            "enum": [
              "success",
              "neutral",
              <etc.>,
              null
            ],

(Possibly wrapped in a oneOf with the other side being a "type": "string" validation, if Github wishes to reserve the addition of values in the future.)

Additional information

This applies to,

• a workflow run's .conclusion
• a workflow job's .conclusion
• a workflow step's .conclusion

It would also help me if the JSONSchema indicated whether these types are all the same type. All of the JSONSchema appears to just inline everything, instead of using $ref to refer to, e.g., a named type or something. So, in a library/implementation, one is forced to assume these are separate. It seems likely that a job conclusion & a step conclusion are the same type, whereas a run is not. (AFAIK, a run cannot be "skipped".)

But this is the sort of questions API docs should answer: are these the same type? Are these enums exhaustive? What variants exist, and what are their semantic meanings?

(& c/p all this to status, and probably a lot of other fields…)

[cmwilson21]

@roy-work Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[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.

[sandokandias]

Hi, while the doc isn't update, could someone from the documentation team post a comment with all the conclusion enum values for run, job, step?

[skedwards88]

@github/c2c-actions-first-responder can you update the OpenAPI schema to reflect the actual values. Once that is done, the docs will update automatically.