Troubleshooting jobs

When working with jobs, you might encounter the following issues.

Jobs or pipelines run unexpectedly when using changes:

You might have jobs or pipelines that run unexpectedly when using rules: changes or only: changes without merge request pipelines.

Pipelines on branches or tags that don’t have an explicit association with a merge request use a previous SHA to calculate the diff. This calculation is equivalent to git diff HEAD~ and can cause unexpected behavior, including:

  • The changes rule always evaluates to true when pushing a new branch or a new tag to GitLab.
  • When pushing a new commit, the changed files are calculated by using the previous commit as the base SHA.

Additionally, rules with changes always evaluate as true in scheduled pipelines. All files are considered to have changed when a scheduled pipeline runs, so jobs might always be added to scheduled pipelines that use changes.

File paths in CI/CD variables

Be careful when using file paths in CI/CD variables. A trailing slash can appear correct in the variable definition, but can become invalid when expanded in script:, changes:, or other keywords. For example: 

docker_build:
  variables:
    DOCKERFILES_DIR: 'path/to/files/'  # This variable should not have a trailing '/' character
  script: echo "A docker job"
  rules:
    - changes:
        - $DOCKERFILES_DIR/*

When the DOCKERFILES_DIR variable is expanded in the changes: section, the full path becomes path/to/files//*. The double slashes might cause unexpected behavior depending on factors like the keyword used, or the shell and OS of the runner.

You are not allowed to download code from this project. error message

You might see pipelines fail when a GitLab administrator runs a protected manual job in a private project.

CI/CD jobs usually clone the project when the job starts, and this uses the permissions of the user that runs the job. All users, including administrators, must be direct members of a private project to clone the source of that project. An issue exists to change this behavior.

To run protected manual jobs:

  • Add the administrator as a direct member of the private project (any role)
  • Impersonate a user who is a direct member of the project.

A CI/CD job does not use newer configuration when run again

The configuration for a pipeline is only fetched when the pipeline is created. When you rerun a job, uses the same configuration each time. If you update configuration files, including separate files added with include, you must start a new pipeline to use the new configuration.

Job may allow multiple pipelines to run for a single action warning

When you use rules with a when clause without an if clause, multiple pipelines may run. Usually this occurs when you push a commit to a branch that has an open merge request associated with it.

To prevent duplicate pipelines, use workflow: rules or rewrite your rules to control which pipelines can run.

This GitLab CI configuration is invalid for variable expressions

You might receive one of several This GitLab CI configuration is invalid errors when working with CI/CD variable expressions. These syntax errors can be caused by incorrect usage of quote characters.

In variable expressions, strings should be quoted, while variables should not be quoted. For example: 

variables:
  ENVIRONMENT: production

job:
  script: echo
  rules:
    - if: $ENVIRONMENT == "production"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

In this example, both if: clauses are valid because the production string is quoted, and the CI/CD variables are unquoted.

On the other hand, these if: clauses are all invalid: 

variables:
  ENVIRONMENT: production

job:
  script: echo
  rules:       # These rules all cause YAML syntax errors:
    - if: ${ENVIRONMENT} == "production"
    - if: "$ENVIRONMENT" == "production"
    - if: $ENVIRONMENT == production
    - if: "production" == "production"

In this example:

  • if: ${ENVIRONMENT} == "production" is invalid, because ${ENVIRONMENT} is not valid formatting for CI/CD variables in if:.
  • if: "$ENVIRONMENT" == "production" is invalid, because the variable is quoted.
  • if: $ENVIRONMENT == production is invalid, because the string is not quoted.
  • if: "production" == "production" is invalid, because there is no CI/CD variable to compare.