docs Add generic information on how the environment files work for GitHub Action Workflow Commands

Add generic information on how the environment files work for GitHub Action Workflow Commands

Open jessehouwing opened this issue 1 year ago • 4 comments

Code of Conduct

[X] 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/actions/using-workflows/workflow-commands-for-github-actions?ref=jessehouwing.net&tool=powershell#environment-files

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

The code samples explain how to use bash or PowerShell to set variables and such, but don't explain the concept of the environment files very well. There is no need to do this explicitly in Bash or PowerShell, one can do it from msbuild or C# or a node script once you understand how it works.

I propose to either add a separate page or a paragraph in the "environment files" section, explaining the underlying concept of the $GITHUB_OUTPUT variable containing the file name in which these output variables are stored. And that "a-b">>$GITHUB_OUTPUT basically appends a line to the bottom of that file. And to document that that file needs to be written in utf-8 encoding.

That way you can easily translate that to C#, or msbuild, or python or java or node or go or anything else. Any tool that runs inside the workflow can interact with the agent in this way.

Additional information

No response

Feb 10 '24 11:02 jessehouwing

@jessehouwing Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

Feb 12 '24 16:02 nguyenalex836

Hey @jessehouwing, thanks so much for opening this issue! ✨

I agree that we could do a better job of explaining what environment files are and how they work in this section.

We should update the paragraph in Environment files to include the following information:

Add brief examples of what environment files can do, such as storing job outputs or environment variables so you can use them in subsequent steps and jobs.
We can edit the following sentence:

The path to these files are exposed via environment variables.

We should communicate that you can use GitHub's default environment variables to access the path to these files and edit them. We could also link to Default environment variables so it's easy to see a list of available environment files.

You or anyone else is welcome to open a pull request to make these changes!