publish reference documentation

[Morriz]

What article on docs.github.com is affected?

GitHub Actions / Reference

There seems to be no reference documentation for workflow_run (and many other items for that matter). This is very problematic as it leaves us struggling to find information in the guides, which are not complete in that regard.

[janiceilene]

Hey @Morriz Thanks for reaching out! We've got to make sure our docs balance having every possible answer with being maintainable and readable, so we don't document absolutely everything.

Please keep in mind that repeatedly opening the same issue (or very similar issues), can be considered a violation of the harassment clause of our Code of Conduct.

Thanks so much for your passion in improving the GitHub docs!

[Morriz]

It is more about having answers, but about having reference documentation that is complete...so made by machines, not humans

[Morriz]

@janiceilene where can I take this concern now that I get shut down twice already?

[polarathene]

As a developer using Github Actions this has been a constant frustration as well.

Often when something in the reference is vague, it can be difficult to seek out the answers we seek for clarification. Official responses at best may reference documentation for API responses elsewhere unrelated to Github Actions. That may be sufficient for those familiar with the documentation and API's, but for those whom rarely are involved with needing to look through Github's various docs, it's not a pleasant experience.

Rather than blame the users, consider that the documentation process itself is at fault? You can still provide the balance you want by default, while catering to more complete documentation upon user action, commonly known as progressive disclosure in UX design.

If the concern is regarding duplicate content, the documentation ideally would have a build process that share common data (eg with mkdocs there is a snippets extension for exactly this purpose). I would hope that all the API response examples are not copy/paste into docs, they can be version controlled as separate files and imported as part of the build process.

Regarding any concerns about adding verbosity..

Have admonitions that are collapsed by default like this. When the user is actually interested in the information they can interact with it to view it.

This isn't the first time I saw requests to address problems with the docs being dismissed for such reasons. I hope that Github takes the feedback more seriously, seeing as it has done so well at becoming the dominant CI of choice on it's own platform.

We lose far more time attempting to search and find answers when the documentation lacks. I understand that the pages are lengthy as-is, but I'm provided with structured documents (and ctrl+f) to quickly view content of interest. Meanwhile when information is lacking, I can find multiple users confused and sharing workarounds that aren't safe in github issues or the same questions being asked in the community support forum without any answers for months.

Solid documentation is highly valuable.

[janiceilene]

Thanks for the feedback @polarathene! I've relayed it to the team 💛

[devinrsmith]

Hi @janiceilene,

I've gone down the rabbit hole of trying to learn more about workflow_run fields, following the general path of:

• https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
• https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#workflow_run
• Various external websites
• GitHub Actions: add more details for "workflow_run" event #799
• GitHub Actions: add more details for "workflow_run" event #4435
• And eventually landing on this issue.

Unfortunately, the fields that are accessible through workflow_run are still not apparent to me. Maybe I'm missing some other documentation?

So, I sympathize with the sentiments that @Morriz has expressed - and thought I would pass along my own experience of trying to learn.

My next steps will probably be to start up some ad-hoc workflow_runs so I can export the object to manually introspect the available fields.

[polarathene]

I've gone through a similar experience as @devinrsmith

Presently I had a simpler pull_request event workflow for building and deploying documentation for a project, however became aware that non-collaborators contributions can't run the workflow for security reasons as the blog post explained.

I have no issue with that but documentation / advice is rather scarce.

• I need to have access to pull_request event data for the deployment step (which uses secrets).
• There doesn't appear to be a clear way to transfer that beyond either writing to separate files to upload, or using toJSON expression to simplify (while I only need a small portion of values). This is in addition to the build output that gets deployed.
• Official upload action hasn't been entirely clear with how the name is tied to a workflow run, or if I need to be careful there to avoid overwriting (eg multiple PRs triggering workflow, same PR receiving multiple updates).
  • There's various reports of users uploading artifacts but encountering failures / corruption, with the apparent solution being to compress data in advance before uploading (yet this seems something that the action itself should enable).
  • For some using zstd might help minimize the transfer size and time to compress (as I'm guessing this all contributes towards some limits/costs to keep in mind), but AFAIK this isn't advised whenever I've seen official mentions it's tar and zip. Ubuntu 20.04 seems to at least provide zstd out of the box, again you need to go look for this stuff.
• Download action doesn't support retrieving artifacts from other workflows.
  • So users copy/paste scripts like in the blog post to get what they want done, with some advising others with their own snippets and variations instead of linking or sharing the same source. I've seen some of the advice going around as risky, especially when users react positively to it and reply "+1 works and solved my problem!" when they may not understand the risks/gotchas such as with pull_request_target.
  • While others resort to third-party actions that they may not be able to trust as much (the most popular one atm is dawidd6/action-download-artifact). Someone could get an action popular enough and presumably be compromised or intentionally release a malicious update that does enough damage before it's caught?
  • For a common scenario like this (when trying to be secure), Github taking it more seriously via official action support would go a long way.
• Back to workflow_run, it's difficult to say how much of the pull_request info I can access through the event payload without manually running tests to export/log and inspect it like others are also going through to get access to this information.
  • Others do this and get information, but then without a forked test repo and creating a 2nd account to test the workflow against what we're trying to fix, sometimes find out that information isn't available either (IIRC this was the pull_requests array field being unpopulated).
  • There doesn't appear to be a way to output values like a job/step can do for the workflow_run to read from the workflow that it's been triggered from? Do I need to go through more Github docs on using their JS APIs as a workaround to query info, while passing the minimal required data via file artifact upload/download?
  • The workflow name string has relevance in being used as a trigger, but the documentation is vague on this too. The name field where you set it for a workflow doesn't mention it's relevance elsewhere.
    • Devs on a project I contribute to have opted to share the same workflow name across related workflows because of only seeing it as a UI friendly/pretty name where the job names would avoid duplication (eg Documentation + Build Documentation, or Build Documentation + Build - can just be Documentation(workflow name) + Build(job name)).

Another thing I've tried is creating an environment to isolate the scope of secrets, but that implicitly creates "environment deployments". Multiple issues/discussions have been raised about this being undesirable and wanting to opt-out so they can just provide different environment contexts/scopes, especially with secrets. None of that is documented well that the two things are tied and inseparable.

---

I understand the security issue with third-party pull requests, and I'm trying to resolve it safely. Friction from lack of official support and expending additional effort to understand risk in trusting third-party actions or code snippets, along with considering handing off scripts using github APIs for maintainers to review and accept becoming responsible for isn't great. Github Actions AFAIK is meant to help simplify this and increase the trust in automation.

Going through the experience, I have to wonder why a fix of changing the environment/permissions scope within a single workflow isn't a considered option. For example, running untrusted builds in a sandbox? In my case the build is performed via a run step which uses docker and requires no secrets access. AFAIK there isn't any security problems there but the deployment step can't be run as I can't indicate that the workflow should be safe to allow secrets access.

---

TL;DR: There's quite a bit of friction introduced by a lack of documentation, missing support in official actions (with some issues spanning 1-2 years), leaving many developers to flounder around to piece together a solution and potentially introducing more risks.

[KevinGDialpad]

TL;DR: There's quite a bit of friction introduced by a lack of documentation, missing support in official actions (with some issues spanning 1-2 years), leaving many developers to flounder around to piece together a solution and potentially introducing more risks.

This has been my experience as well.

Hey @Morriz Thanks for reaching out! We've got to make sure our docs balance having every possible answer with being maintainable and readable, so we don't document absolutely everything.

I just found out about github.event.workflow_run.head_branch and it would have saved me a lot of time if that information had been available in the docs. I see the new "Many workflow_run keys, such as head_branch, conclusion, and pull_requests are the same as those in a check_suite object." line now that I know exactly what to look for, but it would have been great to have these keys enumerated and explained. Maintainability and readability are certainly good to keep in mind, but documentation needs to give information about how to use the system.

I don't think leaving things out of the docs is a good idea.

[wichon]

In case of anyone is still wondering what are the properties of the workflow_run event, here is an excerpt of the object:

workflow_run: {
      artifacts_url: 'https://api.github.com/repos/...',
      cancel_url: 'https://api.github.com/repos/...',
      check_suite_id: 123456789,
      check_suite_node_id: 'NODEIDACDEFGHUIADASD',
      check_suite_url: 'https://api.github.com/repos/...',
      conclusion: 'success',
      created_at: '2021-06-07T18:44:28Z',
      event: 'workflow_dispatch',
      head_branch: 'main',
      head_commit: [Object],
      head_repository: [Object],
      head_sha: 'SHAACBADSADAASDASD',
      html_url: 'https://github.com/....',
      id: 123456789,
      jobs_url: 'https://api.github.com/repos/...',
      logs_url: 'https://api.github.com/repos/...',
      name: 'workflow-that-completed',
      node_id: 'NODEIDACDEFGHUIADASD',
      pull_requests: [],
      repository: [Object],
      rerun_url: 'https://api.github.com/repos/...',
      run_number: 14,
      status: 'completed',
      updated_at: '2021-06-07T18:47:28Z',
      url: 'https://api.github.com/repos/...',
      workflow_id: 0987654321,
      workflow_url: 'https://api.github.com/repos/...'
    }

I extracted it using this Action to print the context, hope is of any help :)

[Dao007forever]

Having it in the documentation will help prevent breaking changes. Currently, I'm very much concerned that someday my GHA would stop working for some reasons.

[makeable]

Im raising this again: #23257
This has bitten me, and wasted hours of time trying to find out what is contained in the payload.
Even the reference to check_suite from the previous issues no longer exists...