Skip to main content
Mapagam

Handling Errors and Debugging

1. Using allow_failure for Non-Critical Jobs

Property Description Default
allow_failure When set to true, the job will be marked as failed but the pipeline will continue to run false

Example: Using allow_failure in a job

test_job:
  script:
    - npm test
  allow_failure: true
Note: Setting allow_failure to true does not prevent the job from failing the pipeline if it is a required job in a stage.

2. Debugging with CI_DEBUG_TRACE

Variable Value Description
CI_DEBUG_TRACE true Enables debug tracing for all jobs in the pipeline

Example: Enabling Debug Trace

CI_DEBUG_TRACE=true
  script:
    - echo "Running job with debug trace"
Note: Setting CI_DEBUG_TRACE to true will output detailed logs for each command executed in the job, which can help identify where errors occur.
Warning: Using CI_DEBUG_TRACE in production pipelines may expose sensitive information. It is recommended to use it only in development or testing environments.

3. Viewing Job Logs

Log Type Description Access Method Notes
Job Logs Logs from individual jobs in a pipeline CI_JOB_ID or via UI Available in the job's page in GitLab UI
Pipeline Logs Aggregated logs from all jobs in a pipeline UI or API Useful for debugging overall workflow issues
Build Logs Logs from build stages (e.g., compilation, testing) UI or API Can be filtered by job name or stage

Example: Accessing Job Logs via GitLab UI

1. Navigate to your project in GitLab
2. Go to "CI/CD" > "Pipelines"
3. Click on the pipeline you want to debug
4. Click on the job name to view its logs
Note: Logs are retained for a configurable period (default is 30 days) unless otherwise specified in gitlab-ci.yml.
Warning: Large logs may be truncated in the UI. For full logs, use the API or download them via gitlab-ci tools.

Log Debugging Tips

  • Use echo or printf to output debug information in scripts
  • Filter logs by job or stage using GitLab's filtering options
  • Check for CI_JOB_NAME in logs to identify specific job issues

4. Using echo for Debug Output

Example: Basic echo usage in a GitLab CI job

job_name:
  script:
    - echo "Starting deployment process"
    - echo "Current branch: $CI_COMMIT_REF_NAME"
    - echo "Build ID: $CI_PIPELINE_ID"
Command Description Notes
echo Prints text or variables to the job log Useful for debugging and logging progress
echo $VAR Prints the value of a variable Variables are expanded in double quotes
echo "Message: $VAR" Prints formatted messages with variables Best practice for readable logs
Note: GitLab CI/CD logs are captured and displayed in the job's console. Use echo to output debug information, environment variables, or status messages.
Warning: Avoid printing sensitive data like passwords or tokens using echo. These will be visible in the job logs.

Best Practices for Debugging with echo

  • Use descriptive messages to track execution flow
  • Print environment variables to verify configuration
  • Avoid excessive logging that may clutter the output

5. Handling Script Failures

Property Description Values
script Defines the script to run in the job script:
fail_fast Stops the pipeline if a job fails true or false
allow_failure Allows a job to fail without stopping the pipeline true or false

Example: Handling Script Failures

job_name:
  script:
    - echo "Running job"
    - exit 1
  allow_failure: true
Note: When allow_failure: true, the job will be marked as failed but the pipeline continues.

6. Retrying Failed Jobs

Option Values Notes
retry 1 Number of times to retry a job
max_retries 2 Maximum retries allowed for a job

Example: Retry configuration in .gitlab-ci.yml

job_name:
  script:
    - echo "Running job"
  retry:
    max_retries: 3
    delay: 10
Note: Retries are not supported for jobs that have when: manual or when: on_failure conditions.
Warning: Excessive retries may lead to increased resource consumption and potential job timeouts.

7. Using when:on_failure Jobs

When a job fails in a GitLab CI/CD pipeline, you can define a follow-up job that runs only when the previous job fails using the when keyword with the value on_failure.

Property Value Description
when on_failure Specifies that the job should run only if the previous job fails.

Example: Defining a job that runs on failure

deploy:
  stage: deploy
  script:
    - echo "Deploying to production..."
  when: on_failure

send_notification:
  stage: notify
  script:
    - echo "Sending failure notification..."
  when: on_failure
Note: The when: on_failure job will only execute if the job it's associated with (in the same stage or previous stages) has failed. It does not run if a job in a later stage fails.

8. Debugging Variable Expansion

Variable Expansion Result Notes
CI_PIPELINE_ID 12345 Unique identifier for the pipeline
CI_JOB_ID 67890 Unique identifier for the job
CI_COMMIT_SHA abc123def456... Full commit SHA of the current job
CI_PROJECT_NAME my-project Name of the project

Example: Using Variables in Scripts

script:
  - echo "Pipeline ID: $CI_PIPELINE_ID"
  - echo "Job ID: $CI_JOB_ID"
  - echo "Commit SHA: $CI_COMMIT_SHA"
Note: Variable expansion happens during job execution, so any errors in variable usage will appear in the job logs.

9. Validating YAML Syntax

Example: Basic YAML Validation

stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Building..."
YAML Rule Description Common Error
Indentation Use 2 spaces for indentation; no tabs Tab characters cause parsing errors
Keys All keys must be unique within a scope Duplicate keys overwrite previous values
Quotes Use quotes for strings with special characters Unescaped special chars break parsing
Note: GitLab CI/CD uses strict YAML parsing. Even a single misplaced space can cause job failures.
Warning: Indentation errors are one of the most common causes of CI/CD pipeline failures.

Validation Tips

  • Use an online YAML validator before committing
  • Enable config.gitlab-ci.yml linting in your IDE
  • Validate with gitlab-ci-lint CLI tool

10. Using Job Artifacts for Debugging

Property Description Values
artifacts Defines the files or directories to be stored as artifacts paths, exclude, name, expire_in
artifacts.paths List of files/directories to include in the artifact Array of strings (e.g., ['logs/', 'build/'])
artifacts.exclude Patterns to exclude from the artifact Array of strings (e.g., ['*.tmp', 'cache/'])
artifacts.name Name of the artifact (used in UI) String (e.g., build-artifacts)
artifacts.expire_in Time after which the artifact is deleted String (e.g., 1 week, 30 days)

Example: Configuring Artifacts in a Job

build_job:
  script:
    - make build
  artifacts:
    paths:
      - build/
      - logs/
    name: "build-artifacts"
    expire_in: 1 week
Note: Artifacts are stored in GitLab and can be downloaded from the job page or accessed via API.
Warning: Large artifacts can increase storage costs and slow down job execution.

Key Points

  • Artifacts are useful for debugging and sharing build outputs between jobs.
  • Use expire_in to manage storage usage.
  • Artifacts can be accessed in downstream jobs or downloaded manually from the GitLab UI.

Was this article helpful?

Related Cheat Sheets