はじめに
Walk Weekender は、架空の川沿いのイベントに向けて来場者用の資料を準備しています。資料パックには、小さな Web サイト、ルートのイラスト、立ち寄り地点の CSV、来場者向けの案内が含まれています。Jenkins には正常に動くパック作成処理がすでにありますが、一時的なワークスペースは実行のたびに消去されます。あなたの仕事は、ダウンロードできる完全な成果物を、そのビルドに関連付けて保存することです。
この実習では、Jenkins の基本的な画面操作、短い Declarative Pipeline を見て理解できること、ZIP の展開を含む基本的なファイル操作を前提としています。アーカイブ、フィンガープリント、ワークスペースのライフサイクルについては、使う前に説明します。Web サイトの作成、ソフトウェアのインストール、Java の知識は必要ありません。
来場者向けの参考見本を確認するには Pack Desk、ビルドと設定には Jenkins を使います。これらは準備済みの 1 台の VM 上で動く 2 つのサービスです。ブラウザーでダウンロードしたファイルは、練習用 VM 内の Jenkins のファイルとは別に、自分のコンピューターに保存されます。各単元は独立した状態で始まります。所要時間は著者による見積もりで、読解と通常の操作ミスへの対応を含みます。初心者による実測値ではありません。
ビルドで作ったファイルの行方を確認する
このステップでは、期待される来場者用の資料を確認し、元のジョブを実行して、ビルドが成功してもダウンロードできるパックが自動的には残らない理由を調べます。Pack Desk から始めてください。
依頼されているのは、Riverwalk Saturday の来場者向けエディション RW-02 です。Reference visitor pack セクションで Open the reference pack を選びます。この見本は、来場者が利用する際の期待される体験を示しています。あなたの成果物は、自分の Jenkins ビルドに保存される ZIP です。
Explore the route を選びます。ルートには、Garden gate、Willow bridge、Orchard yard という、番号付きの立ち寄り地点が 3 か所あります。Download all route stops を選び、保存した CSV を普段使っているテキストビューアーや表計算ソフトで開きます。CSV は、各フィールドをコンマで区切るテキスト形式で、最初の行に列名が記載されています。先頭部分は次のとおりです。
order,stop_id,name,map_x,map_y,visitor_note
1,gate,Garden gate,150,340,Meet beside the blue gate.
Read the visitor notes を選び、ダウンロードしたテキストファイルを読みます。確定した集合時刻は 10:00 です。これらのファイル、正常に動く各ページ、ルート画像は、ひとまとまりの資料です。ファイルをダウンロードしても、表示中のページは変わりません。ブラウザーの Back 操作を 2 回使い、ルートのページからパックの概要ページを経由してデスクに戻ります。
Jenkins タブに切り替えます。create-riverwalk-pack を開き、Build with Parameters を選びます。パラメーターフォームの読み込みが完了するまで待ちます。EDITION は river-v2 のままにし、Build を選びます。このパラメーターで、準備済みの来場者向けエディションを選択します。用意されたプログラムが、その実際の ZIP を作成します。
番号付きビルドが完了するまで待ちます。Builds の下でそのビルドを開き、Console Output を選びます。次の行を探してください。
Prepared visitor edition: Riverwalk Saturday / RW-02
Complete event-pack.zip created.
...
Finished: SUCCESS
プログラムは確かにパックを作成しています。Pipeline ログをさらに下まで読み、最後の事後処理の中にある [Pipeline] deleteDir を探してください。用意されたクリーンアップ処理は、各ステージが終わった後に、この実行のワークスペース内のファイルを削除します。
ワークスペース（workspace）は、ジョブの実行のために Jenkins が割り当てる作業ディレクトリです。ビルドはそこにファイルを作成し、後で削除することもできます。SUCCESS は実行の結果を表します。生成されたすべてのファイルを Jenkins が自動的に保存した、という意味ではありません。
パンくずリストのリンクを使い、この番号付きビルドの状態ページに戻ります。この元の実行には、アーティファクト event-pack.zip をダウンロードするリンクがありません。ジョブはファイルを作成しましたが、アーカイブを保存する前に消去してしまいました。次の実行と比較できるように、このビルドを履歴に残してください。
クリーンアップの前にアーカイブを保存する
このステップでは、完全な来場者用 ZIP を保存し、ワークスペースのクリーンアップを維持したまま、ダウンロードしたファイルを利用します。Jenkins の create-riverwalk-pack ジョブページから始めてください。
Configure を選び、Pipeline セクションに進みます。Script エディターには、用意されたビルドの各ステージと post ブロックがあります。このブロック内の always セクションは、実行が失敗した場合も含めて、ステージの後に実行されます。その中の deleteDir() 操作は、割り当てられたワークスペースを消去します。このクリーンアップは残してください。
archiveArtifacts は、クリーンアップの前に、選択したワークスペースのファイルを、そのビルドに保存されるアーティファクトへコピーします。artifacts の設定値は、そのワークスペースを基準とするファイル名またはパターンです。'event-pack.zip' を囲む一重引用符は、これを文字列として表します。fingerprint: true は、Jenkins のファイル使用状況を追跡するための識別情報も記録します。これは、次のガイド付き実習で、ジョブ間の ZIP の受け渡しを追跡する際に役立ちます。フィンガープリントが記録するのは、ファイルの同一性と使用状況です。公開者の署名ではありません。
コロンは各設定とその値を区切り、コンマは設定同士を区切ります。stages の内側で、Build pack の後に Archive pack ステージを追加します。パラメーター、ビルドコマンド、クリーンアップは維持してください。全体をコピーできる版を使う場合は、Script の内側をクリックし、Windows/Linux では Ctrl+A、macOS では Command+A で内容をすべて選択して、次の内容に置き換えます。
pipeline {
agent any
parameters {
choice(name: 'EDITION', choices: ['river-v2'], description: 'Visitor edition to prepare')
}
stages {
stage('Prepare workspace') {
steps { deleteDir() }
}
stage('Build pack') {
steps { sh 'sh /var/jenkins_home/walk-pack-fixtures/build-pack.sh' }
}
stage('Archive pack') {
steps {
archiveArtifacts artifacts: 'event-pack.zip', fingerprint: true
}
}
}
post {
always { deleteDir() }
}
}
Save を選びます。もう一度 Build with Parameters を実行します。パラメーターフォームの読み込みが完了するまで待ち、EDITION は river-v2 のままにして、Build を選びます。この新しい番号付きビルドが正常に完了するまで待ちます。コンソールには Archiving artifacts、Recording fingerprints、最後のクリーンアップが表示されるはずです。
新しいビルドの状態ページを開き、Build Artifacts を探します。event-pack.zip をダウンロードしてください。ワークスペースが消去されても、Jenkins はこの ZIP をそのビルドの一部として保存しています。
自分のコンピューターのアーカイブツールで、ZIP 全体を新しいフォルダーに展開します。展開先のフォルダーにある index.html をブラウザーで開いてください。次の 8 つのファイルは、すべて展開先の同じフォルダーに置いてください。
index.html
route.html
styles.css
route-map.png
stops.csv
visitor-notes.txt
event.json
build.json
Riverwalk Saturday、エディション RW-02、集合時刻 10:00 を確認します。Explore the route を開き、3 か所すべての立ち寄り地点を確認し、ルートの CSV をダウンロードします。続いて Read the visitor notes を選び、ローカルのテキストファイルを読みます。ブラウザーによっては、このテキストファイルは新たにダウンロードされず、ページに直接表示されることがあります。このファイルは、展開したフォルダーにすでに含まれています。画像とリンクはローカルファイルを使うため、この来場者用パックは練習用 VM とは独立して利用できます。
展開したページのスタイルや画像が表示されない場合は、ZIP 全体を展開したことと、開いた index.html が styles.css および route-map.png と同じフォルダーにあることを確認してください。ZIP ビューアーの中から HTML ファイルだけを開くと、必要なリソースと切り離されることがあります。ファイルを作り直すのではなく、最初にダウンロードした ZIP を新しいフォルダーに展開してください。
Jenkins で Groovy の構文エラーが表示された場合は、Configure に戻り、上記の完全なスクリプトを復元して、Save を選び、river-v2 を再実行します。波括弧と一重引用符を維持してください。用意されたジョブをそのまま実行する前に編集してしまった場合は、Archive pack だけを一時的に削除し、保存して 1 回実行します。その後、完全なスクリプトを復元して、もう一度実行してください。
最終的な成果物は、現在保存されている Pipeline から生成されたものでなければなりません。さらに編集した場合は、再実行してください。以前のビルドと、用意されたパックのファイルは残します。この練習用 VM は一時的なものです。実習が終わっても、ダウンロードしたコピーは手元に保管してください。
まとめ
実際に作成されたパックが一時的なワークスペースから消える様子を確認し、その後、Jenkins のアーカイブ機能とフィンガープリントの記録によって、完全な ZIP を保存しました。クリーンアップを維持し、元のビルドアーティファクトをダウンロードして、そのページ、画像、ルートデータ、来場者向けの案内を、単独で利用できるひとまとまりの来場者用パックとして使いました。
