- 技術 💻
Jenkinsとは・使い方|Jenkinsfileで最初のパイプラインを作る
結論
Jenkins は、ビルド・テスト・デプロイを自動で回す「自動化サーバー」で、手順は Jenkinsfile というファイルに書きます。Java 21 以上を入れて java -jar jenkins.war を動かし、ブラウザで初期設定を済ませ、Jenkinsfile を置いたリポジトリを Pipeline ジョブに登録すれば、最初のパイプラインが動きます。
この記事でわかること
- インストール(war・apt・Docker)から初期設定ウィザードまでの手順と、Java の要件
- checkout→build→test→archive を行う宣言型 Jenkinsfile の全文と、各ステップの出力・失敗時のログ原文
- 画面の見方・プラグイン・エージェント・GitHub Actions/GitLab CI との対応表・LTS 2.580.2 の位置づけ
Jenkins は「コードが変わったら、決めた手順を自動で実行し、結果を知らせる」ための道具です。手順を書く場所が Jenkinsfile、手順を実行する場所がエージェント、全体を取り仕切るのがコントローラーです。
flowchart TD
G[Git リポジトリ<br>Jenkinsfile 入り] -->|push・webhook| C[Jenkins コントローラー<br>画面・ジョブ管理]
C -->|割り当て| A[エージェント<br>checkout→build→test]
A -->|結果・成果物| C
C --> R[Console Output<br>Test Result・通知]
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| jenkins とは | Java で動くオープンソースの自動化サーバー。CI/CD の土台 | Jenkinsとは |
| jenkins インストール | Java 21 以上+ jenkins.war、または apt・Docker | Jenkinsのインストール |
| 初期設定・パスワードの場所 | コンソールか secrets/initialAdminPassword | 初期設定ウィザード |
| jenkinsfile 書き方 | pipeline { agent / stages / steps / post } | Jenkinsfileで最初のパイプライン |
| jenkins 使い方(画面) | New Item → Pipeline → Build Now → Console Output | パイプラインジョブの作り方と画面の見方 |
| 失敗したときに見る場所 | Console Output の末尾と junit の結果 | 失敗時のログの読み方 |
| GitHub Actions との違い | 自分でサーバーを持つか、SaaS に任せるか | GitHub Actions・GitLab CIとの対応表 |
| 最新の LTS | 2.580.2(2026年10月28日)。Java 21 か 25 | LTSの版・Javaの要件・Blue Oceanの扱い |
確認環境:この記事の作業環境では、外部からファイルを取得する経路が方針で止められており、jenkins.war・apt のリポジトリ・Docker イメージのいずれも取得できませんでした。そのため Jenkins 本体の起動・画面の操作・プラグインの導入・エージェントの接続は、Jenkins 公式ドキュメント(jenkins.io/doc の User Handbook・Pipeline Syntax・Pipeline Steps Reference・ダウンロードページ・LTS の変更履歴)で1つずつ確かめて書いています。Jenkinsfile の各 sh ステップが実行するコマンド(git log・python3 -m compileall・python3 -m zipapp・python3 -m pytest --junitxml)は、Ubuntu 24.04.4 LTS・Python 3.11・pytest 9.1.1・git 2.43.0 で、Jenkins の sh と同じ sh -xe で実行し、成功時の出力・失敗時の出力・junit ステップが読む JUnit XML の中身を載せています。GitHub Actions・GitLab CI との対応は、GitHub Docs と GitLab Docs の移行ガイドで確かめました。図は mermaid で描画を確かめています(確認日 2026年10月29日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Jenkinsとは・使い方|Jenkinsfileで最初のパイプラインを作る」
Jenkinsとは(できること・CI/CDでの役割)
この節では、Jenkins が何をする道具で、CI/CD のどこを担うのかが分かります。
Jenkins は、ソフトウェアのビルド・テスト・デプロイを自動化するためのオープンソースの自動化サーバーです。 Java で書かれており、Java が動く環境なら Linux・Windows・macOS・Docker・Kubernetes のどこでも動きます。公式サイトは「開発者がソフトウェアのビルド・テスト・デプロイを行えるようにするオープンソースの自動化サーバー」と説明しています。Hudson という名前で始まったプロジェクトが2011年に Jenkins と名前を変え、現在は Continuous Delivery Foundation のもとで開発が続いています。
CI(継続的インテグレーション)は「コードを変えるたびにビルドとテストを自動で行い、壊れたらすぐ知る」こと、CD(継続的デリバリー/デプロイ)は「テストを通ったものを自動で配る」ことです。Jenkins はその両方の「自動で行う」部分を受け持ちます。CI/CD そのものの考え方は、関連記事「CI/CDとは|GitHub Actionsで最初のパイプラインを作るまで」で扱っています。
1コードが変わったら動く
push や webhook、定期実行、ほかのジョブの完了をきっかけに、決めた手順を実行します。
2手順はファイルに書く
Jenkinsfile をリポジトリに置くと、手順そのものがレビューと履歴の対象になります。
3プラグインで広げる
Git・JUnit・Docker・Slack 通知など、機能はプラグインで足します。中核は小さく保たれています。
4自分のサーバーで動かす
社内ネットワークの中だけで完結でき、実行環境(OS・ツール・ネットワーク)を自分で決められます。
Jenkinsの仕組み(コントローラー・エージェント・ジョブ・Pipeline)
この節では、Jenkins を使うときに出てくる言葉の意味と、それぞれの関係が分かります。
| 言葉 | 意味 | 補足 |
|---|---|---|
| コントローラー | 画面を出し、ジョブを管理し、仕事をエージェントに割り当てる中心のプロセス | 以前は「マスター」と呼ばれていた |
| エージェント(ノード) | 実際にビルドやテストを実行する機械・コンテナ | 公式は「Pipeline を実行できる、Jenkins 環境の一部である機械」と定義 |
| built-in node | コントローラーのプロセスの中にあるノード | 公式はここでのビルド実行を勧めていない |
| エグゼキューター | ノードの中の「同時に実行できる仕事の枠」 | 公式は「1ノードに1つがいちばん安全」としている |
| ジョブ(アイテム) | Freestyle・Pipeline・Multibranch Pipeline などの「仕事の定義」 | 新しく作るなら Pipeline |
| Pipeline | CD の流れを Jenkinsfile に書いたもの。stage と step で構成 | 公式は「ユーザーが定義した CD パイプラインのモデル」と定義 |
| JENKINS_HOME | 設定・ジョブ・ビルド履歴・プラグインが置かれるフォルダー | apt では /var/lib/jenkins、Docker では /var/jenkins_home |
Pipeline の中の言葉は、公式の定義では次のとおりです。stage は「パイプライン全体を通して行う、概念として区別できるひとまとまりの作業」、step は「1つの作業」で、sh 'make' のようにシェルコマンドを実行するのが step です。Build・Test・Deploy という stage の中に、複数の step を並べます。
Freestyle ジョブ
画面のフォームで手順を組む
手順が JENKINS_HOME の XML に残り、レビューしにくい
以前からあるジョブで、今も動く
Pipeline ジョブ(Jenkinsfile)
手順をコードで書き、リポジトリに置く
再起動をまたいで続く・人の承認で止まれる・並列にできる
新しく作るときの基本
Jenkinsのインストール(war・apt・Docker)とJavaの要件
この節では、Jenkins を入れる3つの方法と、先に用意する Java の版が分かります。
どの方法でも、先に Java 21 以上が要ります。 公式の Java サポート方針(2026年10月29日時点)では、動かせる Java は 21 と 25 の2つで、Java 17 は LTS 2.541.3(2026年3月)が最後の対応版でした。Java 17 のまま最新の LTS に上げると起動しません。
war ファイルで動かす(いちばん小さい)
# Java を確かめる(21 か 25)
java -version
# ダウンロードした jenkins.war と同じフォルダーで
java -jar jenkins.war
# ポートを変えるとき(既定は 8080)
java -jar jenkins.war --httpPort=9090
起動したら http://localhost:8080 を開き、「Unlock Jenkins」の画面が出るのを待ちます。JENKINS_HOME は既定でホームフォルダーの .jenkins になり、環境変数 JENKINS_HOME で変えられます。
Debian・Ubuntu の apt で入れる(公式の手順)
sudo apt update
sudo apt install fontconfig openjdk-21-jre
java -version
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key
echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc]" \
https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
/etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install jenkins
公式は「Debian/Ubuntu では Jenkins より先に Java を入れることを強く勧める」としています。先に Jenkins を入れると、次のエラーで止まります。
jenkins: failed to find a valid Java installation
apt で入れると systemd のサービスとして動きます。状態は systemctl status jenkins、ログは journalctl -u jenkins.service、設定は systemctl cat jenkins で見ます。8080 が使われているときは systemctl edit jenkins で次の2行を足します。
[Service]
Environment="JENKINS_PORT=8081"
Docker で動かす
公式イメージ jenkins/jenkins には現在の LTS が入っています。公式ドキュメントは、タグを jenkins/jenkins:2.580.2-jdk21 のように版で固定し、--publish 8080:8080 --publish 50000:50000 で画面用の 8080 とエージェント接続用の 50000 を出す形を示しています。初期パスワードは docker exec <コンテナ名> cat /var/jenkins_home/secrets/initialAdminPassword で読めます。
| 方法 | 向いている場面 | JENKINS_HOME |
|---|---|---|
| war | 手元で試す・Java だけある環境 | ~/.jenkins(JENKINS_HOME で変更) |
| apt・rpm | サーバーに常駐させる。systemd で管理 | /var/lib/jenkins |
| Docker | ホストを汚さない。版を固定しやすい | /var/jenkins_home(volume に出す) |
| Windows(MSI)・macOS(brew) | 各 OS のサービスとして動かす | インストーラーの既定 |
Docker の基本操作は、関連記事「Dockerコマンド早見表|よく使う操作とつながらない時の対処」で扱っています。
初期設定ウィザード(Unlock Jenkins・プラグイン・管理者)
この節では、最初にブラウザで開いたときに出る3つの画面で、何をすればよいかが分かります。
初回は「ロック解除 → プラグイン → 管理者ユーザー」の順に進みます。 公式ドキュメントは、ウィザードを通ると多くのセキュリティ設定が既定で有効になり、匿名アクセスは許可されず、管理者ユーザーが1人いる状態になる、と説明しています。
Unlock Jenkins(ロック解除)
自動生成されたパスワードを「Administrator password」に貼って Continue を押す。パスワードは起動時のコンソールに「2組のアスタリスクの間」に出る。apt なら sudo cat /var/lib/jenkins/secrets/initialAdminPassword、Docker なら /var/jenkins_home/secrets/initialAdminPassword。
Customize Jenkins(プラグインを選ぶ)
「Install suggested plugins」を選ぶと、よくある使い方に基づく推奨セット(Git・Pipeline・JUnit など)が入る。「Select plugins to install」なら自分で選ぶ。迷ったら前者で、あとから足せる。
Create First Admin User(管理者を作る)
ユーザー名・パスワード・氏名・メールを入れて「Save and Finish」。「Jenkins is ready」で「Start using Jenkins」を押す。「Jenkins is almost ready!」と出たら「Restart」を押す。
Jenkins URL を確かめる
Manage Jenkins → System の「Jenkins Location」にある URL は、エージェントや外部ツールとの通信、通知に入るリンクに使われる。localhost のままだと、ほかの機械から届くリンクが壊れる。
Jenkinsfileで最初のパイプライン(checkout→build→test→archive)
この節では、宣言型 Jenkinsfile の全文と、各ステージが何をしているか、各 sh ステップが出す出力が分かります。
Jenkinsfile はリポジトリの直下に「Jenkinsfile」という名前(拡張子なし)で置き、宣言型(Declarative)で書くのが基本です。 次の例は、小さな Python ライブラリを「取得 → コンパイルして配布物を作る → pytest で試験 → 配布物を保存」する流れです。テストは --junitxml で JUnit 形式の XML を出し、post { always { junit } } で、失敗したときも結果を画面に出します。
pipeline {
agent any
options {
timestamps()
timeout(time: 10, unit: 'MINUTES')
buildDiscarder(logRotator(numToKeepStr: '20'))
}
stages {
stage('Checkout') {
steps {
checkout scm
sh 'git log -1 --oneline'
}
}
stage('Build') {
steps {
sh 'python3 -m compileall -q src'
sh 'mkdir -p dist && python3 -m zipapp src -o dist/calc.pyz -m "calc.cli:main"'
}
}
stage('Test') {
steps {
sh 'python3 -m pytest -q --junitxml=reports/junit.xml'
}
}
stage('Archive') {
steps {
archiveArtifacts artifacts: 'dist/*.pyz', fingerprint: true
}
}
}
post {
always {
junit 'reports/*.xml'
}
failure {
echo "失敗: ${env.JOB_NAME} #${env.BUILD_NUMBER} ${env.BUILD_URL}"
}
}
}
| 行 | していること | 公式の説明 |
|---|---|---|
agent any |
空いているどのエージェントでも実行する | agent は最上位で必須 |
options { timestamps() … } |
各行に時刻を付ける・10分で打ち切る・20回分だけ残す | timeout はエージェント確保後に数え始める |
checkout scm |
このジョブに設定したリポジトリの、きっかけになった版を取得 | Pipeline script from SCM のときに使える |
sh '…' |
シェルで実行。終了コードが 0 以外ならステップが失敗 | 既定で -xe 付きで実行される |
archiveArtifacts |
dist/*.pyz をビルドの成果物として保存 | 1つも無ければ既定でビルドが失敗 |
junit 'reports/*.xml' |
JUnit XML を読み、テスト結果の画面を作る | 失敗があるとビルドは UNSTABLE になる |
post { always / failure } |
結果に関係なく/失敗のときだけ、実行する | 順に always・changed・…・cleanup |
各 sh ステップが出す出力(手元で実行)
Jenkins の sh は、既定でシェルを -xe 付きで動かします(-x は実行するコマンドを表示、-e はエラーで止める)。同じ sh -xe で、Jenkinsfile の各コマンドを順に実行した出力です。
+ git log -1 --oneline
69ba966 src 配置に変更
+ python3 -m compileall -q src
+ mkdir -p dist
+ python3 -m zipapp src -o dist/calc.pyz -m calc.cli:main
+ ls -l dist/
-rw-r--r-- 1 root root 2001 Oct 29 17:50 calc.pyz
+ python3 dist/calc.pyz
calc ok: 5
+ python3 -m pytest -q --junitxml=reports/junit.xml
... [100%]
3 passed in 0.01s
junit ステップが読む reports/junit.xml の中身です。tests="3" failures="0" が、画面の「3 tests, 0 failures」になります。
<?xml version="1.0" encoding="utf-8"?>
<testsuites name="pytest tests">
<testsuite name="pytest" errors="0" failures="0" skipped="0" tests="3" time="0.013"
timestamp="2026-10-29T17:50:54.870084+09:00" hostname="vm">
<testcase classname="tests.test_calc" name="test_add" time="0.000" />
<testcase classname="tests.test_calc" name="test_div" time="0.000" />
<testcase classname="tests.test_calc" name="test_div_zero" time="0.000" />
</testsuite>
</testsuites>
Java のプロジェクトなら、Build は sh 'mvn -B -DskipTests package'、Test は sh 'mvn -B test'、junit は 'target/surefire-reports/*.xml'、archive は 'target/*.jar' に置き換えます。公式ドキュメントの例も archiveArtifacts artifacts: '**/target/*.jar', fingerprint: true と junit '**/target/*.xml' です。Maven の書き方は、関連記事「Mavenコマンド一覧|pom.xml書き方とよく使うオプション」で扱っています。
パイプラインジョブの作り方と画面の見方
この節では、Jenkinsfile を Jenkins に登録して実行するまでの画面の操作と、結果をどこで見るかが分かります。
Jenkinsfile をリポジトリから読ませるには、Pipeline ジョブを作り、Definition を「Pipeline script from SCM」にします。 公式ドキュメントの手順は次のとおりです。
- 1Dashboard → New Item名前を入れて「Pipeline」を選び OK。名前に空白を入れない(公式はスクリプトで不具合を招くと注意)
- 2Pipeline → Definition「Pipeline script」なら画面の Script 欄に直接書く。「Pipeline script from SCM」ならリポジトリから読む
- 3SCM・Repository URL・Credentials・BranchGit を選び、URL と認証情報、ブランチ(*/main など)を入れる
- 4Script Path既定は「Jenkinsfile」(リポジトリ直下)。別の場所なら ci/Jenkinsfile のように相対パスで
- 5Save → Build Now左の「Build History」に #1 が出る。番号を押して「Console Output」で全ログを見る
| 画面・場所 | 何が見えるか | いつ見るか |
|---|---|---|
| Dashboard | ジョブの一覧・直近の結果(青/緑・赤・黄)・天気のアイコン | 全体の状態を知りたい |
| ジョブの画面(Stage View) | ステージごとの所要時間と成否が、実行ごとに並ぶ | どのステージで止まったか |
| Console Output | sh の出力を含む全ログ。末尾に Finished: SUCCESS / FAILURE / UNSTABLE |
失敗の原因を読む |
| Test Result | junit が読んだテストの数・失敗・所要時間・失敗の本文 | どのテストが落ちたか |
| Build Artifacts | archiveArtifacts で保存した成果物のダウンロード | 配布物を取り出す |
| Replay | 完了した実行の Jenkinsfile を画面で直して、コミットせずに再実行 | Jenkinsfile の試行錯誤 |
| Pipeline Syntax(Snippet Generator) | JENKINS_URL/pipeline-syntax。ステップのコードをフォームから生成 |
引数の名前が分からない |
結果は SUCCESS・UNSTABLE・FAILURE・ABORTED の4つです。 テストの失敗を junit が読むと UNSTABLE(黄色)になり、sh が 0 以外で終わると FAILURE(赤)になります。見た目の色が違うので、「赤はコマンドが失敗、黄はテストが失敗」と覚えると読みやすくなります。
Replay は「Run / Replay」の権限(Job / Configure に含まれる)が要り、Job / Build だけの人には「Rebuild」と表示されます。構文エラーで始まらなかった実行は Replay できません(JENKINS-37589)ので、大きく書き直すときは手元で保存してからにします。宣言型の Jenkinsfile は、実行する前に Linter で確かめられます。
# 公式が勧める SSH 経由(CLI の SSH を有効にしているとき)
ssh -p $JENKINS_PORT $JENKINS_HOST declarative-linter < Jenkinsfile
# HTTP 経由
curl -X POST --user "$JENKINS_AUTH" -F "jenkinsfile=<Jenkinsfile" "$JENKINS_URL/pipeline-model-converter/validate"
正しいときは Jenkinsfile successfully validated.、誤りがあるときは行と列つきで理由が出ます。公式ドキュメントの例(agent の後ろに any が無い)では、次の出力になります。
Errors encountered validating Jenkinsfile:
WorkflowScript: 2: Not a valid section definition: "agent". Some extra configuration is required. @ line 2, column 3.
agent
^
WorkflowScript: 1: Missing required section "agent" @ line 1, column 1.
pipeline }
^
失敗時のログの読み方(Console Outputの原文)
この節では、テストが落ちたとき・コマンドが失敗したときに、Console Output のどこを見て何を読み取るかが分かります。
sh ステップは、スクリプトが 0 以外の終了コードで終わると、例外を投げてステップを失敗させます。 公式の Pipeline Steps Reference は「通常、0 以外のステータスコードで終了したスクリプトは、ステップを例外で失敗させる」と書いています。add にバグを入れて(足し算を引き算にして)Test ステージのコマンドを実行した出力です。
+ python3 -m pytest -q --junitxml=reports/junit.xml
F.. [100%]
=================================== FAILURES ===================================
___________________________________ test_add ___________________________________
def test_add():
> assert add(2, 3) == 5
E assert -1 == 5
E + where -1 = add(2, 3)
tests/test_calc.py:5: AssertionError
=========================== short test summary info ============================
FAILED tests/test_calc.py::test_add - assert -1 == 5
1 failed, 2 passed in 0.02s
exit=1
終了コードが 1 なので、Jenkins ではこの直後に sh が失敗し、Archive ステージは実行されず、post { always } の junit が reports/junit.xml を読みます。XML には失敗の本文がそのまま入っており、これが Test Result の画面に出ます。
<testsuite name="pytest" errors="0" failures="1" skipped="0" tests="3" time="0.020" …>
<testcase classname="tests.test_calc" name="test_add" time="0.001">
<failure message="assert -1 == 5 + where -1 = add(2, 3)">def test_add():
> assert add(2, 3) == 5
E assert -1 == 5
E + where -1 = add(2, 3)
tests/test_calc.py:5: AssertionError</failure>
</testcase>
- 1Console Output の末尾の1行を見るFinished: FAILURE なら sh が失敗、UNSTABLE なら junit がテストの失敗を読んだ
- 2「+ コマンド」の行を上へたどる-x で表示された行の直後が、そのコマンドの出力。最後の「+」が失敗したコマンド
- 3Stage View でどのステージかを見るCheckout で落ちれば認証や URL、Build なら依存やツール、Test ならコード
- 4テストの失敗は Test Result で読むjunit を post { always } に置いていれば、失敗しても結果が画面に残る
- 5Replay で直して再実行するJenkinsfile 側の問題なら、コミットせずに直して試せる
テストの失敗でパイプライン全体を赤にしたくないときは、sh に returnStatus: true を付けて終了コードを受け取るか、catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE') { … } で包みます。pytest の結果の読み方は、関連記事「pytest 使い方|導入からfixture・mock・カバレッジまで実行結果つき」で、Java のテストは関連記事「JUnitの使い方|単体テストの書き方と観点【JUnit 5・6】」で扱っています。
よくあるエラー・つまずき(原文と直し方)
この節では、Jenkins を入れて最初のパイプラインを動かすまでに出やすいエラーと、その直し方が一覧で分かります。
| 出るもの(原文) | 原因 | 直し方 |
|---|---|---|
jenkins: failed to find a valid Java installation |
Java が無い、または対応しない版 | Java 21 か 25 を先に入れる(公式が「先に Java」を強く推奨) |
| 8080 を開いても何も出ない・起動に失敗 | ポートが使われている | --httpPort=9090、apt なら JENKINS_PORT の上書き |
| 「Unlock Jenkins」のパスワードが分からない | コンソールを閉じた | JENKINS_HOME の secrets/initialAdminPassword を読む |
Missing required section "agent" |
宣言型で agent が無い・書き方の誤り | 最上位に agent any を書く。Linter で先に確かめる |
Not a valid section definition: "agent" |
agent の後ろの指定が無い |
agent any・agent { label 'linux' } の形にする |
script returned exit code 1(sh の失敗) |
コマンドが 0 以外で終わった | 直前の「+」の行の出力を読む。受け止めるなら returnStatus: true |
| Archive ステージでビルドが失敗 | パターンに合う成果物が 0 件 | パス・拡張子を直す。無くてもよいなら allowEmptyArchive: true |
| junit で「結果が無い」と失敗 | XML の場所が違う・テストが1つも動かなかった | パターンを直す。空を許すなら allowEmptyResults: true |
| Checkout で認証に失敗 | Credentials が未登録・権限不足 | Manage Jenkins → Credentials に登録し、ジョブの Credentials で選ぶ |
| ビルドが「pending」で動かない | 条件に合うエージェントが無い・エグゼキューターが 0 | label を見直す。Nodes でノードが online か、executor の数を確かめる |
テスト結果の扱い
post { always { junit 'reports/*.xml' } } に置く。失敗しても XML を読んで Test Result に出す公式の Jenkinsfile の例も post の always で junit を呼んでいる
秘密情報の渡し方
sh "deploy --token ${TOKEN}" のように Groovy の二重引用符で展開する。プロセス一覧に値が見えるenvironment { TOKEN = credentials('id') } と sh 'deploy --token $TOKEN'(単一引用符)で、シェル側に展開させる公式は「ログのマスクは事故を減らすだけ」で、信頼できないジョブに信頼した認証情報を使わないとしている
Jenkinsfileの文法早見(宣言型)とスクリプト型との違い
この節では、宣言型 Jenkinsfile で使う節とディレクティブの一覧と、スクリプト型をいつ使うかが分かります。
宣言型は pipeline { } の中に決まった節を書く形で、スクリプト型は node { } の中に Groovy を書く形です。 公式は、宣言型を「Pipeline のサブシステムの上に、より単純で意見を持った構文を載せたもの」と説明し、宣言型の中で Groovy が要るところだけ script { }(公式は「逃げ道」と呼ぶ)を使う形を勧めています。
| 節・ディレクティブ | 役割 | 公式の例 |
|---|---|---|
| agent(必須) | どこで動かすか。any・none・label・node・docker・dockerfile・kubernetes | agent { docker { image 'maven:3-eclipse-temurin-21' } } |
| stages / stage / steps(必須) | ステージの並びと、各ステージの手順 | stage('Build') { steps { sh 'make' } } |
| post | 終了後の処理。always・changed・fixed・regression・aborted・failure・success・unstable・unsuccessful・cleanup の順 | post { failure { mail to: '…' } } |
| environment | 環境変数。credentials() で認証情報を束ねられる |
CC = 'clang' |
| options | timeout・retry・timestamps・buildDiscarder・skipDefaultCheckout・disableConcurrentBuilds | timeout(time: 1, unit: 'HOURS') |
| parameters | 実行時に人が入れる値。params.名前 で読む |
string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: '…') |
| triggers | cron・pollSCM・upstream で自動実行 | cron('H */4 * * 1-5') |
| when | ステージを動かす条件。branch・changeset・environment・expression・not・allOf・anyOf | when { branch 'production' } |
| tools | maven・jdk・gradle を自動で入れて PATH に通す(agent none では無効) | tools { maven 'apache-maven-3.9' } |
| parallel / matrix | ステージを並列に。failFast true で1つ失敗したら全部止める |
parallel { stage('A') {…} stage('B') {…} } |
| input | 人の承認でステージを止める | input { message "本番に出しますか?" } |
cron の H は「その範囲のどこかに散らす」記号で、H */4 * * 1-5 は「平日、4時間ごとに、分はばらつかせて」です。多くのジョブが 0 分に集中しないようにするための Jenkins の書き方で、GitHub Actions の */15 とは同じ意味になりません。
まず宣言型
構造が決まっているので、Linter と Directive Generator が使え、読み手が迷わない。
新規はこちら
script { } は小さく
ループや条件分岐が要るところだけ。大きくなったら Shared Library に移す。
公式の勧め
スクリプト型は Groovy
node { stage('Build') { sh 'make' } }。try/catch/finally で失敗を扱う。
柔軟だが読みにくい
変数は env と params
env.BUILD_NUMBER・env.WORKSPACE・params.PERSON。一覧は Global Variable Reference に。
JENKINS_URL/pipeline-syntax/globals
// 公式ドキュメントの「Build / Test / Deploy」の形(抜粋)
pipeline {
agent any
options { skipStagesAfterUnstable() }
stages {
stage('Build') { steps { sh 'make' } }
stage('Test') {
steps {
sh 'make check'
junit 'reports/**/*.xml'
}
}
stage('Deploy') {
when { branch 'production' }
steps { sh 'make publish' }
}
}
}
プラグインの入れ方・更新のしかた
この節では、プラグインをどこから入れ、どう更新し、どこまで入れるかの考え方が分かります。
プラグインは Manage Jenkins → Plugins で入れます。 公式ドキュメントの手順は、「Available」タブで検索して選び「Install without restart」、更新は「Updates」タブで選んで「Download now and install after restart」です。依存するプラグインは Update Center から自動で一緒に入ります。更新の確認は既定で24時間ごとで、「Check now」で今すぐ確かめられます。
| プラグイン | 何ができるか | 最初に要るか |
|---|---|---|
| Pipeline(Pipeline: Declarative を含む) | Jenkinsfile を動かす本体 | 要る(推奨セットに含まれる) |
| Git | checkout scm・Git リポジトリの取得 |
要る(推奨セット) |
| JUnit | junit ステップとテスト結果の画面 |
要る(推奨セット) |
| Pipeline Graph View | ステージとステップの図・途中からの再開。Blue Ocean の代わり | あると見やすい |
| GitHub Branch Source/GitLab Branch Source | Multibranch Pipeline でブランチと PR を自動で見つける | GitHub・GitLab を使うなら |
| Docker Pipeline | agent { docker { … } } でコンテナの中で動かす |
コンテナで実行するなら |
| Credentials | パスワード・トークン・鍵の保管と credentials() |
要る(推奨セット) |
| Timestamper | timestamps() で各行に時刻 |
あると便利 |
- Update Center にあるのは各プラグインの最新版だけです。前の版を入れるには、「Advanced」タブの「Deploy Plugin」で
.hpiを上げるか、JENKINS_HOME/pluginsに.jpiの名前で置いて再起動します。 - CLI なら
java -jar jenkins-cli.jar -s JENKINS_URL install-plugin 名前 -deployで、依存も含めて入ります。 - プラグインは「要るものだけ」にします。数が増えるほど更新と脆弱性の対応が増え、互換性の問題も出やすくなります。Jenkins のセキュリティ勧告はプラグイン単位で出るので、入れたものを把握しておきます。
エージェント(ノード)を足して、built-in nodeで動かさない
この節では、ビルドを実行する機械を足す手順と、コントローラーでビルドを動かさない理由が分かります。
公式ドキュメントは「ビルドは built-in node で実行しない」と明記しています。 理由はセキュリティ・性能・拡張性で、built-in node のエグゼキューターを 0 にして、ビルドは別のエージェントに任せます。手元で試すだけなら built-in node でも動きますが、チームで使うなら最初から分けておきます。
ノードを作る
Manage Jenkins → Nodes → New Node。名前を付けて Permanent Agent を選ぶ。Remote root directory(エージェント側の作業フォルダー)、Labels(linux・docker など、Jenkinsfile の agent { label } で使う)、エグゼキューター数を入れる。
接続方法を選ぶ
「Launch agent by connecting it to the controller」(エージェント側から接続。インバウンド)か、SSH でコントローラーから起動する方法。公式の手順はインバウンドの形で説明している。
エージェント側でコマンドを動かす
保存後のノードの画面に出るコマンドをコピーし、agent.jar を落として実行する。ノードの画面に「Agent is connected」と出れば接続できている。
# ノードの画面に表示される形(値は自分の環境のもの)
java -jar agent.jar -url https://jenkins.example.com/ -secret <secret> -name linux-01 -workDir /home/jenkins/agent
エージェントは、固定の機械のほかに、Docker や Kubernetes で「ビルドのたびに作って捨てる」形にもできます。Jenkinsfile の agent { docker { image '…' } } は、そのステージをコンテナの中で動かす書き方で、ツールの版をイメージで固定できます。
GitHub Actions・GitLab CIとの対応表と、Jenkinsを選ぶ判断
この節では、同じことを GitHub Actions・GitLab CI でどう書くかと、どれを選ぶかの判断の軸が分かります。
書き方は違っても、「どこで(agent)・何を(steps)・終わったら何を(post)」という骨組みは同じです。 GitHub Docs と GitLab Docs の移行ガイドにある対応をまとめました。
| Jenkins(Jenkinsfile) | GitHub Actions(YAML) | GitLab CI(.gitlab-ci.yml) |
|---|---|---|
| Jenkinsfile(Groovy) | .github/workflows/*.yml | .gitlab-ci.yml |
| stages / stage | jobs(job ごとに独立) | stages と job の stage |
| steps / sh | jobs.<id>.steps / run | script |
| agent | runs-on・container | image・tags(runner) |
| environment | env | variables |
| triggers { cron(…) } | on.schedule | パイプラインスケジュール |
| when | jobs.<id>.if | rules |
| parallel / matrix の axes | strategy.matrix | parallel:matrix |
| archiveArtifacts | actions/upload-artifact | artifacts:paths |
| junit | (アクションで対応) | artifacts:reports:junit |
| post | 対応なし(if: always() のステップで代用) | after_script・.post ステージ |
| プラグイン(Timestamper・Build Timeout など) | マーケットプレイスのアクション | 組み込み(timeout キーワード、ログの時刻) |
GitHub Actions の書き方は、関連記事「GitHub Actionsのキャッシュとmatrix|コピペ用YAMLとキー設計」で扱っています。
判断表
| 状況 | 向いているもの | 理由 |
|---|---|---|
| コードが GitHub にあり、サーバーを持ちたくない | GitHub Actions | SaaS で保守が要らない。リポジトリと一体 |
| コードが GitLab にある | GitLab CI | 同上。テスト結果・カバレッジ・スキャンが組み込み |
| 社内ネットワークの外に出せない・実行環境を細かく決めたい | Jenkins | 自分のサーバーで完結。エージェントの OS・ツールを自由に選べる |
| すでに Jenkins のジョブが多くある | Jenkins(Pipeline 化を進める) | 移行コストより、Freestyle を Jenkinsfile に移す方が早い |
| 人の承認で止める・長い配布の流れ | Jenkins か GitLab CI | Jenkins の input、GitLab の manual ジョブ |
| Windows・macOS・特殊なハードで実行したい | Jenkins(自前のエージェント) | 自前のエージェントに何でも載せられる |
| 運用する人がいない | SaaS(GitHub Actions・GitLab CI) | Jenkins はサーバー・プラグイン・バックアップの保守が自分の仕事になる |
LTSの版・Javaの要件・Blue Oceanの扱い
この節では、どの版を入れればよいか、Java は何を選ぶか、以前よく使われた画面の今の扱いが分かります。
入れるのは LTS(Long-Term Support)です。 2026年10月29日時点の最新 LTS は 2.580.2(2026年10月28日)、週次版は 2.588 です。LTS は12週ごとに新しい系列が出て、その間は修正版(.1・.2・.3)が出ます。直前の LTS は 2.580.1(2026年9月30日)、その前は 2.568.3(2026年9月2日)でした。週次版は新しい機能を早く試すための版で、常用には LTS を選びます。
| Java | 対応する Jenkins | 2026年10月29日時点 |
|---|---|---|
| Java 25 | LTS 2.541.1(2026年1月)以降、週次 2.534 以降 | 対応。サポート予定は2029年9月まで |
| Java 21 | LTS 2.479.1(2024年10月)以降、週次 2.463 以降 | 対応。サポート予定は2027年9月まで |
| Java 17 | LTS 2.541.3(2026年3月)・週次 2.544(2025年12月)が最後 | 対応外。最新の LTS は動かない |
- Blue Ocean は2026年7月から非推奨です。 公式ドキュメントは「これ以上のセキュリティ修正や機能更新は行われない」とし、代わりに Pipeline Graph View プラグイン(ステージの図・ステップごとの進み方・途中からの再開)を勧めています。以前の記事で Blue Ocean の画面が前提になっているときは、読み替えます。
- Jenkins 2.539 以降では Content Security Policy の設定ができます。CSRF の保護は既定で有効です。
- 更新は「JENKINS_HOME をバックアップ → 本体を上げる → プラグインを上げる → ジョブを1つ動かして確かめる」の順にします。本体とプラグインには互換性の範囲があるので、本体を大きく飛ばすときはプラグインの対応版を先に見ます。
セキュリティの基本
- ウィザードを飛ばさない。公式は「初回起動でウィザードを無効にすると、既定で安全に設定されないことがある」としています。
- ビルドを built-in node で動かさない(エグゼキューターを 0 に)。
- 認証情報は Credentials に入れ、Jenkinsfile には書かない。秘密はシェルの単一引用符で展開する。
- Jenkins URL を正しい値にし、画面は HTTPS(手前のリバースプロキシでも可)で出す。
- プラグインを減らし、セキュリティ勧告に合わせて更新する。
よくある質問
Q. Jenkins とは何ですか? A. ビルド・テスト・デプロイを自動化するためのオープンソースの自動化サーバーです。Java で動き、手順は Jenkinsfile に書きます。CI/CD の「自動で実行する」部分を受け持ちます。
Q. Jenkins は無料ですか? A. 本体とプラグインは無料で使えます。費用は、動かすサーバーと、更新・バックアップ・プラグインの保守にかかる手間です。SaaS の CI と比べるときは、この保守の手間を入れて考えます。
Q. Java は何を入れればよいですか? A. 2026年10月29日時点では Java 21 か 25 です。Java 17 は LTS 2.541.3 が最後の対応版で、最新の LTS 2.580.2 は動きません。
Q. 初期パスワードはどこにありますか?
A. 起動時のコンソールの、2組のアスタリスクの間です。apt なら /var/lib/jenkins/secrets/initialAdminPassword、Docker なら /var/jenkins_home/secrets/initialAdminPassword、war なら JENKINS_HOME(既定 ~/.jenkins)の secrets/initialAdminPassword です。
Q. Jenkinsfile はどこに置きますか? A. リポジトリの直下に「Jenkinsfile」という名前で置くのが既定です。別の場所に置くなら、ジョブの Script Path に相対パスを書きます。
Q. 宣言型とスクリプト型のどちらで書けばよいですか?
A. 宣言型です。構造が決まっていて Linter で確かめられ、読み手が迷いません。Groovy の制御が要るところだけ script { } を使い、大きくなったら Shared Library に移します。
Q. テストが失敗したのに黄色(UNSTABLE)で、赤になりません。
A. junit ステップは、テストの失敗を既定で UNSTABLE にします。赤にしたいなら、テストコマンドの終了コードで sh を失敗させる(pytest・Maven は失敗時に 0 以外を返す)か、skipMarkingBuildUnstable と組み合わせて自分で error を呼びます。
Q. 成果物(jar や zip)はどこで取れますか?
A. archiveArtifacts で保存したものは、そのビルドの画面の「Build Artifacts」からダウンロードできます。公式は、これは簡単な保管と報告のためのもので、成果物リポジトリ(Nexus・Artifactory など)の代わりではない、としています。
Q. push したら自動で動かすには?
A. GitHub・GitLab からの webhook を Jenkins に届ける設定(各 Branch Source プラグイン)が基本です。webhook が届かないネットワークなら、triggers { pollSCM('H/5 * * * *') } で5分ごとに変更を見に行きます。
Q. ブランチごとに自動でジョブを作れますか? A. Multibranch Pipeline を使います。Jenkinsfile のあるブランチを自動で見つけてジョブを作り、PR も検証できます。既定ではブランチの増減を自動で再走査しないので、定期的な再走査を設定に入れます。
Q. Blue Ocean はまだ使えますか? A. 2026年7月から非推奨で、セキュリティ修正も機能更新も行われません。Pipeline Graph View プラグインに置き換えます。
Q. GitHub Actions があるのに Jenkins を使う理由は? A. コードや実行環境を社内から出せない、実行する機械(OS・ハード)を自分で決めたい、すでに Jenkins の資産が多い、といった場合です。サーバーを持ちたくないなら SaaS の CI の方が手間が少なくなります。
まとめ
- Jenkins は、ビルド・テスト・デプロイを自動化するオープンソースの自動化サーバー。Java 21 か 25 を入れ、war・apt・Docker のどれかで動かす。
- 初回は「Unlock Jenkins → Install suggested plugins → Create First Admin User」の3画面。パスワードは secrets/initialAdminPassword。
- 手順は宣言型 Jenkinsfile に書く。
agent・stages・stepsが必須で、junitはpost { always }に置く。shは終了コード 0 以外で失敗する。 - 失敗したら Console Output の末尾(Finished: …)と最後の「+ コマンド」、Stage View、Test Result を見る。Jenkinsfile の誤りは Linter と Replay で直す。
- ビルドは built-in node で動かさず、エージェントに任せる。最新 LTS は 2.580.2(2026年10月28日)で、Blue Ocean は非推奨、代わりは Pipeline Graph View。
参考・出典
確認日はいずれも 2026年10月29日です。
- Jenkins「Download and deploy」(LTS 2.580.2・週次 2.588):https://www.jenkins.io/download/
- Jenkins「LTS Changelog」(2.580.2 は 2026年10月28日):https://www.jenkins.io/changelog-stable/
- Jenkins「Java Support Policy」:https://www.jenkins.io/doc/book/platform-information/support-policy-java/
- Jenkins「Installing Jenkins – WAR file」:https://www.jenkins.io/doc/book/installing/war-file/
- Jenkins「Installing Jenkins – Linux」:https://www.jenkins.io/doc/book/installing/linux/
- Jenkins「Installing Jenkins – Docker」(Post-installation setup wizard):https://www.jenkins.io/doc/book/installing/docker/
- Jenkins「Pipeline」(概要・用語の定義):https://www.jenkins.io/doc/book/pipeline/
- Jenkins「Getting started with Pipeline」:https://www.jenkins.io/doc/book/pipeline/getting-started/
- Jenkins「Using a Jenkinsfile」:https://www.jenkins.io/doc/book/pipeline/jenkinsfile/
- Jenkins「Pipeline Syntax」:https://www.jenkins.io/doc/book/pipeline/syntax/
- Jenkins「Pipeline Development Tools」(Linter・Replay):https://www.jenkins.io/doc/book/pipeline/development/
- Jenkins「Branches and Pull Requests」(Multibranch):https://www.jenkins.io/doc/book/pipeline/multibranch/
- Jenkins「Pipeline Steps Reference – Pipeline: Nodes and Processes」(sh):https://www.jenkins.io/doc/pipeline/steps/workflow-durable-task-step/
- Jenkins「Pipeline Steps Reference – Pipeline: Basic Steps」:https://www.jenkins.io/doc/pipeline/steps/workflow-basic-steps/
- Jenkins「Pipeline Steps Reference – JUnit」:https://www.jenkins.io/doc/pipeline/steps/junit/
- Jenkins「Pipeline Steps Reference – Jenkins Core」(archiveArtifacts):https://www.jenkins.io/doc/pipeline/steps/core/
- Jenkins「Managing Plugins」:https://www.jenkins.io/doc/book/managing/plugins/
- Jenkins「Managing Nodes」:https://www.jenkins.io/doc/book/managing/nodes/
- Jenkins「Securing Jenkins」:https://www.jenkins.io/doc/book/security/
- Jenkins「Blue Ocean」(非推奨の案内):https://www.jenkins.io/doc/book/blueocean/
- GitHub Docs「Migrating from Jenkins to GitHub Actions」:https://docs.github.com/en/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions
- GitLab Docs「Migrating from Jenkins」:https://docs.gitlab.com/ci/migration/jenkins/
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「Jenkinsとは・使い方|Jenkinsfileで最初のパイプラインを作る」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。