Jenkins¶
セットアップ¶
インストール¶
2つのリリース体系¶
Jenkinsは、わりと毎週リリースされる"Release"と、3ヶ月毎にリリースされる"Long-Term Support Release(LTS)"の2つが用意されています。
Weekly | 新機能とバグ修正が混在している最新版 |
LTS | ベースラインとしたReleaseに対して重要なバグ修正のみを施した版 |
CentOS 8へのJenkinsインストール¶
OSのパッケージ(RPM)としてインストールする次の2つの方法があります。
- Jenkins公式サイト から[Download]を辿り、LTSまたはWeeklyから[Red Hat/Fedora/CentOS]を辿り、所望のバージョンのRPMファイルをダウンロードしてインストール
- Jenkins Redhat Packages を開き、記載の手順でyumリポジトリを設定、GPGキーを取得後、インストール
インストールするとサービスに追加されます。デフォルトは8080ポートです。jenkinsの設定ファイルが/etc/sysconfig/jenkinsにあるのでポート番号を変える等はこれを編集します。
インストール後、サービス起動(systemctl start jenkins
)で実行します。
初回起動後には幾つか設定を行います。
- 最初にWebブラウザでアクセスすると、Unlock Jenkins画面が表示され、画面に表示されるファイルをJenkins起動サーバーに入って開き、内容をコピーしてWebブラウザ画面に入力します。
- インストールするプラグインを選びます。[Install suggested plugins]を選べはお仕着せのプラグインがインストールされます。
- Jenkinsの管理者アカウントを作成します。
プロキシ設定¶
[Jenkinsの管理] > [プラグインの管理] > [高度な設定]タブを選択し、HTTP Proxyの設定 にプロキシサーバ、ポート番号、必要ならユーザ名、パスワードを設定します。
Jenkinsの制御¶
起動・終了¶
JenkinsをWeb経由で再起動させる¶
http://jenkins.example.com:8080/safeRestart
のようにjenkinsのサーバー名にsafeRestartをつければ再起動します。
ただし、コマンドラインからjava -jarで起動した場合は再起動できません。
ビルド環境を構築¶
Jenkins自身は特定のプログラミング言語のコンパイラやビルド手段(makeやantなど)を持っていません。ビルド手段を呼び出す設定をしておく必要があります。
Javaのビルド環境を設定¶
JDKを設定¶
ビルドに使用するJDKをJenkinsを動かすマシンにインストールします。
JenkinsにはJDK自動インストール機能がありますが、壁が高かったので手動でインストールして設定します。
次に、[Jenkinsの管理] > [システムの設定]を開き、JDK項の[JDK追加]ボタンを押します。
名前は、"jdk7u51"とか、"Oracle Java SE Development Kit 8"とかお好みで。
自動インストールのチェックを外し、するとJAVA_HOMEの記入欄が表示されるので、JDKがインストールされたディレクトリを指定します。
Antを設定¶
ビルドに使用するAntをJenkinsを動かすマシンにインストールします。
次に、[Jenkinsの管理] > [システムの設定]を開き、Ant項の[Ant追加]ボタンを押します。
名前は、"ant 1.9.3"とか。
自動インストールのチェックを外すとANT_HOMEの記入欄が表示されるので、Antがインストールされたディレクトリを指定します。
NetBeans AntでビルドするJavaプロジェクト¶
プロジェクトを作成¶
NetBeans IDEでAntを使用したJavaアプリケーション/ライブラリのプロジェクトをJenkinsでビルドするためのプロジェクトを作成します。
[新規ジョブ作成]でジョブ名を記載し、[フリースタイル・プロジェクトのビルド]を選択します。なお、ジョブ名には日本語を使えますが、jenkinsの作業ディレクトリのパス名に使われるので、頻繁にjenkinsのビルド作業ディレクトリにコマンドライン環境でアクセスする場合面倒なので英語名にした方がよいかもしれません。
一部のツール(JaCoCo、Coberturaなど)は絶対パスにASCII文字以外が含まれると正しく動かないのでジョブ名はASCII文字に限定すべきです。
ソースコードの取得先を設定¶
ビルドするソースファイル一式をどこから取得するかを設定します。
作成したプロジェクトを選択し、[設定]からソースコード管理システム項目で使用するバージョン管理システムを選択します。
Gitを選択した場合、リポジトリURLを記入します。
過去のビルドの保存度合いを設定¶
Jenkinsは実行したビルドの過程、結果を保持するので、繰り返しビルドを実施するとディスク領域を圧迫します。
作成したプロジェクトを選択し、[設定]から、[古いビルドの破棄]にチェックを付け、ビルドの保存最大数を指定します(過去10回分のビルドを取っておくなら10を指定)。
使用するJDKとAntの選択¶
作成したプロジェクトを選択し、[設定]から、ビルド項の[ビルド手順の追加]ドロップダウンリストをクリックし、[Antの呼び出し]を選択します。
使用するAnt欄に、デフォルトから先ほど作成したAntの名前をドロップダウンリストから選択します。
ターゲット欄に、Antのビルド設定(build.xml)に定義したターゲット名の中から実行したいものを指定します。NetBeansで作成したプロジェクトのAntビルド設定ファイルでは、ビルドだけならjar、ユニットテストを実行するならtest、Javadoc APIリファレンスドキュメントを生成するならjavadocをターゲットに指定します。defaultターゲットを指定すると、jar、test、javadocをすべて実行します。
[高度な設定]ボタンを押し、ビルドファイル欄が現れるのでソースコード一式を取得するリポジトリの中にあるビルド設定ファイル(build.xml)のパスを記入します。パスはリポジトリをクローン(チェックアウト)したときのトップディレクトリからの相対パスとします。
もし、複数のNetBeansプロジェクトをビルドするときは、ビルド項の[ビルド手順の追加]ドロップダウンリストを再度クリックし、[Antの呼び出し]を選択し、上述と同様に設定を追加します。
数個のNetBeansプロジェクトであればこれで追加していけばいいですが、あまりに多数のNetBeansプロジェクトをビルドする場合は、上位ディレクトリにbuild.xmlを作成し、それを指定した方が楽かと思います。
JUnitのインストールとAntプロパティにJUnitライブラリを指定¶
NetBeansでJUnitを使ったテストコードを記述している場合、Jenkinsでテスト実行することができます。ただし、JUnitのライブラリをJenkinsで設定しておかないとJUnitのライブラリが見つからないためテストコードのコンパイルが失敗します。
CentOS 6の標準搭載JUnitはバージョンが4.5でいささか古い(ルール機能、カテゴリ機能などに未対応)ので、別途インストールします。
JUnitサイト から[Download and Install guide]のリンクを辿って最新版のjuitのjarを入手します。
Linuxでは、Javaのライブラリ(JAR)を/usr/share/java/の下に置くのが主流みたいなので、ダウンロードしたjunit-4.11.jarを/usr/share/java/に置きます。JARファイルは、バージョン番号付きファイル名の実体と、バージョン番号のないシンボリックリンクファイルを置くのが流儀なのでそれに合わせて置きます。
/usr/share/java +-- junit-4.11.jar +-- junit.jar -> junit-4.11.jar
Jenkinsのビルドプロジェクトの[設定]を開き、ビルド項でAntの呼び出しの[高度な設定]ボタンを押し、プロパティに次を記載します。
libs.junit_4.classpath=/usr/share/java/junit.jar
NetBeansでは、ユーザー(開発マシン)個別に異なる可能性のあるライブラリパス設定を、Windowsマシンであれば
C:\Users\<ユーザー名>\AppData\Roaming\NetBeans\8.0\build.propertiesに定義しています。JUnit4に関する設定(例)は次のようになります。
libs.junit_4.classpath=C:\\Program Files\\NetBeans 8.0\\platform\\modules\\ext\junit-4.10.jar
なお、Linuxでは、~/.netbeans/8.0/build.propertiesになるようです。 Jenkinsでは、このファイルが存在しないので、Antのプロパティとして定義しました。
(ひょっとすると、/var/lib/jenkins/.netbeans/8.0/build.propertiesを作成すれば反映されるかもしれません)
参考URL
これで、NetBeansで作成したAntプロジェクトをJenkinsでビルドしたときにテストコードがコンパイルできるようになります。
別法)ANT_HOME/libの下にJUnitのJARファイルを配置¶
Antは、環境変数ANT_HOME/libに格納されているJARファイルをクラスパスに含めます。そこで、JUnitをここに置くことで、JenkinsやAntでのJUnitクラスパス設定が不要になります。
ユニットテスト結果の集計を設定¶
Jenkinsプロジェクトの[設定]で、ビルド後の処理項で[ビルド後の処理の追加]ドロップダウンリストから[JUnitテスト結果の集計]を選択します。
テスト結果XML欄には、複数のNetBeansプロジェクトをビルドしたときに対応できるよう次のように記載します。
**/build/test/results/*.xml
NetBeansプロジェクトをAntでビルドするとJUnitテスト実行結果を各プロジェクトのbuild/test/resultsディレクトリ下にXMLファイルとして生成します。
ビルドは成功して、続くテストに失敗すると、本来はJenkinsプロジェクトのビルドステータスは黄色(ビルド自体は成功したが、テストに失敗している)になるはずですが、なぜか赤色になってしまいます。
NetBeansが生成したAntのビルド設定に原因があり、回避方法を紹介しているブログがあります。
http://ogawa.s18.xrea.com/tdiary/20120312p02.html
ここの記述を倣って、Jenkinsプロジェクトの設定でビルド項のAntの呼び出しのプロパティに次を追記します。
ignore.failing.tests=true
設定メモ¶
- 設定後最初のビルドを実行してもテスト結果グラフが表示されない
- 設定後、2回ビルドを実行するとグラフが表示されます。
静的解析ツールの実行¶
PMD(CPD)¶
JenkinsでPMDを実行し、その解析結果を集計する設定を行います。
ソースコードと同じリポジトリ(NetBeansの各プロジェクトの下)にPMDを入れて、NetBeansの生成するAntプロジェクトにPMDの実行を追記する方法もありますが、多数のNetBeansプロジェクトからなるソフトウェア開発では手間が馬鹿にならないので、ここではJenkinsマシンにPMDをインストールし、静的解析ツールを実行する専用のAntビルドファイルを作成します。
ついでにCPD(重複コード解析)の解析設定も行います。
- PMDのインストール
- PMDプラグインのインストール
- PMDを実行するAntビルドファイル作成
- Jenkinsの設定
PMDのインストール¶
PMDのサイトより最新版(あるいは使用するバージョン)をダウンロードします。
http://pmd.sourceforge.net/
ディレクトリを決めてダウンロードしたファイルを展開します。
- Windowsなら、
C:\Program Files\Java\pmd-bin-5.1.0
など - Linuxなら、
/usr/share/java/pmd-bin-5.1.0
など
AntのlibディレクトリにPMDのjarファイルを置く方法もあります。antでPMDを実行するときにクラスパスの設定が省略できるというメリットがあります。
PMDプラグインのインストール¶
Jenkinsのプラグイン管理から、次のプラグインをインストールします。
- PMD Plug-in
- Static Analysis Utilities
- Duplicate Code Scanner Plug-in
これは、PMDに含まれるコピペ検出器(CPD)を使う場合にインストールします。
PMDを実行するAntビルドファイルの作成¶
静的解析対象のソースファイルがあるリポジトリに、AntビルドファイルおよびPMDルール検証定義ファイルを置きます。ここでは次のように置くことにします。
<リポジトリ基点> +-- staticanalyze.xml PMDを実行するAntビルドファイル +-- rules | +-- custom.xml PMDの解析対象ルール定義 +-- report | +-- pmd | | +-- pmd.xml PMDの解析実行結果が格納されるファイル | +-- cpd | +-- cpd.xml PMDのCPD(コピペ検出器)の解析実行結果が格納されるファイル +-- app | + ProjectAlfa NetBeansのプロジェクト | | +-- src この下にPMD解析対象となる製品コードが格納される | | +-- test この下にPMD解析対象ではないテストコードが格納される | + ProjectBeta : :
staticanalyze.xml は次のようになります。
- 注記1 mavenのディレクトリポリシーのようにsrcディレクトリ下に製品コードとテストコードを置く場合、解析対象ファイルの定義を変更する必要があります。
Jenkinsの設定¶
- [ビルド手順の追加] > [Antの呼び出し]
ターゲットに"pmd cpd"
高度な設定のビルドファイルに"staticanalyze.xml"
プロパティに"libs.pmd.dir=C:\\Program Files\\Java\\pmd-bin-5.1.0\\lib" (Windowsの場合) - [ビルド後の処理の追加] > [PMD警告の集計]
追加指定は不要(デフォルトで使用するレポートファイルが**/pmd.xmlなので)- Windows上でUTF-8ソースファイルを解析する場合は高度な設定のデフォルトのエンコーディングにUTF-8を指定
- [ビルド後の処理の追加] > [重複コード分析の集計]
追加指定は不要(デフォルトで使用するレポートファイルが**/cpd.xmlなので)- Windows上でUTF-8ソースファイルを解析する場合は高度な設定のデフォルトのエンコーディングにUTF-8を指定
FindBugs¶
JenkinsでFindBugsを実行し、その解析結果を集計する設定を行います。
ソースコードと同じリポジトリ(NetBeansの各プロジェクトの下)にFindBugsを入れて、NetBeansの生成するAntプロジェクトにPMDの実行を追記する方法もありますが、多数のNetBeansプロジェクトからなるソフトウェア開発では手間が馬鹿にならないので、ここではJenkinsマシンにFindBugsをインストールし、静的解析ツールを実行する専用のAntビルドファイルを作成します。
- FindBugsのインストール
- FindBugsプラグインのインストール
- FindBugsを実行するAntビルドファイル作成
- Jenkinsの設定
FindBugsのインストール¶
FindBugsのサイトより最新版(あるいは使用するバージョン)をダウンロードします。
http://findbugs.sourceforge.net/
ディレクトリを決めてダウンロードしたファイルを展開します。
- Windowsなら、
C:\Program Files\Java\findbugs-3.0.0
など - Linuxなら、
/usr/share/java/findbugs-3.0.0
など
AntのlibディレクトリにFindBugsのjarファイルを置く方法もあります。antでFindBugsを実行するときにクラスパスの設定が省略できるというメリットがあります。
FindBugsプラグインのインストール¶
Jenkinsのプラグイン管理から、次のプラグインをインストールします。
- FindBugs Plugin
- 依存関係から Static Code Analysis Plug-ins もインストールされます
h5.FindBugsを実行するAntビルドファイルの作成
静的解析対象のソースファイルがあるリポジトリに、Antビルドファイルを置きます。ここでは次のように置くことにします。
<リポジトリ基点> +-- staticanalyze.xml FindBugsを実行するAntビルドファイル +-- report | +-- findbugs | +-- findbugs.xml FindBugsの解析実行結果が格納されるファイル +-- app | + ProjectAlfa NetBeansのプロジェクト | | +-- dist この下にFindBugs解析対象となる製品コード(JARファイル)が格納される | | +-- src この下に製品コードのソースファイルが格納される | | +-- test | + ProjectBeta : :
staticanalyze.xml は次のようになります。
Jenkinsの設定¶
- [ビルド手順の追加] > [Antの呼び出し]
ターゲットに"findbugs"
高度な設定のビルドファイルに"staticanalyze.xml"
プロパティに"libs.findbugs.dir=C:\\Program Files\\Java\\findbugs-3.0.0\\lib" (Windowsの場合) - [ビルド後の処理の追加] > [FindBugs警告の集計]
追加指定は不要(デフォルトで使用するレポートファイルが**/findbugs.xmlなので)- Windows上でUTF-8ソースファイルを解析する場合は高度な設定のデフォルトのエンコーディングにUTF-8を指定
ソースコードメトリクス¶
マスター・スレーブ¶
マスターとスレーブとの間の通信は、次の2種類あります。
- SSH(マスター ⇒ スレーブ)
- "JNLP"(スレーブ ⇒ マスター)
スレーブのOSやネットワークの制約によって使い分けます。
スレーブでjenkinsを実行するアカウント¶
一例として、ユーザー名:jenkins、グループ名:jenkinsにしておきます。
Linuxの場合、UID/GIDも一致させておくと便利です。
ユーザーjenkinsのホームディレクトリは、/var/lib/jenkins が典型例です。
Linux上でマスター、Linuxをスレーブにする(SSH接続)¶
SSH接続、パスワード認証の場合
- [Jenkinsの管理] > [ノードの管理] > [新規ノード作成]
- ノード名(例:[alfa-slave])を記入、[Permanent Agent]を選択
- 説明(適当に)、リモートFSルート(スレーブマシン上でこのディレクトリをワークディレクトリとする)、ラベル(例:ノード名と同じ)を記入
- 用途は、特定のプロジェクト用に構成したスレーブは[このマシーンを特定ジョブ専用にする]を選択
- 起動方法は、マスターとスレーブの通信方法により選択([SSH経由でUnixマシンのスレーブエージェントを起動])
- SSHを選択した場合は、ホスト欄にスレーブのホスト名(IP解決可能な場合)またはIPアドレスを記入
- 同、認証情報の[追加] > [Jenkins]をクリック、「Jenkins Credentials Provider: Jenkins」画面でユーザー名欄とパスワードにスレーブでjenkinsを実行するアカウントを記入(例:jenkins/********)。既にアカウント作成済みならスキップする。
- 同、認証情報の右横をクリックし、使用するアカウントを選択
- 同、Host Key Verification Strategy欄を[Manually trusted key Verification Strategy]を選択する
- 同、Require manual verification of initial connection欄にチェックを付ける
- [保存]を押す
- 作成したノードを選択し、[Trust SSH Host Key]をクリックする
- fingerprintが表示されるので[Yes]をクリックする
→ この操作を忘れると、接続がエラーに
Linux上でマスター、Linuxをスレーブにする(JNLP接続)¶
- SSH接続と同じ設定要領で進め、ただし起動方法の箇所は、[Launch agent by connecting it to the master]を選択
- [Jenkinsの管理] > [グローバルセキュリティの設定] で Agents領域の設定項目[TCP port for inbound agents]を[無効]から[ランダム]に変更
→ 注)ファイアウォールでポート番号を特定する必要があるなら、[固定]で専用のポート番号を指定し、ファイアウォールでそのポート番号を通過可能に設定
スレーブマシンにログインし、次のいずれかの操作でマスターと接続させます。
- WebブラウザでJenkinsに接続、対象ノードを選択し、[Launch]ボタンをクリックしJNLPファイルを開いてJava Web Startでエージェントを実行
→ WindowsマシンにJDK 8をインストーラーでインストールしていればファイル拡張子.jnlpでJava Web Startが動きますが、JDK 11以降しかインストールしていなかったり、インストーラーを使わず(zipをマニュアル展開等)インストールしていると関連付けがないので起動できません。 - WebブラウザでJenkinsに接続、対象ノードを選択し、[Run from agent command line]の下に書かれているコマンド実行行の中にある[agent.jar]のリンクをクリックしを実行
→ 少々長いのでバッチファイルやシェルスクリプト化するとよい
- スレーブを実行するユーザーの$HOME/bin/にagent.jarとrun-slave.shを置き、run-slave.shを記述(以下例)
#!/bin/sh cd $(dirname $0) java -jar agent.jar \ -jnlpUrl http://ci.example.com:8080/computer/alfa-slave/slave-agent.jnlp \ -secret 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \ -workDir "/home/jenkins/slave-jnlp"
Linux上でマスター、Windowsをスレーブにする¶
本項の記述はJenkinsの古いバージョンであり、2020年時点では上述のLinux上でマスター、Linuxをスレーブにする(JNLP接続)項を参照のこと
WindowsをスレーブにするとSSH接続ができないのでJNLPを使います。
JNLPを使うとWindowsスレーブからLinuxマスターへTCPコネクションを張りにいきますが、その際使用されるポート番号はデフォルトではランダムなので、Linux側でiptablesを稼動しているとコネクションがはじかれます。
JNLPポート番号を固定化するには、[Jenkinsの管理] > [グローバルセキュリティの設定] で、[セキュリティの有効化]にチェックを付けます。
すると、設定項目がずらっと表示されます。
JNLPスレーブ用TCPポート番号欄の固定にチェックを付け、ポート番号を記載します。JNLPスレーブ用TCPポート番号