What is the function of the `GITLAB_ENV` file?

GitLab CI/CD
1

Problem to solve

In my CI I want to conditionally pass environment variables between stages, but I also wanted to pass environment variables in a script section to another section of the job (see docs)

Use $GITLAB_ENV to pass environment variables defined in the script section to another section.

What I am observing is that the variables stored in the GITLAB_ENV file on one job are cached between pipelines. It seems that its cached per runner.

  1. Is this expected behaviour?
  2. Is there a possibility that I could reset GITLAB_ENV?
  3. Is there any more detailed docs or information on GITLAB_ENV?

If so, then the current way in which the documentation is written is misleading, because GITLAB_ENV is more than just a variable to use to share env variables between sections but actually between pipeline jobs in the same runner!

Steps to reproduce

  1. Try to store an environment variable using artifacts:reports:dotenv and GITLAB_ENV
  2. Run the CI job on branch_a and then on branch_b
  3. Ensure that the CI jobs run on different runners

Configuration

...
setup-el-env-on-branch:
  image: docker:20
  stage: init
  script:
  - cat "$GITLAB_ENV" # debug
  - echo "PKG_TAG_NAME=$PKG_TAG_NAME" | tee -a $GITLAB_ENV >> build.env
  - cat build.env # debug
  - echo "PKG_TAG_NAME=$PKG_TAG_NAME" # debug
  artifacts:
    reports:
      dotenv:
      - build.env
  variables:
    PKG_TAG_NAME: "$CI_COMMIT_REF_SLUG"

package:
  image: docker:20
  stage: package
  variables:
    PKG_TAG_NAME: "$CI_COMMIT_REF_SLUG"
  before_script:
  - cat "$GITLAB_ENV"
  - echo "PKG_TAG_NAME=$PKG_TAG_NAME"
  - cat build.env
...

Versions

Please select whether options apply, and add the version information.

  • Self-managed
  • Dedicated
  • Self-hosted Runners

Versions

  • GitLab: v17.6.3-ee
  • GitLab Runner, if self-hosted: 17.5.4
2

Hi,

Whatever variables you define in a job, are by default shared throughout before_script and script sections, you don’t need to do anything about it usually. Some processes might be more isolated, in that case you might need to do an export before you want another script to use it. after_script is executed in a separate shell, so you cannot access any variables from other two sections.

If you want to pass variables between jobs / stages (no matter which runner), then you store it in a dotenv artifact, as explained in the documentation - so yes, this is expected behavior in that case.

Btw, $GITLAB_ENV is just an example name. You can use whatever name you want to store and pass your variables between jobs. Just make sure they all end up in one file you will specify in artifacts:dotenv section.

3

Thanks @paula.kokic for the swift reply. I have now learnt my lesson that artifacts:reports:dotenv should be used, however my point is specifically on the fact that GITLAB_ENV is more than just an example name.

This variable does have a function, it’s not just a user defined variable. In fact, look at this bug report/issue: GITLAB_ENV is not reset between jobs (#472855) · Issues · GitLab.org / GitLab · GitLab

4

Ah sorry. You meant different sections of the job definition in general.

I’ve never used this variable, but if I understand correctly, then it’s suppose to enable you to use a custom variables produced e.g. in script section, outside of script section. However, I’d still take caution here, because I don’t think you can use it any section - have a look at Where variables can be used | GitLab