How to set and access a Workflow variable?


I would like to simplify my workflow by using a variable at certain places. That workflow ultimately becomes some kind of a template and I would like to make it as easiest as possible for people to maintain it, when they have created their own copy of that workflow. Therefore I was thinking to declare a global variable and use it in the workflow at many places:

It basically looks like this and people should only be required to maintain the pluginId:

  pluginId: 'plugin-fn-xml-node'

      - ${{env.pluginId}}/**
      - .github/workflows/**
      - ${{env.pluginId}}/**
      - '.github/workflows/**'

      working-directory: ${{env.pluginId}}
    runs-on: ubuntu-latest

        node-version: [8.x, 10.x, 12.x]


That fails with the error message:

Your workflow file was invalid: The pipeline is not valid. .github/workflows/fn-xml-node-tests.yml (Line: 7, Col: 9): Unrecognized named-value: 'env'. Located at position 1 within expression: env.pluginId,.github/workflows/fn-xml-node-tests.yml (Line: 11, Col: 9): Unrecognized named-value: 'env'. Located at position 1 within expression: env.pluginId

It’s stated here: that workflow (global) variables are supported, but I don’t find a way to get it working. Unfortunately the documentation isn’t much talking about Workflow-Variables.

Can someone tell me, if this is possible? And if yes, what I’m doing wrong.




I guess you don’t need the env prefix,  just use the var name {{ pluginId }}

Currently, we have no ways to call environment variables on job level, ideally the syntax ${{ env.VAR_NAME }} should work but just has not been implemented yet. It’s being tracked internally, but I don’t have any timeline to share yet. On step level, ${{ env.VAR_NAME }} is working fine.

In addition, when defining environment variables, you only can use alphanumeric characters and _  character (not - character) to name the environment variables, and environment variables are case-sensitive.


Hi @rigobcastro,

Thanks for the response. Unfortunately the error also that way remains. I tried:

${{ pluginId }} and {{ pluginId }}

Any other ideas?

Hi @brightran,

That’s interesting feedback. But then I don’t understand why I can even declare an environment variable at workflow level. If I declare something, it should be possible to reference it somewhere in the workflow file.
Also, it’s stated here that the feature is available:

Or is this something different? And really thanks for the hint regarding the allowed characters.


Yeah, we can define environment variables at workflow level, job level and step level.
And ideally, the workflow level environment variables can be used at all jobs and steps in the workflow, the job level environment variables can only be used at all steps in the current job, and the step level environment variables can only be used at current step.

But now, the workflow level environment variables can’t be used at job level. I’m not sure why it is not supported initially. This problem had been reported to the appropriate engineering team for further investigation and evaluation.

As I metioned previously, the engineering team is considering to make the syntax  ${{ env.VAR_NAME }}  also work at job level, but they do not share any timeline.

Apologize for the inconvenience caused to you.


How can we know when this is available? We want to re-use a global scope variable in more than 5 jobs.

    (github.event.action == ‘synchronize’ && contains(github.event.pull_request.labels.*.id, 584780719))
    (github.event.action == ‘labeled’ && == 584780719)

1 Like

Use a secret?

Three months have passed and it still seems a problem. Proper scoping and cascading of env vars for the workflow definiton seems to me like a pretty important feature.


I am not completely sure what you mean, but the following currently works:

name: Show env

      - '*'
  somevar: 'lastvar'
    runs-on: ubuntu-latest
      - name: Is variable exported?
        run: |
          echo "${{ env.somevar }}"

What does not work is to change this variable from one job and have it available in another job (of course with needs ). To use it for settings sharing. (What I do now is to create a JSON at the end of settings job and then use it in all following jobs.)



This is an important feature!

Perhaps the docs should be very clear about this if is not ready yet. I spent hours without realizing it is not supported.



Any updates on this? This is a crucial feature.

I’m not sure if its a recent thing, but the functionality works fine for me. Global env which is usable in steps.

The problem states that the workflow env var is not available at job level configuration.

The example you demonstrate here (which does work) is to use a workflow level env var at the step level. If you change your example to move the ${{ env.somevar }} reference from the step up to the job level, it will fail.

The problem clearly states the workflow env is not usable at the job level. Step level references are fine, but job-level references break (as demonstrated in the example).

1 Like

Probably simplest workaround right now:

  1. Set Environment Var
  2. Step takes it as input and sets it as the step’s output.
  3. Environment variable can now be accessed via ‘needs’.

Of course, this lacks quite a few characteristics of typical env-vars, most importantly the ability to change them dynamically in a run.

1 Like

Any updates on this? my usecase is creating a firebase.config.js file via echo ${{SOME_SECRET_CONTENT}}

I would also like to see this implemented. I’m setting a couple of env vars on the workflow level and then I’m trying to use them on the job-level’s if-statement;

name: Deploy
on: push

  SRC: './'
  PROD: 'user@prod-host:/path/to/site/'
  # STAGE: 'user@stage-host:/path/to/site/'

    # Only run job if stage is set and this is NOT a version tag push OR if prod is set and this IS a version tag push
    if: (env.STAGE && !startsWith(github.ref, 'refs/tags/v')) || (env.PROD && startsWith(github.ref, 'refs/tags/v'))