Bitbucket Pipelines 用パイプの作成方法
パイプは、タスクを実行するためのスクリプトを含む、コンテナ用のカスタム Docker イメージです。多数のパイプが提供されていますが、自身で作成することもできます。
1 つのパイプはいくつかの異なるファイルで構成されます。
- スクリプト、またはバイナリ、タスクを実行するコード。
- Dockerfile。スクリプトを実行する Docker コンテナの構築方法を示します。
- (オプション) メタデータと readme ドキュメント。パイプについて理解するのに役立ちます。
- (オプション) パイプを簡単に更新できるようにする、いくつかの CI/CD 構成。
これらのファイルは 1 箇所 (通常はパイプ リポジトリ) に格納されます。
パイプを記述する理由
パイプを記述する理由はいくつかあります。
- パイプラインの複数のステップで同じアクションを実行するため
- 複数のリポジトリで同様のタスクを実行するため
- ベンダーの場合、ソフトウェアまたはサービスをパイプラインによって使いやすくするため
- メインのパイプラインにはない、依存関係を必要とするアクションを実行するため
パイプを作成することで、Pipelines の構成を簡素化し、簡単かつ効率的に再利用できるようになります。
パイプの可能性は無限ですが、すぐに利用できる次のようなパイプを提供しています。
パイプを記述する方法
必要な内容に応じて、シンプルなパイプまたは完全なパイプを作ることができます。これらは同じように動作しますが、追加可能な詳細設定や構成が異なります。
| simple | 完全なパイプ |
|---|---|
| すぐに利用を開始 | べスト プラクティス |
| 後からの更新は複雑性を高める可能性がある | CI/CD によるバージョニングの自動化 |
| 最小限の構成 | 他のユーザーや自身が将来使用できる、便利なドキュメント |
| 私的利用のみ | マーケットプレイスに追加可能 |
次の 3 ファイル
| 前述の 3 つのファイルと次のファイル
|
このガイドでは、まずシンプルなパイプを作成し、それを完全なパイプにする手順について説明します。コンテナをビルドして Dockerhub にアップロードするため、Dockerhub にアカウントがあることを確認してください (無料でセットアップできます)。
Prerequisites
- パイプは、docker ハブのパブリック イメージでのみ機能します。
- Docker に精通していて、私的使用のためにのみパイプを作成したい場合、必要なすべてのファイルを含む独自の Docker コンテナを作成できます。
ステップ 1 - リポジトリを作成またはインポートする
最初に、ファイルを配置する場所が必要となるため、リポジトリを作成します。
パイプ リポジトリを作成する方法は主に 3 つあります。
- 空のリポジトリを作成する (含める情報については後述します)
- サンプル リポジトリのいずれか 1 つをインポートする
- アトラシアンのジェネレータを使用してローカル リポジトリを作成する (完全なパイプでのみ推奨)
また、 シンプルなパイプ リポジトリ 1 つと、参照に使用したり、インポートしたりできる完全なパイプ リポジトリ 2 つ (Bash 用と Python 用) の、3 つのサンプルリポジトリを用意しています。
完全なパイプを作りたい場合、アトラシアンのジェネレータを使用してフレームワークを作成し、ファイルに部分的に入力できます。
ステップ 2 - スクリプトまたはバイナリを作成する
これはパイプが呼び出されたときに実行される、パイプの主要部分です。パイプ タスクを実行するためのすべてのコマンドとロジックが含まれます。任意のコーディング言語を使用して、スクリプトまたはバイナリ ファイルを作成します。
簡単なスクリプトは次のようになります。
#!/usr/bin/env bash
set -e
echo 'Hello World'処理を拡張したい場合、変数を使用できます。
パイプを呼び出すパイプライン ステップで使用可能な任意のデフォルト変数 (デフォルト変数の一覧を参照) と、パイプが呼び出されたときに提供される任意のパイプ変数を使用できます。pipe.yml に記載する場合、ユーザー定義の変数 (アカウントとチーム、リポジトリ、またはデプロイメント) のみを使用できます (詳細は後述)。
#!/usr/bin/env bash
set -e
echo 'Hello $BITBUCKET_REPO_OWNER'
#when you call the pipe from your pipeline
#you can provide variables, for example here: GREETING
echo '$GREETING' いくつかの変数を必須にしたり、指定した既定値を変数で使用するようにしたりすることができます。既定値を指定する方法は 2 とおりあります。ここではスクリプトでの定義方法を示しますが、後ほど、pipe.yml ファイルを使用する、より強力な方法について説明します。bash の完全なパイプの例では両方について説明します。
パイプのエンド ユーザーが使いやすいよう、必須変数は最小限に抑えることをおすすめします。変数に適切な既定値がある場合はスクリプトでそれらを指定すると、エンド ユーザーは必要に応じて変数をオーバーライドできます。
また、ログ出力に色を追加し、外部情報に遷移できるクリック可能なリンクを提供することをおすすめします。
これからスクリプトを実行するため、スクリプトが実行可能である必要があります (したがって、ターミナルで chmod +x pipe.sh を実行することが必要な可能性があります)。アトラシアンのサンプル リポジトリを使用している場合、これはすでに完了しています。
ステップ 3: Dockerfile を構成する
先ほど作成したスクリプトを実行するには、スクリプトを Docker コンテナに入れる必要があります。Dockerfile は、この Docker コンテナを構築する方法の詳細を定義します。最低でも、FROM、COPY、および ENTRYPOINT の値が必要です。
bash の完全なパイプのサンプルの場合、すでにルート ディレクトリに Dockerfile が含まれています。
FROM alpine:3.8
RUN apk update && apk add bash
COPY pipe /
ENTRYPOINT ["/pipe.sh"]この場合、コンテナは次のことを実行します。
- Alpine Linux 3.8 イメージを使用する
- 更新コマンドを実行し、コンテナに bash をインストールする
- pipe ディレクトリの内容をルート ディレクトリにコピーする
- pipe.sh の実行を開始する
これらをニーズに合わせて編集できます。Alpine Linux 3.9 を使用したい場合、FROM alpine:3.9 を読み込むように FROM を変更するだけです。
Linux にさらにパッケージをインストールしたい場合、RUN コマンドに追加します。その前に、それらのパッケージをインストール済みのイメージがあるかどうかを Dockerhub で確認してください。これにより、貴重な時間を節約できます。
希望どおりのスクリプトとコンテナを作成するために、複数回の反復作業が必要になることがあります。これを考慮し、Docker をローカル マシンにインストールすることをおすすめします。こうすることで、ビルド時間を使用せずにパイプ コンテナのビルドと実行をテストできます。
ステップ 4 - パイプ コンテナを Dockerhub に更新するための基本的なパイプラインを作成する
シンプルなパイプを作成する最後のステップは、コンテナを構築し、それを Dockerhub にアップロードすることです。
必ずしもパイプラインを使用する必要はありませんが、これによって将来の更新が容易になり、バージョン番号が自動的に更新されるため、最新バージョンを使用していることをすばやく確認できます。
以下のサンプルの bitbucket-pipelines.yml は、コミットのたびにコンテナの新しいバージョンをビルドして Dockerhub にプッシュします。したがって、Docker コンテナで使用したいイメージを更新したり、スクリプトを変更したりすると、このファイルによって Dockerhub のバージョンが自動的に最新に保たれます。dockerhub アカウントを持っていることを確認したら、pipe リポジトリに 2 つの変数: DOCKERHUB_USERNAME と DOCKERHUB_PASSWORD、を追加し、パイプラインを有効化します。
image:
name: atlassian/default-image:2
pipelines:
default:
- step:
name: Build and Push
script:
# Build and push image
- VERSION="1.$BITBUCKET_BUILD_NUMBER"
- echo ${DOCKERHUB_PASSWORD} | docker login --username "$DOCKERHUB_USERNAME" --password-stdin
- IMAGE="$DOCKERHUB_USERNAME/$BITBUCKET_REPO_SLUG"
- docker build -t ${IMAGE}:${VERSION} .
- docker tag ${IMAGE}:${VERSION} ${IMAGE}:latest
- docker push ${IMAGE}
# Push tags
- git tag -a "${VERSION}" -m "Tagging for release ${VERSION}"
- git push origin ${VERSION}
services:
- dockerこれでシンプルなパイプができました。
シンプルなパイプに必要な手順は以上です。これで、次の構文を使用して、ステップでパイプを参照できるようになりました。
pipe: docker://<DockerAccountName>/<ImageName>:<version>
パイプ作成の次のステップは、長期的な利便性を高め、他のユーザーがパイプを使用しやすくするために設計されています。正式にサポートされるパイプを作りたいユーザーの場合、このステップが必要です。
完全なパイプを作成する場合は、以下もセットアップする必要があります。
- パイプのメタデータ -パイプの詳細 (保守担当者の名前など)
- readme - パイプの使用方法の詳細 (必要な変数など)
- 自動テスト - 変更によって問題が発生していないことの確認
- セマンティック バージョニング - 使用するパイプのバージョンを明確にする
- デバッグ ロギング - 何か問題が生じた場合にエンド ユーザーが容易にトラブルシューティングできるようにする
これらはサンプル リポジトリ (Bash と Python) で構成済みなので、リンク先をご確認ください。次のステップをご案内します。
ステップ 5 - pipe.yml (メタデータ ファイル) を作成する
pipe.yml ファイルは、パイプを分類するための便利な情報を提供します。
キーワード | 説明 |
|---|---|
| パイプに対して表示する名前またはタイトル。 |
| account/repo:tag の形式で Dockerhub 上で作成した、パイプの Docker イメージ。 |
category | Category of the pipe. Can be one of:
|
description | パイプの実行内容を説明する簡単な要約。 |
| Bitbucket pipe repository absolute URL. Example: atlassian/demo-pipe-bash |
| Object that contains name, website and email.
|
| Object that contains name, website and email. For vendor pipes this field is mandatory.
|
| Keywords to help users find and categorize the pipe. Options could include the type of function your pipe performs (deploy, notify, test) or your product, or company, name, or specific tools you are integrating with. |
pipe.yml ファイルは次のようになります。
ステップ 6 - README.md (readme ファイル) を作成する
ユーザーは readme を使用して、パイプの使用方法を確認できます。これは Bitbucket で表示されるため、マークダウンで特定の形式で記述し、見出しを順番に並べる必要があります。
# Bitbucket Pipelines Pipe: <pipe_name> <pipe_short_description > ## YAML Definition Add the following snippet to the script section of your `bitbucket-pipelines.yml` file: ```yaml <pipe_code_snippet> ``` ## Variables <pipe_variables_table> ## Details <pipe_long_description> ## Prerequisites <pipe_prerequisites> ## Examples <pipe_code_examples> ## Support <pipe_support> |
セクション | 説明 |
|---|---|
<pipe_name> | パイプ名 |
<pipe_short_description> | パイプの実行内容の概要 - 次の形式を使用することをお勧めします: "[宛先 | ベンダー | スイート] (への) [アクションを表す動詞]" 例: "Dockerhub へのデプロイ" または "Opsgenie への通知" |
<pipe_code_snippet> | ユーザーがパイプを使用するためにパイプラインにコピーして貼り付ける必要があるもの |
<pipe_variable_table> | パイプが必要とする変数の一覧。必須か任意かを明確にします。 |
<pipe_long_description> | 使用方法、構成、セットアップなどの詳細な説明。 |
<pipe_prerequisites> | パイプを使用する前に必要となるもの。例: インストール済みのパッケージ、サードパーティ システムのアカウント。 |
<pipe_code_examples> | サンプル変数を持つコード スニペット。少なくとも以下を網羅することをおすすめします。
|
<pipe_support> | 質問やサポートのための問い合わせ先を記載します。 |
ステップ 7 - テストを作成する
パイプに自動統合テストを追加することをおすすめします。こうすることで、一般に公開する前に、期待どおりに動作していることを確認できます。たとえば、予期しない変数を処理する方法や、必要なサード パーティ サービスに正常に接続できるかどうかをテストできます。正式にサポートされる予定のパイプは、定期的にテストすることが非常に重要です。
ステップ 8 - パイプをデバッグしやすくする
スクリプトには、パイプで行われていることの追加情報を出力するデバッグ モードを追記することをおすすめします。
また、ログに表示されるリンクをクリックできるようにし、出力では色を使用して重要な情報を強調表示することをおすすめします。
これを行う方法はスクリプトの作成に使用している言語によって異なりますが、アトラシアンの bash デモ リポジトリの common.sh ファイルで例を確認できます。
ステップ 9 - テストと更新を自動化するよう CI/CD をセットアップする
また、CI/CD を以下に使用することをお勧めします。
- 自動テスト
- Dockerhub (または選択したサイト) への自動アップロード
- 以下のバージョン番号を自動的に更新
- 変更履歴
- readme
- メタデータ
bitbucket-pipelines.yml ファイルを構成したら、パイプラインを有効化できます。リポジトリの [設定] > [Pipelines] セクション > [設定] > [パイプラインの有効化] でパイプラインを有効にできます。
ステップ 10 - セマンティック バージョニングをセットアップする
パイプにセマンティック バージョニング (semver) を使用することをお勧めします。これにより、どのバージョンが最新であるか、どのバージョンを使用すべきか、更新によって問題が発生する可能性があるかどうかが明確になります。バージョンは 3 つの部分に分かれます: <major>.<minor>.<patch>。例: 6.5.2
行った変更に応じてバージョン番号を増やします。次のように更新します。
- major: 既存のユーザーによる使用に問題が生じる可能性のある変更を加えた場合 (例: 必須変数の名前の変更)
- minor: 下位互換性のある方法で機能を追加した場合
- patch: 下位互換性のあるバグ修正の場合
バージョンを変更する際は、複数の場所の更新が必要な場合があります。この作業を簡素化する、semversioner (https://pypi.org/project/semversioner/) と呼ばれるツールがあります。このツールは、変更履歴に新しいエントリを作成し、バージョン番号を更新して、リポジトリにコミットします。
ステップ 11 - 新しい完全なパイプを使用する
パイプのシンプルなバージョンと同様、最後のステップはコンテナを構築して Dockerhub にプッシュすることです。
他のリポジトリでこのパイプを参照する方法は 2 とおりあります。bitbucket-pipelines.yml ファイルでは、次の操作を実行できます。
- docker イメージを直接参照する
pipe: docker://acct/repo:tag(ここでacct/repoは Dockerhub アカウントとリポジトリです) - Bitbucket でホストされているパイプ リポジトリを参照する
pipe: <BB_acct>/repo:tag(ここで、BB_acct/repoは自分の Bitbucket アカウントとパイプ リポジトリです)
この参照バージョンは pipe.yml ファイルでイメージの取得先を見つけます。
高度なヒント
- Docker イメージをホストする別のサービスがある場合は Dockerhubを使用する必要はありませんが、イメージは公開されている必要があります。
- Docker をローカル マシンにインストールすることで、アップロードの前にすべてがうまく動作することをテストできます。
- 重要な変数がある場合は、それらの変数が提供され、有効であることをスクリプトでテストするようにします。
- 必須変数は最小限に抑え、可能であれば既定値を指定します。
- 予期せぬ事態が発生した場合に備えて、迅速かつ効率的にパイプ サポートを提供できるプロセスを用意しておきます。フィードバックをすばやく受け取り、パイプ ユーザーにより良いエクスペリエンスを提供できます。
- 他のパイプと共有したいファイル、またはメイン パイプラインで使用するファイルを作成する場合、そのファイルの権限を編集する必要があります。これを行う一般的な方法として、パイプ スクリプトの先頭に
umask 000を配置します。1 つのファイルの値のみを変更したい場合、chownまたはchmodコマンドを使用することもできます。 - 最適な引用方法や配列変数を渡す方法などのさらに高度なパイプ記述テクニックをご覧ください。
公式パイプへの参加
パイプを登録してアトラシアンの公式リストへの追加を依頼できます。その場合、完全なパイプの作成方法に従っていることをご確認ください。
パイプの投稿方法の詳細をご覧ください。