GitLab CI environment:url Variable Not Expanded

By Kaveh Alemi·Latchkey

environment:url can use variables to point at the deployed app. It is resolved when the deployment is recorded, so a variable defined only inside script (after deploy) may not be available, leaving a literal value.

What this error means

The environment in the UI links to a literal string like ${APP_URL} or an empty URL, instead of the real deployed address.

# Environment URL renders as the literal variable name.
deploy:
  environment:
    name: staging
    url: ${APP_URL}   # APP_URL never set where the URL is resolved

Common causes

Variable defined too late

A URL based on a value computed in script is not available when GitLab records the environment URL.

Dynamic environments need dotenv

Per-deploy URLs (e.g. review apps) must be exported via a dotenv report so the value is available to environment:url.

How to fix it

Export the URL via a dotenv artifact

Write the computed URL to a dotenv file and reference it from environment:url.

deploy:
  script:
    - echo "DYNAMIC_URL=https://${CI_COMMIT_REF_SLUG}.example.com" >> deploy.env
  artifacts:
    reports:
      dotenv: deploy.env
  environment:
    name: review/${CI_COMMIT_REF_SLUG}
    url: ${DYNAMIC_URL}

Use static, predefined variables

1. For fixed environments, build the URL from predefined variables like CI_COMMIT_REF_SLUG.
2. Avoid relying on values that only exist inside the running script.
3. Confirm the environment URL renders correctly after one deploy.

How to prevent it

• Use a dotenv report to pass dynamic URLs to environment:url.
• Prefer predefined CI variables for static environment URLs.
• Verify the environment link in the UI after deploys.

Frequently asked questions

Related guides

References

• GitHub Actions documentation