{"id":164945,"date":"2026-03-28T12:11:13","date_gmt":"2026-03-28T09:11:13","guid":{"rendered":"https:\/\/computingforgeeks.com\/gitlab-cicd-variables-inputs\/"},"modified":"2026-03-28T12:55:29","modified_gmt":"2026-03-28T09:55:29","slug":"gitlab-cicd-variables-inputs","status":"publish","type":"post","link":"https:\/\/computingforgeeks.com\/gitlab-cicd-variables-inputs\/","title":{"rendered":"Configure GitLab CI\/CD Variables and Inputs with Real Examples"},"content":{"rendered":"\n

GitLab CI\/CD variables control how pipelines behave. They inject configuration, credentials, and runtime data into your jobs without hardcoding values in .gitlab-ci.yml<\/code>. The problem is that GitLab has multiple variable types, scopes, and precedence rules, and the documentation scatters them across eight different pages. This guide consolidates everything into one practical reference with working examples from a real GitLab 18 server.<\/p>\n\n\n\n

Tested March 2026<\/strong> | GitLab CE 18.10.1 on Ubuntu 24.04 LTS, GitLab Runner 18.10.0, shell executor<\/em><\/p>\n\n\n\n

Every example in this article ran on a live GitLab instance. The pipeline outputs, screenshots, and job logs are real, not fabricated. If you want to follow along, you’ll need a GitLab instance with at least one registered runner. Our guides cover installing GitLab on Ubuntu\/Debian<\/a> and Rocky Linux\/AlmaLinux<\/a>.<\/p>\n\n\n\n

How GitLab Variables Work<\/h2>\n\n\n\n

Every CI\/CD job runs in an environment where variables are injected as standard environment variables. There are three sources:<\/p>\n\n\n\n

    \n
  1. Predefined variables<\/strong>: GitLab injects 150+ variables automatically (commit SHA, branch name, pipeline ID, project path, runner info, and more)<\/li>\n\n\n\n
  2. Custom variables<\/strong>: you define them in .gitlab-ci.yml<\/code>, the project\/group settings UI, or via the API<\/li>\n\n\n\n
  3. Dotenv variables<\/strong>: jobs create them at runtime and pass them to downstream jobs through artifacts<\/li>\n<\/ol>\n\n\n\n

    GitLab 17+ also introduced inputs<\/strong>, which are typed parameters resolved at pipeline creation time. Unlike variables (which can change during execution), inputs are immutable once the pipeline starts. They use a different syntax ($[[ inputs.name ]]<\/code> vs $VARIABLE<\/code>) and serve a different purpose: making reusable pipeline templates.<\/p>\n\n\n\n

    Predefined Variables<\/h2>\n\n\n\n

    GitLab automatically sets variables for every pipeline and job. You don’t need to define them. Here’s a pipeline job that prints the most useful ones:<\/p>\n\n\n\n

    show-predefined-vars:\n  stage: info\n  script:\n    - echo \"Commit SHA   - $CI_COMMIT_SHA\"\n    - echo \"Short SHA    - $CI_COMMIT_SHORT_SHA\"\n    - echo \"Branch       - $CI_COMMIT_REF_NAME\"\n    - echo \"Pipeline ID  - $CI_PIPELINE_ID\"\n    - echo \"Source        - $CI_PIPELINE_SOURCE\"\n    - echo \"Project      - $CI_PROJECT_NAME\"\n    - echo \"Job ID       - $CI_JOB_ID\"\n    - echo \"Runner       - $CI_RUNNER_DESCRIPTION\"\n    - echo \"Triggered by - $GITLAB_USER_LOGIN\"<\/code><\/pre>\n\n\n\n
    The actual output from our GitLab server:<\/p>\n\n\n\n
    Commit SHA   - f46a0e647fbd830b2c10c4b10ec4d9988a63d3f6\nShort SHA    - f46a0e64\nBranch       - main\nPipeline ID  - 2\nSource        - push\nProject      - ci-variables-demo\nJob ID       - 17\nRunner       - Shell runner on GitLab server\nTriggered by - root<\/code><\/pre>\n\n\n\n
    \"GitLab<\/figure>\n\n\n\n
    The most commonly used predefined variables:<\/p>\n\n\n
    \n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
    Variable<\/th>\nContains<\/th>\nAvailable in rules:if?<\/th>\n<\/tr>\n<\/thead>\n
    CI_COMMIT_SHA<\/code><\/td>\nFull 40-character commit hash<\/td>\nYes<\/td>\n<\/tr>\n
    CI_COMMIT_SHORT_SHA<\/code><\/td>\nFirst 8 characters of the commit hash<\/td>\nYes<\/td>\n<\/tr>\n
    CI_COMMIT_REF_NAME<\/code><\/td>\nBranch or tag name<\/td>\nYes<\/td>\n<\/tr>\n
    CI_COMMIT_BRANCH<\/code><\/td>\nBranch name (empty in MR pipelines)<\/td>\nYes<\/td>\n<\/tr>\n
    CI_PIPELINE_SOURCE<\/code><\/td>\nHow the pipeline was triggered (push, web, schedule, api, trigger, merge_request_event)<\/td>\nYes<\/td>\n<\/tr>\n
    CI_PIPELINE_ID<\/code><\/td>\nUnique pipeline ID across the instance<\/td>\nNo (persisted)<\/td>\n<\/tr>\n
    CI_JOB_ID<\/code><\/td>\nUnique job ID<\/td>\nNo (persisted)<\/td>\n<\/tr>\n
    CI_JOB_TOKEN<\/code><\/td>\nToken for authenticating API calls within the job<\/td>\nNo (persisted)<\/td>\n<\/tr>\n
    CI_PROJECT_ID<\/code><\/td>\nNumeric project ID<\/td>\nYes<\/td>\n<\/tr>\n
    CI_DEFAULT_BRANCH<\/code><\/td>\nDefault branch name (usually main)<\/td>\nYes<\/td>\n<\/tr>\n
    CI_REGISTRY_IMAGE<\/code><\/td>\nContainer registry address for the project<\/td>\nYes<\/td>\n<\/tr>\n
    GITLAB_USER_LOGIN<\/code><\/td>\nUsername of who triggered the pipeline<\/td>\nYes<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n\n\n
    Variables marked “No” under rules:if<\/code> are persisted variables<\/strong>. They contain tokens or sensitive data and are only available inside running jobs, not during pipeline creation. Trying to use CI_JOB_ID<\/code> in a rules:if<\/code> expression will always evaluate to empty.<\/p>\n\n\n\n
    Custom Variables in .gitlab-ci.yml<\/h2>\n\n\n\n
    Define variables at two levels: globally (available to all jobs) or per-job (scoped to that job only).<\/p>\n\n\n\n
    variables:\n  APP_NAME: \"my-web-app\"\n  APP_VERSION: \"2.1.0\"\n  DEPLOY_ENV:\n    value: \"staging\"\n    description: \"Target environment (staging or production)\"\n\nshow-custom-vars:\n  variables:\n    JOB_SPECIFIC_VAR: \"only-in-this-job\"\n    APP_VERSION: \"3.0.0-override\"\n  script:\n    - echo \"APP_NAME    - $APP_NAME\"\n    - echo \"APP_VERSION - $APP_VERSION\"\n    - echo \"JOB_VAR     - $JOB_SPECIFIC_VAR\"\n    - echo \"DEPLOY_ENV  - $DEPLOY_ENV\"<\/code><\/pre>\n\n\n\n
    Output from our test pipeline:<\/p>\n\n\n\n
    === Global Variables ===\nAPP_NAME    - my-web-app\nDEPLOY_ENV  - staging\n\n=== Job-Level Override ===\nAPP_VERSION - 3.0.0-override  (was 2.1.0 globally, overridden to 3.0.0)\nJOB_VAR     - only-in-this-job<\/code><\/pre>\n\n\n\n
    The value:<\/code> and description:<\/code> syntax for DEPLOY_ENV<\/code> creates a prefilled variable when someone triggers the pipeline manually from the GitLab UI. The description appears as a label next to the input field.<\/p>\n\n\n\n
    Project Variables in the GitLab UI<\/h2>\n\n\n\n
    Go to Settings > CI\/CD > Variables<\/strong> in your project to add variables through the web interface. This is where you store credentials, API keys, and environment-specific configuration that should never appear in your repository.<\/p>\n\n\n\n
    \"GitLab<\/figure>\n\n\n\n
    Each UI variable has these properties:<\/p>\n\n\n\n
      \n
    • Type<\/strong>: Variable<\/code> (standard env var) or File<\/code> (value written to a temp file, variable holds the file path)<\/li>\n\n\n\n
    • Protected<\/strong>: only available on protected branches and tags<\/li>\n\n\n\n
    • Masked<\/strong>: value replaced with [MASKED]<\/code> in job logs. Requires 8+ characters, no spaces<\/li>\n\n\n\n
    • Masked and hidden<\/strong> (GitLab 17.6+): also hidden from the Settings UI itself<\/li>\n\n\n\n
    • Environment scope<\/strong> (Premium): restrict to specific environments like staging<\/code> or production\/*<\/code><\/li>\n<\/ul>\n\n\n\n
      In our demo, we created a masked API_SECRET_KEY<\/code> variable. The job log shows exactly how masking works:<\/p>\n\n\n\n
      === UI-Defined Variables ===\nDEPLOY_SERVER  - 192.168.1.100\nAPI_SECRET_KEY - [MASKED]  (should show [MASKED])<\/code><\/pre>\n\n\n\n
      \"GitLab<\/figure>\n\n\n\n
      The actual value (sk-prod-a8f3e2d1c4b5a697<\/code>) is injected into the job’s environment but never appears in the log output.<\/p>\n\n\n\n
      File-Type Variables<\/h2>\n\n\n\n
      File-type variables are commonly misunderstood. When you create a file-type variable, GitLab writes the value to a temporary file and sets the environment variable to the file path<\/strong>, not the contents. This is essential for SSH keys, TLS certificates, and kubeconfig files.<\/p>\n\n\n\n
      show-file-var:\n  script:\n    - echo \"Path: $SSH_PRIVATE_KEY\"\n    - head -3 \"$SSH_PRIVATE_KEY\"<\/code><\/pre>\n\n\n\n
      Output from our test:<\/p>\n\n\n\n
      === File-Type Variable ===\nSSH_PRIVATE_KEY variable contains a file path:\nPath - \/home\/gitlab-runner\/builds\/e_ZfGc5EI\/0\/root\/ci-variables-demo.tmp\/SSH_PRIVATE_KEY\n\nFile contents (first 3 lines):\n-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0\ndemo-key-content-for-article-purposes-only<\/code><\/pre>\n\n\n\n
      The runner creates the temp file before the job starts and deletes it after. To use it with SSH:<\/p>\n\n\n\n
      deploy:\n  script:\n    - chmod 600 \"$SSH_PRIVATE_KEY\"\n    - ssh -i \"$SSH_PRIVATE_KEY\" user@server \"echo connected\"<\/code><\/pre>\n\n\n\n
      Passing Variables Between Jobs with dotenv<\/h2>\n\n\n\n
      Jobs run in isolation. If a build job generates a version number or artifact path, the next job doesn’t automatically know about it. Dotenv artifacts solve this by letting one job write key-value pairs to a file that later jobs can read as environment variables.<\/p>\n\n\n\n
      build-app:\n  stage: build\n  script:\n    - BUILD_ID=\"build-$(date +%s)\"\n    - BUILD_ARTIFACT=\"$APP_NAME-$APP_VERSION.tar.gz\"\n    - COMMIT_SHORT=$(echo $CI_COMMIT_SHA | cut -c1-8)\n    - echo \"BUILD_ID=$BUILD_ID\" >> build.env\n    - echo \"BUILD_ARTIFACT=$BUILD_ARTIFACT\" >> build.env\n    - echo \"BUILD_COMMIT=$COMMIT_SHORT\" >> build.env\n  artifacts:\n    reports:\n      dotenv: build.env\n\ntest-with-build-vars:\n  stage: test\n  needs: [build-app]\n  script:\n    - echo \"BUILD_ID       - $BUILD_ID\"\n    - echo \"BUILD_ARTIFACT - $BUILD_ARTIFACT\"\n    - echo \"BUILD_COMMIT   - $BUILD_COMMIT\"<\/code><\/pre>\n\n\n\n
      The build job writes three variables to build.env<\/code> and declares it as a dotenv artifact. The test job receives them automatically:<\/p>\n\n\n\n
      === Variables received from build-app via dotenv ===\nBUILD_ID       - build-1774688488\nBUILD_ARTIFACT - my-web-app-2.1.0.tar.gz\nBUILD_COMMIT   - f46a0e64\n\nThese were NOT defined in this job.\nThey came from the build-app job's dotenv artifact.\n\n=== Global vars still available too ===\nAPP_NAME    - my-web-app\nAPP_VERSION - 2.1.0  (global value, not overridden)<\/code><\/pre>\n\n\n\n
      \"GitLab<\/figure>\n\n\n\n
      Dotenv files must follow strict formatting rules: UTF-8 encoding, no empty lines, no comments, no multiline values, max 5 KB. Variable names can only contain ASCII letters, digits, and underscores.<\/p>\n\n\n\n
      Control which dotenv artifacts a job inherits with dependencies:<\/code> or needs:<\/code>:<\/p>\n\n\n\n
      # Inherit dotenv from specific jobs only\ntest-job:\n  needs: [build-app]\n  script: echo \"$BUILD_ID\"\n\n# Block all dotenv inheritance\nindependent-job:\n  needs:\n    - job: build-app\n      artifacts: false\n  script: echo \"No dotenv vars here\"<\/code><\/pre>\n\n\n\n
      Variable Precedence<\/h2>\n\n\n\n
      When the same variable name is defined at multiple levels, GitLab uses a strict precedence order. This catches people off guard because UI variables beat YAML definitions. We tested this by defining DEPLOY_SERVER<\/code> in both the project UI (value: 192.168.1.100<\/code>) and the job-level YAML (value: job-level-server.local<\/code>).<\/p>\n\n\n\n
      === Variable Precedence Demo ===\nDEPLOY_SERVER is defined in THREE places:\n  1. Project UI variable  = 192.168.1.100\n  2. Job-level .gitlab-ci.yml = job-level-server.local\n\nActual value - 192.168.1.100\n\nThe UI project variable WINS over the job-level YAML variable.<\/code><\/pre>\n\n\n\n
      \"GitLab<\/figure>\n\n\n\n
      The full precedence order (highest wins):<\/p>\n\n\n\n
        \n
      1. Pipeline variables (manual trigger, API, schedule, downstream)<\/li>\n\n\n\n
      2. Project variables (Settings > CI\/CD > Variables)<\/li>\n\n\n\n
      3. Group variables (inherited from parent groups)<\/li>\n\n\n\n
      4. Instance variables (self-managed only, set by admins)<\/li>\n\n\n\n
      5. Dotenv report variables<\/li>\n\n\n\n
      6. Job-level .gitlab-ci.yml<\/code> variables<\/li>\n\n\n\n
      7. Global .gitlab-ci.yml<\/code> variables<\/li>\n\n\n\n
      8. Predefined variables<\/li>\n<\/ol>\n\n\n\n
        This means a project-level UI variable will always override the same key defined in your YAML. If your pipeline ignores a YAML variable and you can’t figure out why, check whether a UI variable with the same name exists.<\/p>\n\n\n\n
        Using Variables in rules:<\/h2>\n\n\n\n
        The rules:if<\/code> keyword evaluates variables to decide whether a job runs. This is how you create conditional pipelines:<\/p>\n\n\n\n
        deploy-staging:\n  rules:\n    - if: $DEPLOY_ENV == \"staging\"\n      when: always\n    - when: never\n  script:\n    - echo \"Deploying to staging...\"\n\ndeploy-production:\n  rules:\n    - if: $DEPLOY_ENV == \"production\"\n      when: manual\n    - when: never\n  script:\n    - echo \"Deploying to production...\"\n\nonly-on-tags:\n  rules:\n    - if: $CI_COMMIT_TAG\n  script:\n    - echo \"This runs only when a tag is pushed\"\n\nonly-merge-requests:\n  rules:\n    - if: $CI_PIPELINE_SOURCE == \"merge_request_event\"\n  script:\n    - echo \"This runs only in MR pipelines\"<\/code><\/pre>\n\n\n\n
        Two important gotchas with rules:if<\/code>:<\/p>\n\n\n\n