Sitelet https://web.archive.org/web/20230815011759/https://github.com/github/docs/issues/7892
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

GITHUB_ENV need more complete examples #7892

Closed
jsoref opened this issue Jul 2, 2021 · 8 comments
Closed

GITHUB_ENV need more complete examples #7892

jsoref opened this issue Jul 2, 2021 · 8 comments
Labels
actions This issue or pull request should be reviewed by the docs actions team content This issue or pull request belongs to the Docs Content team
Projects
Docs open source board

Comments

@jsoref
Copy link
Contributor

jsoref commented Jul 2, 2021

What article on docs.github.com is affected?

https://docs.github.com/en/actions/reference/environment-variables#about-environment-variables makes a passing reference to GITHUB_ENV

https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable

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

All of the environment related "examples", the first one is almost an example, but even it isn't, and the rest are even less so.

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      echo "${{ env.action_state }}" # This will output 'yellow'

This shows using an env var via ${{ env.* }}

It doesn't show that ${{env.*}} won't work in the previous step (which is kinda important).

(Stylistically, it'd be nice if there was a comment in the first line of each of these example fragments that pointed to code one could copy to get the rest of the boilerplate to have a working example.)

steps:
  - name: Set the value
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://httpbin.org/json >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV

This doesn't show that it won't be available in this step, and it doesn't show what it looks like when it's used.

echo "$HOME/.local/bin" >> $GITHUB_PATH

This is even less of an example.

A better example would use which or command -v both right after the echo, and in the next step to show the impact.

Additional information

https://github.community/t/following-github-actions-tutorial-but-getting-an-npm-eacces-error/188088/4
@jsoref jsoref added the content This issue or pull request belongs to the Docs Content team label Jul 2, 2021
@github-actions github-actions bot added the triage Do not begin working on this issue until triaged by the team. label Jul 2, 2021
@github-actions github-actions bot added this to Triage in Docs open source board Jul 2, 2021
@janiceilene
Copy link
Collaborator

@jsoref Thanks for opening an issue! I'll triage this for the team to take a look 👀

Just a heads up, the team is out for the next two weeks, so we'll be very slow to respond 💛

@janiceilene janiceilene removed the triage Do not begin working on this issue until triaged by the team. label Jul 2, 2021
@janiceilene janiceilene moved this from Triage to Content review needed in Docs open source board Jul 2, 2021
@janiceilene janiceilene added the actions This issue or pull request should be reviewed by the docs actions team label Jul 2, 2021
@jsoref jsoref mentioned this issue Jul 2, 2021
Closed
@Simran-B
Copy link
Contributor

Simran-B commented Jul 3, 2021

It doesn't show that ${{env.*}} won't work in the previous step (which is kinda important).

Setting an environment variable (second link) talks about that almost exclusively:

Creates or updates an environment variable for any actions running next in a job. The action that creates or updates the environment variable does not have access to the new value, but all subsequent actions in a job will have access.

Are you saying that the examples should reiterate this information?

@jsoref
Copy link
Contributor Author

jsoref commented Jul 4, 2021

Maybe.

Tangentially, every instance of action here should say step instead:

Creates or updates an environment variable for any actions running next in a job. The action that creates or updates the environment variable does not have access to the new value, but all subsequent actions in a job will have access. Environment variables are case-sensitive and you can include punctuation.

Anyone using runs: instead of uses: isn't using an action.

The article isn't exclusively about GITHUB_ENV, so it's pretty easy to not choose to read it top to bottom.

@lucascosti
Copy link
Contributor

lucascosti commented Jul 14, 2021 •
edited

Thanks for opening this, @jsoref.

🤔 I agree with @Simran-B that I think the 'next step' behavior is already adequately covered for the docs both the first articles mention, and in the second articles section.

Tangentially, every instance of action here should say step instead:

The step vs action wording should be cleaned up, and is already covered by this issue that is open for anyone to make a PR to fix: #7553.

Docs open source board automation moved this from Content review needed to Done Jul 14, 2021
@bauergeorg
Copy link

Hi folks,

du you have an example for two environment variables? I try to set this with python but I have a lot's of trouble :(
(see https://stackoverflow.com/questions/70123328/how-to-set-environment-variables-in-github-actions-using-python)

Thanks Georg

@jsoref
Copy link
Contributor Author

jsoref commented May 12, 2022

Hi @bauergeorg. I'm glad you were able to find this ticket -- it's a perfect match to your problem. Your stack overflow and comment here are exactly the evidence supporting my request that github add one to the docs.

I'm not entirely unsympathetic to the GitHub team's response. Some things (like explaining how environment variables are scoped to child processes) legitimately have to be out of scope for GitHub documentation.

It does look like someone gave a correct answer on SO, which is good...

@bauergeorg
Copy link

Hey @jsoref, thanks for your answer. I found a solution. You have to set a linebreak between your two or more environment variables. I was a little bit confused by this bug.
Thanks!

@lucascosti
Copy link
Contributor

found a solution. You have to set a linebreak between your two or more environment variables.

Thanks for this feedback, @bauergeorg. Yep, this is correct. It's implied by the >> in the commands of echoing the variable in the examples in Setting an environment variable, but feel free to open a PR to mention it in the description there so that it's more explicit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
actions This issue or pull request should be reviewed by the docs actions team content This issue or pull request belongs to the Docs Content team
Projects
Docs open source board
Done
Milestone
No milestone
Development

No branches or pull requests
7 participants
@jsoref @lucascosti @Simran-B @janiceilene @bauergeorg and others