Cannot get !reference to work in .gitlab-ci.yaml

2 min read 05-10-2024

"Cannot get !reference to work in .gitlab-ci.yaml": Unveiling the Secrets of GitLab CI/CD Variables

Have you ever encountered the frustrating "Cannot get !reference to work in .gitlab-ci.yaml" error in your GitLab CI/CD pipeline? This commonly arises when you're trying to use variables declared in one stage within another stage. Let's demystify this error and empower you to confidently utilize GitLab CI/CD variables.

Understanding the Problem

In essence, GitLab CI/CD pipelines run in a sequential manner, stage by stage. The "Cannot get !reference" error usually means you're attempting to access a variable that hasn't been defined yet. Think of it like trying to open a door that's locked from the inside – you need the key (variable) to access what's on the other side.

Example Scenario

Let's illustrate with an example:

stages:
  - build
  - deploy

variables:
  BUILD_VERSION: "1.0.0"

build:
  stage: build
  script:
    - echo "Building version: $BUILD_VERSION"

deploy:
  stage: deploy
  script:
    - echo "Deploying version: $BUILD_VERSION"

In this scenario, BUILD_VERSION is defined at the pipeline level. The build stage can access this variable successfully. However, the deploy stage might encounter the "Cannot get !reference" error because it attempts to access BUILD_VERSION before it's been set.

The Solution: Leveraging `global` and `stage` Variables

GitLab CI/CD provides two key concepts for handling variable scope:

global variables: These are defined at the top level of your .gitlab-ci.yaml file and are available across all stages.
stage variables: These are defined within individual stages and are only accessible within those stages.

To fix the Cannot get !reference error in our example, we can declare BUILD_VERSION as a global variable:

stages:
  - build
  - deploy

variables:
  BUILD_VERSION: "1.0.0" 

build:
  stage: build
  script:
    - echo "Building version: $BUILD_VERSION"

deploy:
  stage: deploy
  script:
    - echo "Deploying version: $BUILD_VERSION"

By declaring BUILD_VERSION globally, both build and deploy stages can access it without encountering the Cannot get !reference error.

Additional Tips

Use the !reference syntax carefully. This syntax is intended for dynamic variable access, particularly when using job variables. It's generally not necessary for referencing variables defined at the pipeline level.
Consider CI_COMMIT_REF_NAME and other built-in variables. GitLab CI/CD offers a plethora of built-in variables, such as CI_COMMIT_REF_NAME, CI_PIPELINE_ID, and CI_PROJECT_NAME, which can be handy in different scenarios.
Utilize include for code reuse. The include keyword allows you to include external YAML files, making your .gitlab-ci.yaml more organized and manageable. This can be especially helpful for sharing variables across multiple pipelines.

Conclusion

By understanding variable scopes and leveraging the global and stage mechanisms, you can effectively manage variables within your GitLab CI/CD pipelines and avoid the Cannot get !reference error. Remember to explore the extensive built-in variable options and consider include for code modularity. Armed with this knowledge, you can confidently navigate the intricacies of GitLab CI/CD variable management and create powerful, efficient pipelines.

Cannot get !reference to work in .gitlab-ci.yaml