GitLab CI before_script Fails - Whole Job Aborts Before script

By Kaveh Alemi·Latchkey

GitLab concatenates before_script and script into one shell run. If any before_script line exits non-zero, the job fails there and your script never executes.

What this error means

The job fails during setup - installing a tool, configuring auth, or sourcing an env - and your main script output never appears. The failing command is in before_script (or a default:before_script).

Job log

$ apt-get install -y somecli
E: Unable to locate package somecli
Cleaning up project directory and file based variables
ERROR: Job failed: exit code 100

Diagnose it: which rule matched, and on which runner?

GitLab evaluates rules: top to bottom and the first match wins, including one that sets when: never. A job that does not run, or runs when you did not expect it to, is nearly always matching an earlier rule than the one you are reading.

.gitlab-ci.yml

# validate the definition against the project
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# what the job actually sees
script:
  - env | grep -E "^CI_(PIPELINE_SOURCE|COMMIT_REF_NAME|RUNNER)" | sort

Common causes

A setup command fails

Installing a package, logging into a registry, or generating config in before_script returns non-zero, and GitLab stops the job immediately.

Inherited default:before_script breaks

A global default:before_script (or one from an include/extends) runs before every job. A change there can break jobs that never declared a before_script themselves.

How to fix it

Fix or guard the setup step

Make setup commands robust and idempotent so they do not fail the whole job.

.gitlab-ci.yml

before_script:
  - apt-get update
  - apt-get install -y curl jq
  - command -v aws >/dev/null || pip install awscli

Isolate where it failed

Note that before_script runs in the same shell as script - the failing line is in the setup block.
Check whether a global default:before_script or an included template is the source.
Override before_script: [] in a job to opt out of an inherited setup that does not apply.

How to prevent it

Keep before_script minimal, idempotent, and non-interactive.
Pin tool versions so setup does not break on upstream changes.
Test changes to shared default:before_script against multiple jobs.

Frequently asked questions

What causes GitLab CI before_script fails?

There are 2 common causes: a setup command fails and inherited default:before_script breaks. Installing a package, logging into a registry, or generating config in before_script returns non-zero, and GitLab stops the job immediately.

How do I fix GitLab CI before_script fails?

There are 2 fixes depending on which cause you have: fix or guard the setup step and isolate where it failed. Work through them in order, since the first is the most common.

What does GitLab CI before_script fails actually mean?

The job fails during setup - installing a tool, configuring auth, or sourcing an env - and your main script output never appears.

How do I stop GitLab CI before_script fails happening again?

Keep before_script minimal, idempotent, and non-interactive. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation