---

🔍 Example You Gave:

DOCKER_IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG"
Code language: JavaScript (javascript)

🔹 Explanation:

Variable	Purpose
CI_REGISTRY_IMAGE	Built-in CI variable — the full image path for your project’s Container Registry (e.g., registry.gitlab.com/mygroup/myproject)
CI_COMMIT_REF_SLUG	Built-in CI variable — a simplified, URL-safe version of your branch/tag name (e.g., main, feature-login)
DOCKER_IMAGE	Custom variable created inside gitlab-ci.yml by using other variables

➡️ This means you’re building something like:

DOCKER_IMAGE=registry.gitlab.com/mygroup/myproject:main

---

📦 Ways to Define Variables in GitLab

Here are all the places where you can define and use GitLab CI/CD variables, and how they behave:

---

1. 🧾 gitlab-ci.yml (Project-Level Static)

variables:
  ENV: "production"
  DOCKER_IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG"
Code language: JavaScript (javascript)

| ✅ Use Case | Fixed values used across the pipeline (e.g., timeouts, env labels) |
| ⚠️ Security | Not encrypted; not for secrets |
| 🔁 Scope | Global or job-specific |

---

2. 🔒 GitLab UI → Project Settings > CI/CD > Variables

GitLab.com path: Project → Settings → CI/CD → Variables

| ✅ Use Case | Store secrets, API keys, tokens, passwords |
| 🔒 Security | Encrypted at rest, not visible in job logs by default |
| 🧠 Scope | Project, group, or environment |
| 🔄 Runtime options | Protect (only runs on protected branches/tags), Mask (hide value), File (export as file) |

---

3. 🌍 Group-Level CI/CD Variables

Group → Settings → CI/CD → Variables

| ✅ Use Case | Share CI/CD secrets across multiple projects in a group |
| 📦 Example | Docker credentials, shared API tokens |
| 📌 Inherited by | All projects within the group/subgroup (unless overridden) |

---

4. 🧠 Environment-Specific Variables (Scoped)

In the UI, add a variable and set its scope:

Key: AWS_KEY
Environment scope: staging

| ✅ Use Case | Different values for dev, staging, production |
| ⚠️ Behavior | Used only in jobs running for that environment |
| 📌 Tip | Use environment: keyword in job to match |

---

5. 🧪 Job-Level Variable Overrides

deploy_prod:
  stage: deploy
  script:
    - echo $ENVIRONMENT
  variables:
    ENVIRONMENT: "production"
Code language: PHP (php)

| ✅ Use Case | Override for one job only |
| 🔁 Scope | Temporary within that job |
| 🧩 Can override global/project/group variables ✅ |

---

6. ⌨️ Trigger Pipeline Variables (via API or UI)

Trigger pipeline with dynamic values:

curl --request POST \
  --form token=TRIGGER_TOKEN \
  --form ref=main \
  --form "variables[RELEASE_ENV]=staging" \
  https://gitlab.com/api/v4/projects/123456/trigger/pipeline
Code language: JavaScript (javascript)

| ✅ Use Case | External scripts, GitOps, dynamic environments |
| 📩 Value injected | At pipeline run time |

---

7. 🧱 .gitlab-ci.yml Includes + Templates

Variables can also come from included YAML:

include:
  - project: 'common/ci-templates'
    file: '/templates/vars.yml'
Code language: PHP (php)

---

✅ Summary Table

Method	Encrypted?	Scope	Best For
.gitlab-ci.yml	❌	Global/Job	Static config vars, labels
Project UI Variables	✅	Project-wide	Secrets, tokens, credentials
Group Variables	✅	Multi-project	Shared cloud keys, API access
Environment-Scoped Variables	✅	Per environment	Per-env secrets (e.g., AWS creds)
Job-Level Variables	❌	Single job	Overrides, temp flags
Trigger Variables (API/UI)	✅	Pipeline runtime	GitOps, external triggers

---

Would you like:

• A visual map of where each variable type fits in CI/CD flow?
• A script or .yml template showing overrides in action?
• Best practices to secure variables in shared runners?