Actions: Workflow dispatch API does not accept SHA commit hash as ref

[Simran-B]

What article on docs.github.com is affected?

https://docs.github.com/en/free-pro-team@latest/rest/reference/actions#create-a-workflow-dispatch-event

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

According to the docs, POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches accepts a commit hash as reference:

Name	Type	In	Description
ref	string	body	Required. The reference of the workflow run. The reference can be a branch, tag, or a commit SHA.

This isn't the case:

{
  "message": "No ref found for: {hash}",
  "documentation_url": "https://docs.github.com/rest/reference/actions#create-a-workflow-dispatch-event"
}

Only branch and tag names are accepted. Or is there an undocumented key or syntax for the value to reference a commit hash?

Additional information

https://gh.neting.ccmunity/t/workflow-dispatch-cant-set-ref-to-commit-sha/138132

[janiceilene]

Thanks for the issue @Simran-B! I'll send this over to the ecosystem team to look at 👀

[tie]

@janiceilene also it looks like it doesn’t accept PR refs like refs/pull/3/head.

[lucascosti]

Thanks for opening this, @Simran-B! I'll try and confirm with the engineering team that the docs are incorrect and this isn't a product bug.

[lucascosti]

Ok, confirmed that SHA functionality is not implemented in the API at the moment. Because the source for the API docs is in a separate internal repo, I'll open a fix that will fix this issue. 🚀

[lucascosti]

Thanks all! This fix is now live 🚀

[matfax]

FYI, I've opened a discussion about this, since this fix only concerns the documentation, not the missing feature itself.

community#75513