MeWrite Docs

GitLab CI: Pipeline failed

GitLab CIのパイプラインが失敗した場合の原因と解決方法

概要

GitLab CIのパイプラインが失敗する原因は様々ですが、設定ファイルの構文エラー、依存関係の問題、テストの失敗などが主な原因です。

エラーメッセージ

1
2
# .gitlab-ci.yml の構文エラー
yaml invalid
Job failed: exit code 1
ERROR: Job failed (system failure): prepare environment

原因と解決策

1. .gitlab-ci.yml の構文エラー

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# NG: インデントが間違っている
stages:
- build
- test

build_job:
stage: build  # stageの前にスペースがない

# OK
stages:
  - build
  - test

build_job:
  stage: build
  script:
    - echo "Building..."

2. スクリプトの失敗

1
2
3
4
5
6
# 失敗するコマンドを確認
test_job:
  script:
    - npm install
    - npm test  # テストが失敗
  allow_failure: false  # 失敗を許可しない(デフォルト)
1
2
3
4
5
# 失敗を許可する場合
test_job:
  script:
    - npm test
  allow_failure: true

3. Runnerがない

This job is stuck because you don't have any active runners that can run this job.
1
2
3
4
5
# 特定のタグを持つRunnerを指定
build_job:
  tags:
    - docker
    - linux

4. Docker イメージの問題

1
2
3
4
5
# イメージが見つからない
image: nonexistent/image:latest

# OK: 存在するイメージを使用
image: node:18-alpine

5. アーティファクトの問題

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# パスが間違っている
artifacts:
  paths:
    - dist/  # このディレクトリが存在しない

# expire_inを設定
artifacts:
  paths:
    - dist/
  expire_in: 1 week

6. 依存ジョブの失敗

1
2
3
4
5
# needs で指定したジョブが失敗
deploy:
  stage: deploy
  needs:
    - build  # buildが失敗するとdeployも失敗

7. 変数の未設定

1
2
3
4
5
deploy:
  script:
    - echo $DEPLOY_KEY  # 変数が未設定
  variables:
    DEPLOY_KEY: $CI_DEPLOY_KEY  # CI/CD設定で定義が必要

デバッグ方法

1
2
3
4
5
6
7
# デバッグ用のジョブ
debug:
  script:
    - env  # 環境変数一覧
    - pwd  # カレントディレクトリ
    - ls -la  # ファイル一覧
    - cat .gitlab-ci.yml
1
2
3
4
5
# ローカルでCI設定を検証
gitlab-ci-lint .gitlab-ci.yml

# GitLab UIで検証
# CI/CD > Editor > Validate

完全な例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
stages:
  - build
  - test
  - deploy

variables:
  NODE_VERSION: "18"

cache:
  paths:
    - node_modules/

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test
  coverage: '/Coverage: \d+\.\d+%/'

deploy:
  stage: deploy
  script:
    - echo "Deploying..."
  only:
    - main
  when: manual

関連エラー

関連エラー

CI/CD の他のエラー

最終更新: 2025-12-17