Pipelines as Code
Pipelines as Code の設定と使用
概要
第1章 Pipelines as Code について
Pipelines as Code を使用すると、クラスター管理者と必要な権限を持つユーザーは、パイプラインテンプレートをソースコード Git リポジトリーの一部として定義できます。設定された Git リポジトリーに対するソースコードのプッシュまたはプルリクエストによってトリガーされると、Pipelines as Code はパイプラインを実行し、ステータスを報告します。
1.1. 主な特長
Pipelines as Code は、次の機能をサポートしています。
- プルリクエストのステータスおよび Git リポジトリーをホストするプラットフォームの制御。
- GitHub は API を確認し、パイプライン実行のステータスを設定します (再チェックを含む)。
- GitHub のプルリクエストとコミットイベント。
-
/retest
などのコメントでリクエストアクションをプルします。 - Git イベントのフィルタリング、およびイベントごとの個別のパイプライン。
- ローカルタスク、Tekton Hub、およびリモート URL を含む、OpenShift Pipelines での自動タスク解決。
- GitHub blob およびオブジェクト API を使用した設定の取得。
-
GitHub 組織または Prow スタイルの
OWNERS
ファイルを使用したアクセス制御リスト (ACL)。 -
ブートストラップおよび Pipelines as Code リポジトリーを管理するための
tkn pac
CLI プラグイン。 - GitHub App、GitHub Webhook、Bitbucket Server、および Bitbucket Cloud のサポート。
第2章 Pipelines as Code のインストールと設定
パイプラインとしてのコードは、Red Hat OpenShift Pipelines インストールの一部としてインストールできます。
2.1. OpenShift Container Platform への Pipelines as Code のインストール
Red Hat OpenShift Pipelines Operator をインストールすると、Pipelines as Code が openshift-pipelines
namespace にインストールされます。詳細は、関連情報 セクションの OpenShift パイプラインのインストール を参照してください。
Operator を使用して Pipelines as Code のデフォルトインストールを無効にするには、TektonConfig
カスタムリソースで enable
パラメーターの値を false
に設定します。
apiVersion: operator.tekton.dev/v1alpha1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: enable: false settings: application-name: Pipelines as Code CI auto-configure-new-github-repo: "false" bitbucket-cloud-check-source-ip: "true" hub-catalog-name: tekton hub-url: https://api.hub.tekton.dev/v1 remote-tasks: "true" secret-auto-create: "true" # ...
必要に応じて、以下のコマンドを実行できます。
$ oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": false}}}}}'
Red Hat OpenShift Pipelines Operator を使用して Pipelines as Code のデフォルトインストールを有効にするには、TektonConfig
カスタムリソースで enable
パラメーターの値を true
に設定します。
apiVersion: operator.tekton.dev/v1alpha1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: enable: true settings: application-name: Pipelines as Code CI auto-configure-new-github-repo: "false" bitbucket-cloud-check-source-ip: "true" hub-catalog-name: tekton hub-url: https://api.hub.tekton.dev/v1 remote-tasks: "true" secret-auto-create: "true" # ...
必要に応じて、以下のコマンドを実行できます。
$ oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": true}}}}}'
2.2. Pipelines as Code CLI のインストール
クラスター管理者は、ローカルマシンで、またはテスト用のコンテナーとして tkn-pac
および opc
CLI ツールを使用できます。tkn pac
および opc
CLI ツールは、Red Hat OpenShift Pipelines の tkn
CLI をインストールすると自動的にインストールされます。
サポートされているプラットフォーム用の tkn pac
および opc
バージョン 1.15.0
バイナリーをインストールできます。
2.3. Pipelines as Code 設定のカスタマイズ
Pipelines as Code をカスタマイズするには、クラスター管理者は、platforms.openshift.pipelinesAsCode.settings
仕様の TektonConfig
カスタムリソースで次のパラメーターを設定できます。
パラメーター | 説明 | デフォルト |
---|---|---|
| アプリケーションの名前。たとえば、GitHub Checks ラベルに表示される名前です。 |
|
| GitHub アプリケーションで生成されたトークンを使用してシークレットを自動的に作成するかどうかを示します。このシークレットは、プライベートリポジトリーで使用できます。 |
|
| 有効にすると、パイプライン実行アノテーションからのリモートタスクを許可します。 |
|
| Tekton Hub API のベース URL。 | |
| Tekton Hub のカタログ名。 |
|
|
Tekton Hub ダッシュボードの URL。Pipelines as Code は、この URL を使用して、Tekton Hub ダッシュボードに | NA |
| パブリック Bitbucket の IP 範囲をクエリーしてサービス要求を保護するかどうかを示します。パラメーターのデフォルト値を変更すると、セキュリティーの問題が発生する可能性があります。 |
|
| コンマで区切られた追加の IP 範囲またはネットワークのセットを提供するかどうかを示します。 | NA |
|
パイプライン実行の | NA |
|
パイプライン実行の | NA |
| 新しい GitHub リポジトリーを自動的に設定します。Pipelines as Code は namespace を設定し、リポジトリーのカスタムリソースを作成します。このパラメーターは、GitHub アプリケーションでのみサポートされています。 |
|
|
|
|
| 失敗したタスク (パイプラインにエラーがある) のログスニペットの表示を有効または無効にします。パイプラインからのデータ漏えいの場合は、このパラメーターを無効にすることができます。 |
|
| エラーメッセージを検出し、プルリクエストのアノテーションとして公開するためのコンテナーログの検査を有効または無効にします。この設定は、GitHub アプリを使用している場合にのみ適用されます。 |
|
|
エラーメッセージを検索するためにコンテナーログ内で検査される最大行数。無制限の行数を検査するには、 | 50 |
|
|
|
| 生成された GitHub アクセストークンのスコープを設定するための追加のリポジトリー。 |
2.4. 追加の GitHub アプリケーションをサポートするための、追加の Pipelines as Code コントローラー設定
デフォルトでは、Pipelines as Code を設定して、1 つの GitHub アプリケーションと対話できます。場合によっては、複数の GitHub アプリケーションを使用する必要があることがあります。たとえば、異なる GitHub アカウントや、GitHub Enterprise や GitHub SaaS などの異なる GitHub インスタンスを使用する必要がある場合などです。複数の GitHub アプリケーションを使用する場合は、追加の GitHub アプリケーションごとに追加の Pipelines as Code コントローラーを設定する必要があります。
手順
TektonConfig
カスタムリソースで、次の例のように、platforms.openshift.pipelinesAsCode
仕様にadditionalPACControllers
セクションを追加します。例:
additionalPACControllers
セクションapiVersion: operator.tekton.dev/v1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: additionalPACControllers: pac_controller_2: 1 enable: true 2 secretName: pac_secret_2 3 settings: # 4 # ...
- 1
- コントローラーの名前。この名前は一意であり、長さが 25 文字を超えてはなりません。
- 2
- このパラメーターは任意です。追加のコントローラーを有効にするにはこのパラメーターを
true
に設定し、追加のコントローラーを無効にするにはfalse
に設定します。デフォルト値はtrue
です。 - 3
- このパラメーターを、GitHub アプリケーション用に作成する必要があるシークレットの名前に設定します。
- 4
- このセクションはオプションです。このセクションでは、メインの Pipelines as Code コントローラーとは異なる設定が必要な場合に、このコントローラーの Pipelines as Code 設定を指定できます。
-
オプション: 2 つ以上の GitHub アプリケーションを使用する場合は、
pipelinesAsCode.additionalPACControllers
仕様の下に追加のセクションを作成し、すべての GitHub インスタンスに対して Pipelines as Code コントローラーを設定します。各コントローラーに一意の名前を使用します。
2.5. 関連情報
第3章 サービスプロバイダーをホストする Git リポジトリーでの Pipelines as Code の使用
Pipelines as Code をインストールした後に、クラスター管理者はサービスプロバイダーをホストする Git リポジトリーを設定できます。現在、以下のサービスがサポートされています。
- GitHub アプリケーション
- GitHub Webhook
- GitLab
- Bitbucket Server
- Bitbucket Cloud
GitHub アプリケーションは、Pipelines as Code での使用に推奨されるサービスです。
3.1. GitHub アプリケーションでの Pipelines as Code の使用
GitHub アプリケーションは Red Hat OpenShift Pipeline とのインテグレーションポイントとして機能し、Git ベースのワークフローのメリットを OpenShift Pipelines にもたらします。クラスター管理者は、すべてのクラスターユーザーに単一の GitHub アプリケーションを設定できます。GitHub アプリケーションが Pipelines as Code と連携するには、GitHub アプリケーションの Webhook が GitHub イベントをリッスンする Pipelines as Code リスナールート (または受信エンドポイント) をポイントするようにします。
Pipelines as Code 用に GitHub アプリケーションを設定する方法は 3 つあります。
-
tkn
コマンドラインユーティリティーを使用します。 - Web コンソールの管理者の視点を使用します。
- GitHub でアプリケーションを手動で設定し、Pipelines as Code のシークレットを作成します。
デフォルトでは、Pipelines as Code は 1 つの GitHub アプリケーションと通信できます。追加の GitHub アプリケーションと通信するために追加の Pipelines as Code コントローラーを設定した場合は、各 GitHub アプリケーションを個別に設定します。追加のコントローラーの場合は、GitHub アプリケーションを手動で設定する必要があります。
3.1.1. コマンドラインインターフェイスを使用した GitHub アプリケーションの設定
tkn
コマンドラインユーティリティーを使用して GitHub アプリケーションを作成し、GitHub アプリケーションの Pipelines as Code コントローラーを設定できます。
追加の GitHub アプリケーションをサポートするために追加の Pipelines as Code コントローラーを作成した場合、この手順はメインコントローラーに対してのみ使用できます。追加のコントローラー用の GitHub アプリケーションを作成するには、手動の手順を使用します。
前提条件
- クラスター管理者として OpenShift Container Platform クラスターにログインしている。
-
tkn pac
プラグインとともにtkn
コマンドラインユーティリティーをインストールしている。
手順
以下のコマンドを入力します。
$ tkn pac bootstrap github-app
このコマンドは、アカウントが標準の github.com API エンドポイントを使用していることを前提としています。別の GitHub API エンドポイントを使用する場合 (たとえば、GitHub Enterprise を使用する場合)、次の例のように
--github-api-url
オプションを使用してエンドポイントを指定します。コマンドの例
$ tkn pac bootstrap github-app --github-api-url https://github.com/enterprises/example-enterprise
3.1.2. 管理者パースペクティブでの GitHub アプリケーションの作成
クラスター管理者は、OpenShift Container Platform クラスターで GitHub アプリケーションを Pipelines as Code を使用するように設定できます。この設定により、ビルドのデプロイに必要な一連のタスクを実行できます。
追加の GitHub アプリケーションをサポートするために追加の Pipelines as Code コントローラーを作成した場合、この手順はメインコントローラーに対してのみ使用できます。追加のコントローラー用の GitHub アプリケーションを作成するには、手動の手順を使用します。
前提条件
Operator Hub から Red Hat OpenShift Pipelines pipelines-1.15
Operator をインストールしている。
手順
- 管理者パースペクティブで、ナビゲーションペインを使用して Pipelines に移動します。
- Pipelines ページで GitHub アプリのセットアップ をクリックします。
-
GitHub のアプリケーション名を入力します。例:
pipelines-ci-clustername-testui
- Setup をクリックします。
- ブラウザーでプロンプトが表示されたら、Git パスワードを入力します。
-
Create GitHub App for <username> をクリックします。ここで、
<username>
は GitHub ユーザー名です。
検証
GitHub App の作成に成功すると、OpenShift Container Platform Web コンソールが開き、アプリケーションの詳細を表示します。
GitHub App の詳細は、openShift-pipelines
namespace にシークレットとして保存されます。
GitHub アプリケーションに関連付けられている名前、リンク、シークレットなどの詳細を表示するには、パイプライン に移動し、GitHub アプリの表示 をクリックします。
3.1.3. GitHub アプリケーションの手動設定および Pipelines as Code のシークレットの作成
GitHub ユーザーインターフェイスを使用して GitHub アプリケーションを作成できます。次に、GitHub アプリケーションに接続するために Pipelines as Code を設定するシークレットを作成する必要があります。
追加の GitHub アプリケーションをサポートするために追加の Pipelines as Code コントローラーを作成した場合は、追加のコントローラーに対してこの手順を使用する必要があります。
手順
- GitHub アカウントにサインインします。
- GitHub メニューで、Settings → Developer settings → GitHub Apps を選択し、New GitHub App をクリックします。
GitHub App フォームに以下の情報を入力します。
-
GitHub Application Name:
OpenShift Pipelines
- Homepage URL: OpenShift Console の URL
Webhook URL: Pipelines as Code ルートまたは受信 URL次のコマンドを実行すると、これを見つけることができます。
$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
あるいは、追加の Pipelines as Code コントローラー用に GitHub アプリケーションを設定するには、次の例のように、
pipelines-as-code-controller
を、設定したコントローラーの名前に置き換えます。コマンドの例
$ echo https://$(oc get route -n openshift-pipelines pac_controller_2 -o jsonpath='{.spec.host}')
Webhook secret: 任意のシークレット。次のコマンドを実行してシークレットを生成できます。
$ openssl rand -hex 20
-
GitHub Application Name:
Repository permissions セクションで次の項目を選択します。
-
Checks:
Read & Write
-
Contents:
Read & Write
-
Issues:
Read & Write
-
Metadata:
Read-only
-
Pull request:
Read & Write
-
Checks:
Organization permissions セクションで次の項目を選択します。
-
Members:
Read-only
-
Plan:
Read-only
-
Members:
次のイベントにサブスクライブします。
- Check run
- Check suite
- Commit comment
- Issue comment
- Pull request
- プッシュ
- Create GitHub App をクリックします。
- 新たに作成された GitHub App の Details ページで、上部に表示される App ID を書き留めます。
- Private keys セクションで、Generate Private key をクリックして GitHub アプリケーションの秘密鍵を自動的に生成およびダウンロードします。今後の参照や使用のために秘密鍵を安全に保管します。
- 作成したアプリを Pipelines as Code で使用するリポジトリーにインストールします。
次のコマンドを入力して、新しく作成された GitHub アプリケーションにアクセスできるように Pipelines as Code を設定します。
$ oc -n openshift-pipelines create secret generic pipelines-as-code-secret \ 1 --from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \ 2 --from-literal github-application-id="<APP_ID>" \ 3 --from-literal webhook.secret="<WEBHOOK_SECRET>" 4
GitHub Enterprise から設定されたヘッダーを検出し、それを GitHub Enterprise API 承認 URL に使用することで、Pipelines as Code は自動的に GitHub Enterprise と連携します。
3.1.4. GitHub トークンのスコープの追加のリポジトリー設定
Pipelines as Code は、GitHub アプリを使用して GitHub アクセストークンを生成します。Pipelines as Code は、このトークンを使用してリポジトリーからパイプラインペイロードを取得し、CI/CD プロセスが GitHub リポジトリーと対話できるようにします。
デフォルトでは、アクセストークンのスコープは、Pipelines as Code がパイプライン定義を取得するリポジトリーのみに限定されます。場合によっては、トークンに追加のリポジトリーへのアクセスを許可したい場合があります。たとえば、.tekton/pr.yaml
ファイルとソースペイロードが配置されている CI リポジトリーが存在する可能性がありますが、pr.yaml
で定義されたビルドプロセスは別のプライベート CD リポジトリーからタスクを取得します。
GitHub トークンのスコープは、次の 2 つの方法で拡張できます。
- グローバル設定: GitHub トークンをさまざまな namespace のリポジトリーのリストに拡張できます。この設定を設定するには、管理者権限が必要です。
- リポジトリーレベルの設定: GitHub トークンを、元のリポジトリーと同じ namespace に存在するリポジトリーのリストに拡張できます。この設定を設定するために管理者権限は必要ありません。
手順
-
TektonConfig
カスタムリソース (CR) のpipelinesAsCode.settings
仕様で、secret-github-app-token-scoped
パラメーターをfalse
に設定します。この設定により、GitHub トークンのスコープを、グローバルおよびリポジトリーレベルの設定にリストされているプライベートおよびパブリックリポジトリーに設定できるようになります。 GitHub トークンのスコープを指定するためのグローバル設定を設定するには、
TektonConfig
CR のpipelinesAsCode.settings
仕様で、次の例のようにsecret-github-app-scope-extra-repos
パラメーターで追加のリポジトリーを指定します。apiVersion: operator.tekton.dev/v1alpha1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: enable: true settings: secret-github-app-token-scoped: false secret-github-app-scope-extra-repos: "owner2/project2, owner3/project3"
GitHub トークンのスコープを設定するためのリポジトリーレベルの設定を設定するには、次の例のように、
Repository
CR のgithub_app_token_scope_repos
パラメーターで追加のリポジトリーを指定します。apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: test namespace: test-repo spec: url: "https://github.com/linda/project" settings: github_app_token_scope_repos: - "owner/project" - "owner1/project1"
この例では、
Repository
カスタムリソースはtest-repo
namespace のlinda/project
リポジトリーに関連付けられています。生成された GitHub トークンのスコープはlinda/project
リポジトリーだけでなく、owner/project
およびowner1/project1
リポジトリーにも拡張されます。これらのリポジトリーは、test-repo
namespace の下に存在する必要があります。注記追加のリポジトリーはパブリックまたはプライベートにすることができますが、
Repository
リソースが関連付けられているリポジトリーと同じ namespace に存在する必要があります。いずれかのリポジトリーが namespace に存在しない場合、GitHub トークンのスコープ設定は失敗し、次のエラーメッセージが表示されます。
failed to scope GitHub token as repo owner1/project1 does not exist in namespace test-repo
結果
生成された GitHub トークンにより、グローバルおよびリポジトリーレベルの設定で設定した追加のリポジトリーに加え、Pipelines as Code ペイロードファイルが配置されている元のリポジトリーにアクセスできるようになります。
グローバル設定とリポジトリーレベル設定の両方を指定すると、次の例に示すように、トークンのスコープは両方の設定のすべてのリポジトリーになります。
TektonConfig
カスタムリソース
apiVersion: operator.tekton.dev/v1alpha1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: enable: true settings: secret-github-app-token-scoped: false secret-github-app-scope-extra-repos: "owner2/project2, owner3/project3"
Repository
カスタムリソース
apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: test namespace: test-repo spec: url: "https://github.com/linda/project" settings: github_app_token_scope_repos: - "owner/project" - "owner1/project1"
GitHub トークンのスコープは、owner/project
、owner1/project1
、owner2/project2
、owner3/project3
、および linda/project
リポジトリーです。
3.2. GitHub Webhook での Pipelines as Code の使用
GitHub アプリケーションを作成できない場合は、リポジトリーで GitHub Webhook で Pipelines as Code を使用します。ただし、GitHub Webhook で Pipelines as Code を使用しても、GitHub Check Runs API にはアクセスできません。タスクのステータスはプル要求のコメントとして追加され、Checks タブでは利用できません。
GitHub Webhook を使用した Pipelines as Code は、/retest
や /ok-to-test
などの GitOps コメントには対応していません。継続的インテグレーション (CI) を再開するには、リポジトリーへの新しいコミットを作成します。たとえば、変更を加えずに新しいコミットを作成するには、次のコマンドを使用できます。
$ git --amend -a --no-edit && git push --force-with-lease <origin> <branchname>
前提条件
- Pipelines as Code がクラスターにインストールされている。
承認用に GitHub で個人アクセストークンを作成する。
セキュアで粒度の細かいトークンを生成するには、そのスコープを特定のリポジトリーに制限し、以下のパーミッションを付与します。
表3.1 粒度の細かいトークンのパーミッション 名前 アクセス 管理
Read-only
メタデータ
Read-only
Content
Read-only
コミットステータス
読み取りおよび書き込み
プルリクエスト
読み取りおよび書き込み
Webhook
読み取りおよび書き込み
クラシックトークンを使用するには、パブリックリポジトリーのスコープを
public_repo
に設定し、プライベートリポジトリーのスコープをrepo
に設定します。さらに、トークンの有効期限を短くして、別の場所でトークンを書き留めておきます。注記tkn pac
CLI を使用して Webhook を設定する必要がある場合は、admin:repo_hook
スコープを追加します。
手順
Webhook を設定し、
リポジトリー
カスタムリソース (CR) を作成します。tkn pac
CLI ツールを使用して webhook を設定し、リポジトリー
CR を 自動的に 作成するには、次のコマンドを使用します。$ tkn pac create repo
対話型出力の例
? Enter the Git repository url (default: https://github.com/owner/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes ✓ Repository owner-repo has been created in repo-pipelines namespace ✓ Setting up GitHub Webhook for Repository https://github.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: sJNwdmTifHTs): sJNwdmTifHTs ℹ ️You now need to create a GitHub personal access token, please checkout the docs at https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token for the required scopes ? Please enter the GitHub access token: **************************************** ✓ Webhook has been created on repository owner/repo 🔑 Webhook Secret owner-repo has been created in the repo-pipelines namespace. 🔑 Repository CR owner-repo has been updated with webhook secret in the repo-pipelines namespace ℹ Directory .tekton has been created. ✓ We have detected your repository using the programming language Go. ✓ A basic template has been created in /home/Go/src/github.com/owner/repo/.tekton/pipelinerun.yaml, feel free to customize it.
Webhook を設定して
Repository
CR を 手動 で作成するには、以下の手順を実行します。OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。
$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
GitHub リポジトリーまたは組織で、以下の手順を実行します。
- Settings -> Webhooks に移動し、Add webhook をクリックします。
- Payload URL を Pipelines as Code コントローラーのパブリック URL に設定します。
- コンテンツタイプを application/json として選択します。
Webhook シークレットを追加し、別の場所に書き留めます。
openssl
がローカルマシンにインストールされた状態で、ランダムなシークレットを生成します。$ openssl rand -hex 20
- Let me select individual events をクリックし、Commit comments、Issue comments、Pull request、および Pushes のイベントを選択します。
- Add webhook をクリックします。
OpenShift クラスターで、個人アクセストークンおよび Webhook シークレットを使用して
Secret
オブジェクトを作成します。$ oc -n target-namespace create secret generic github-webhook-config \ --from-literal provider.token="<GITHUB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"
Repository
CR を作成します。例:
Repository
CRapiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://github.com/owner/repo" git_provider: secret: name: "github-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "github-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret
注記Pipelines as Code は、OpenShift
Secret
オブジェクトとRepository
CR が同じ namespace にあることを前提としています。
オプション: 既存の
Repository
CR の場合、複数の GitHub Webhook シークレットを追加するか、削除されたシークレットの代わりを提供します。tkn pac
CLI ツールを使用して Webhook を追加します。例:
tkn pac
CLI を使用した追加の Webhook$ tkn pac webhook add -n repo-pipelines
対話型出力の例
✓ Setting up GitHub Webhook for Repository https://github.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: AeHdHTJVfAeH): AeHdHTJVfAeH ✓ Webhook has been created on repository owner/repo 🔑 Secret owner-repo has been updated with webhook secert in the repo-pipelines namespace.
-
既存の OpenShift
Secret
オブジェクトのwebhook.secret
キーを更新します。
オプション: 既存の
Repository
CR の場合は、Personal Access Token を更新します。tkn pac
CLI ツールを使用して Personal Access Token を更新します。例:
tkn pac
CLI を使用した Personal Access Token の更新$ tkn pac webhook update-token -n repo-pipelines
対話型出力の例
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.
または、
Repository
CR を変更して Personal Access Token トークンを更新します。Repository
CR でシークレットの名前を見つけます。apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: # ... git_provider: secret: name: "github-webhook-config" # ...
oc patch
コマンドを使用して、$target_namespace
namespace の$NEW_TOKEN
の値を更新します。$ oc -n $target_namespace patch secret github-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"
3.3. GitLab での Pipelines as Code の使用
組織またはプロジェクトが優先プラットフォームとして GitLab を使用する場合は、GitLab の Webhook を使用してリポジトリーの Pipelines as Code を使用できます。
前提条件
- Pipelines as Code がクラスターにインストールされている。
承認には、GitLab のプロジェクトまたは組織のマネージャーとして Personal Access Token トークンを生成します。
注記-
tkn pac
CLI を使用して Webhook を設定する必要がある場合は、admin:repo_hook
スコープをトークンに追加します。 - 特定のプロジェクトを対象とするトークンを使用しても、フォークされたリポジトリーから送信されたマージリクエスト (MR) に API でのアクセスはできません。このような場合、Pipelines as Code はパイプラインの結果を MR のコメントとして表示します。
-
手順
Webhook を設定し、
リポジトリー
カスタムリソース (CR) を作成します。tkn pac
CLI ツールを使用して webhook を設定し、リポジトリー
CR を 自動的に 作成するには、次のコマンドを使用します。$ tkn pac create repo
対話型出力の例
? Enter the Git repository url (default: https://gitlab.com/owner/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes ✓ Repository repositories-project has been created in repo-pipelines namespace ✓ Setting up GitLab Webhook for Repository https://gitlab.com/owner/repo ? Please enter the project ID for the repository you want to be configured, project ID refers to an unique ID (e.g. 34405323) shown at the top of your GitLab project : 17103 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: lFjHIEcaGFlF): lFjHIEcaGFlF ℹ ️You now need to create a GitLab personal access token with `api` scope ℹ ️Go to this URL to generate one https://gitlab.com/-/profile/personal_access_tokens, see https://is.gd/rOEo9B for documentation ? Please enter the GitLab access token: ************************** ? Please enter your GitLab API URL:: https://gitlab.com ✓ Webhook has been created on your repository 🔑 Webhook Secret repositories-project has been created in the repo-pipelines namespace. 🔑 Repository CR repositories-project has been updated with webhook secret in the repo-pipelines namespace ℹ Directory .tekton has been created. ✓ A basic template has been created in /home/Go/src/gitlab.com/repositories/project/.tekton/pipelinerun.yaml, feel free to customize it.
Webhook を設定して
Repository
CR を 手動 で作成するには、以下の手順を実行します。OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。
$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
GitLab プロジェクトで、以下の手順を実行します。
- 左側のサイドバーを使用して Settings -> Webhooks に移動します。
- URL を Pipelines as Code コントローラーのパブリック URL に設定します。
Webhook シークレットを追加し、別の場所に書き留めます。
openssl
がローカルマシンにインストールされた状態で、ランダムなシークレットを生成します。$ openssl rand -hex 20
- Let me select individual events をクリックし、Commit comments、Issue comments、Pull request、および Pushes のイベントを選択します。
- Save changes をクリックします。
OpenShift クラスターで、個人アクセストークンおよび Webhook シークレットを使用して
Secret
オブジェクトを作成します。$ oc -n target-namespace create secret generic gitlab-webhook-config \ --from-literal provider.token="<GITLAB_PERSONAL_ACCESS_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"
Repository
CR を作成します。例:
Repository
CRapiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://gitlab.com/owner/repo" # The repository URL git_provider: #url: "https://gitlab.example.com/" 1 secret: name: "gitlab-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "gitlab-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret
- 1
- GitLab.com ではなく GitLab のプライベートインスタンスを使用している場合は、このフィールドのコメントを解除して、GitLab API の URL に設定します。GitLab API はリポジトリーと同じホストです。たとえば、リポジトリーが
https://gitlab.example.com/owner/repo
の場合、API URL はhttps://gitlab.example.com/
です。
注記-
Pipelines as Code は、OpenShift
Secret
オブジェクトとRepository
CR が同じ namespace にあることを前提としています。
オプション: 既存の
Repository
CR の場合、複数の GitLab Webhook シークレットを追加するか、削除されたシークレットの代わりを提供します。tkn pac
CLI ツールを使用して Webhook を追加します。例:
tkn pac
CLI を使用した Webhook の追加$ tkn pac webhook add -n repo-pipelines
対話型出力の例
✓ Setting up GitLab Webhook for Repository https://gitlab.com/owner/repo 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ? Please enter the secret to configure the webhook for payload validation (default: AeHdHTJVfAeH): AeHdHTJVfAeH ✓ Webhook has been created on repository owner/repo 🔑 Secret owner-repo has been updated with webhook secert in the repo-pipelines namespace.
-
既存の OpenShift
Secret
オブジェクトのwebhook.secret
キーを更新します。
オプション: 既存の
Repository
CR の場合は、Personal Access Token を更新します。tkn pac
CLI ツールを使用して Personal Access Token を更新します。例:
tkn pac
CLI を使用した Personal Access Token の更新$ tkn pac webhook update-token -n repo-pipelines
対話型出力の例
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.
または、
Repository
CR を変更して Personal Access Token トークンを更新します。Repository
CR でシークレットの名前を見つけます。... spec: git_provider: secret: name: "gitlab-webhook-config" ...
oc patch
コマンドを使用して、$target_namespace
namespace の$NEW_TOKEN
の値を更新します。$ oc -n $target_namespace patch secret gitlab-webhook-config -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"
3.4. Bitbucket Cloud での Pipelines as Code の使用
組織またはプロジェクトが優先プラットフォームとして Bitbucket Cloud を使用する場合、Bitbucket Cloud の Webhook を使用してリポジトリーに Pipelines as Code を使用できます。
前提条件
- Pipelines as Code がクラスターにインストールされている。
Bitbucket Cloud でアプリのパスワードを作成する。
以下のボックスをチェックして、適切なパーミッションをトークンに追加します。
-
アカウント:
メール
、読み取り
-
ワークスペースのメンバーシップ:
読み取り
、書き込み
-
プロジェクト:
読み取り
、書き込み
-
問題:
読み取り
、書き込み
プルリクエスト:
読み取り
、書き込み
注記-
tkn pac
CLI を使用して Webhook を設定する必要がある場合は、Webhooks
:Read
とWrite
パーミッションをトークンに追加します。 - 生成されたら、パスワードまたはトークンのコピーを別の場所に保存します。
-
-
アカウント:
手順
Webhook を設定し、
Repository
CR を作成します。tkn pac
CLI ツールを使用して webhook を設定し、リポジトリー
CR を 自動的に 作成するには、次のコマンドを使用します。$ tkn pac create repo
対話型出力の例
? Enter the Git repository url (default: https://bitbucket.org/workspace/repo): ? Please enter the namespace where the pipeline should run (default: repo-pipelines): ! Namespace repo-pipelines is not found ? Would you like me to create the namespace repo-pipelines? Yes ✓ Repository workspace-repo has been created in repo-pipelines namespace ✓ Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo ? Please enter your bitbucket cloud username: <username> ℹ ️You now need to create a Bitbucket Cloud app password, please checkout the docs at https://is.gd/fqMHiJ for the required permissions ? Please enter the Bitbucket Cloud app password: ************************************ 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ✓ Webhook has been created on repository workspace/repo 🔑 Webhook Secret workspace-repo has been created in the repo-pipelines namespace. 🔑 Repository CR workspace-repo has been updated with webhook secret in the repo-pipelines namespace ℹ Directory .tekton has been created. ✓ A basic template has been created in /home/Go/src/bitbucket/repo/.tekton/pipelinerun.yaml, feel free to customize it.
Webhook を設定して
Repository
CR を 手動 で作成するには、以下の手順を実行します。OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。
$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
Bitbucket Cloud で、以下の手順を実行します。
- Bitbucket Cloud リポジトリーの左側のナビゲーションペインを使用して Repository settings -> Webhooks に移動し、Add webhook をクリックします。
- Title を設定します。たとえば、"Pipelines as Code" です。
- URL を Pipelines as Code コントローラーのパブリック URL に設定します。
- Repository: Push、Pull Request: Created、Pull Request: Updated、および Pull Request: Comment created のイベントを選択します。
- Save をクリックします。
OpenShift クラスターで、ターゲット namespace に app パスワードを使用して
Secret
オブジェクトを作成します。$ oc -n target-namespace create secret generic bitbucket-cloud-token \ --from-literal provider.token="<BITBUCKET_APP_PASSWORD>"
Repository
CR を作成します。例:
Repository
CRapiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://bitbucket.com/workspace/repo" branch: "main" git_provider: user: "<BITBUCKET_USERNAME>" 1 secret: name: "bitbucket-cloud-token" 2 key: "provider.token" # Set this if you have a different key in your secret
注記-
tkn pac create
およびtkn pac bootstrap
コマンドは Bitbucket Cloud ではサポートされていません。 Bitbucket Cloud では Webhook シークレットはサポートされません。ペイロードを保護し、CI のハイジャックを防止するために、Pipelines as Code は Bitbucket Cloud IP アドレスのリストをフェッチし、Webhook の受信がそれらの IP アドレスからのみ行われるようにします。
-
デフォルトの動作を無効にするには、
pipelinesAsCode.settings
仕様のTektonConfig
カスタムリソースでbitbucket-cloud-check-source-ip
パラメーターをfalse
に設定します。 -
追加の安全な IP アドレスまたはネットワークを許可するには、
pipelinesAsCode.settings
仕様のTektonConfig
カスタムリソースのbitbucket-cloud-Additional-source-ip
パラメーターにコンマ区切りの値として追加します。
-
デフォルトの動作を無効にするには、
オプション: 既存の
Repository
CR の場合は、複数の Bitbucket Cloud Webhook シークレットを追加するか、削除されたシークレットの代わりに指定します。tkn pac
CLI ツールを使用して Webhook を追加します。例:
tkn pac
CLI を使用した Webhook の追加$ tkn pac webhook add -n repo-pipelines
対話型出力の例
✓ Setting up Bitbucket Webhook for Repository https://bitbucket.org/workspace/repo ? Please enter your bitbucket cloud username: <username> 👀 I have detected a controller url: https://pipelines-as-code-controller-openshift-pipelines.apps.example.com ? Do you want me to use it? Yes ✓ Webhook has been created on repository workspace/repo 🔑 Secret workspace-repo has been updated with webhook secret in the repo-pipelines namespace.
注記[-n <namespace>]
オプションをtkn pac webhook add
コマンドで使用するのは、Repository
CR がデフォルト以外の namespace に存在する場合のみです。-
既存の OpenShift
Secret
オブジェクトのwebhook.secret
キーを更新します。
オプション: 既存の
Repository
CR の場合は、Personal Access Token を更新します。tkn pac
CLI ツールを使用して Personal Access Token を更新します。例:
tkn pac
CLI を使用した Personal Access Token の更新$ tkn pac webhook update-token -n repo-pipelines
対話型出力の例
? Please enter your personal access token: **************************************** 🔑 Secret owner-repo has been updated with new personal access token in the repo-pipelines namespace.
注記[-n <namespace>]
オプションをtkn pac webhook update-token
コマンドで使用するのは、Repository
CR がデフォルト以外の namespace に存在する場合のみです。または、
Repository
CR を変更して Personal Access Token を更新します。Repository
CR でシークレットの名前を見つけます。... spec: git_provider: user: "<BITBUCKET_USERNAME>" secret: name: "bitbucket-cloud-token" key: "provider.token" ...
oc patch
コマンドを使用して、$target_namespace
namespace の$password
の値を更新します。$ oc -n $target_namespace patch secret bitbucket-cloud-token -p "{\"data\": {\"provider.token\": \"$(echo -n $NEW_TOKEN|base64 -w0)\"}}"
3.5. Bitbucket サーバーでの Pipelines as Code の使用
組織またはプロジェクトが優先プラットフォームとして Bitbucket Server を使用する場合は、Bitbucket Server の Webhook でリポジトリーの Pipelines as Code を使用できます。
前提条件
- Pipelines as Code がクラスターにインストールされている。
Bitbucket Server でプロジェクトのマネージャーとして Personal Access Token を生成し、そのコピーを別の場所に保存します。
注記-
トークンには、
PROJECT_ADMIN
およびREPOSITORY_ADMIN
権限が必要です。 - トークンには、プルリクエストでフォークされたリポジトリーへのアクセスが必要です。
-
トークンには、
手順
OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。
$ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
Bitbucket Server で、以下の手順を実行します。
- Bitbucket Data Center リポジトリーの左側のナビゲーションペインを使用して Repository settings -> Webhooks に移動し、Add webhook をクリックします。
- Title を設定します。たとえば、"Pipelines as Code" です。
- URL を Pipelines as Code コントローラーのパブリック URL に設定します。
Webhook シークレットを追加し、そのコピーを別の場所に保存します。
openssl
をローカルマシンにインストールしている場合は、以下のコマンドを使用してランダムなシークレットを生成します。$ openssl rand -hex 20
以下のイベントを選択します。
- Repository: Push
- Repository: Modified
- Pull Request: Opened
- Pull Request: Source branch updated
- Pull Request: Comment added
- Save をクリックします。
OpenShift クラスターで、ターゲット namespace に app パスワードを使用して
Secret
オブジェクトを作成します。$ oc -n target-namespace create secret generic bitbucket-server-webhook-config \ --from-literal provider.token="<PERSONAL_TOKEN>" \ --from-literal webhook.secret="<WEBHOOK_SECRET>"
Repository
CR を作成します。例:
Repository
CRapiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: url: "https://bitbucket.com/workspace/repo" git_provider: url: "https://bitbucket.server.api.url/rest" 1 user: "<BITBUCKET_USERNAME>" 2 secret: 3 name: "bitbucket-server-webhook-config" key: "provider.token" # Set this if you have a different key in your secret webhook_secret: name: "bitbucket-server-webhook-config" key: "webhook.secret" # Set this if you have a different key for your secret
注記tkn pac create
およびtkn pac bootstrap
コマンドは Bitbucket サーバーではサポートされません。
3.6. Pipelines as Code とカスタム証明書のインターフェイス
プライベートに署名またはカスタム証明書を使用してアクセス可能な Git リポジトリーで Pipelines as Code を設定するには、証明書を Pipelines as Code に公開できます。
手順
-
Red Hat OpenShift Pipelines Operator を使用して Pipelines as Code をインストールしている場合、
Proxy
オブジェクトを使用してカスタム証明書をクラスターに追加できます。Operator は、Pipelines as Code を含むすべての Red Hat OpenShift Pipelines コンポーネントおよびワークロードの証明書を公開します。
関連情報
3.7. Pipelines as Code でのプライベートリポジトリーの使用
Pipelines as Code は、ユーザートークンを使用してターゲット namespace でシークレットを作成または更新することで、プライベートリポジトリーをサポートします。Tekton Hub からの git-clone
タスクは、ユーザートークンを使用してプライベートリポジトリーのクローンを作成します。
コードとしてのパイプラインは、ターゲット namespace で新しいパイプライン実行を作成するたびに、pac-gitauth-<REPOSITORY_OWNER>-<REPOSITORY_NAME>-<RANDOM_STRING>
形式でシークレットを作成または更新します。
パイプライン実行およびパイプライン定義の basic-auth
ワークスペースでシークレットを参照する必要があり、これは、git-clone
タスクに渡されます。
... workspace: - name: basic-auth secret: secretName: "{{ git_auth_secret }}" ...
パイプラインでは、git-clone
タスクの再使用に basic-auth
ワークスペースを参照できます。
...
workspaces:
- name basic-auth
params:
- name: repo_url
- name: revision
...
tasks:
workspaces:
- name: basic-auth
workspace: basic-auth
...
tasks:
- name: git-clone-from-catalog
taskRef:
name: git-clone 1
params:
- name: url
value: $(params.repo_url)
- name: revision
value: $(params.revision)
...
- 1
git-clone
タスクはbasic-auth
ワークスペースを取得し、これを使用してプライベートリポジトリーのクローンを作成します。
この設定を変更するには、TektonConfig
カスタムリソースの pipelinesAsCode.settings
仕様で、必要に応じて secret-auto-create
パラメーターを false
または true
の値に設定します。
第4章 Repository カスタムリソースの使用
Repository
カスタムリソース (CR) には、次の主要な機能があります。
- URL からのイベントの処理について Pipelines as Code に通知します。
- Pipeline 実行の namespace について Pipelines as Code に通知します。
- Webhook メソッドを使用する場合、Git プロバイダープラットフォームに必要な API シークレット、ユーザー名、または API URL を参照します。
- リポジトリーの最後のパイプライン実行ステータスを指定します。
4.1. Repository カスタムリソースの作成
tkn pac
CLI または他の代替方法を使用して、ターゲット名前空間内に Repository
カスタムリソース (CR) を作成できます。以下に例を示します。
cat <<EOF|kubectl create -n my-pipeline-ci -f- 1
apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
name: project-repository
spec:
url: "https://github.com/<repository>/<project>"
EOF
- 1
my-pipeline-ci
はターゲット namespace です。
https://github.com/<repository>/<project>
などの URL からイベントが発生すると、Pipelines as Code はその URL とマッチさせ、<repository>/<project>
リポジトリーのコンテンツのチェックアウトを開始し、パイプラインを実行して .tekton/
ディレクトリーのコンテンツとマッチさせます。
-
ソースコードリポジトリーに関連付けられたパイプラインが実行されるのと同じ namespace に
Repository
CR を作成する必要があります。これは別の namespace をターゲットにすることはできません。 -
複数の
Repository
CR が同じイベントと一致する場合、コードとしてのパイプラインは最も古い CR のみを処理します。特定の namespace と同じにする必要がある場合は、pipelinesascode.tekton.dev/target-namespace: "<mynamespace>"
アノテーションを追加します。このような明示的なターゲティングにより、悪意のあるアクターがアクセス権のない namespace でパイプラインの実行を防ぎます。
4.2. グローバルの Repository カスタムリソースの作成
オプションで、OpenShift Pipelines がインストールされている namespace (通常は openshift-pipelines)
にグローバル Repository
カスタムリソース (CR) を作成できます。この CR を作成すると、その中で指定した設定が、作成するすべての Repository
CR にデフォルトで適用されます。
グローバルの Repository
CR はテクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品サポートのサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではない場合があります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
前提条件
-
openshift-pipelines
namespace への管理者アクセスがある。 -
oc
コマンドラインユーティリティーを使用して OpenShift クラスターにログインしている。
手順
openshift-pipelines
namespace にpipeline-as-code
という名前のRepository
CR を作成します。この CR で必要なすべてのデフォルト設定を指定します。CR を作成するコマンドの例
$ cat <<EOF|oc create -n openshift-pipelines -f - apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: pipelines-as-code spec: git_provider: secret: name: "gitlab-webhook-config" key: "provider.token" webhook_secret: name: "gitlab-webhook-config" key: "webhook.secret" EOF
この例では、作成するすべての
Repository
CR に、GitLab リポジトリーにアクセスするための共通シークレットが含まれます。CR では、さまざまなリポジトリー URL やその他の設定を指定できます。
4.3. 同時実行制限の設定
Repository
カスタムリソース定義 (CRD) で concurrency_limit
仕様を使用して、リポジトリーに対して同時に実行されるパイプライン実行の最大数を定義できます。
apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: # ... concurrency_limit: <number> # ...
イベントに一致する複数のパイプラインが実行される場合、パイプラインは、イベントの開始に一致するアルファベット順に実行されます。
たとえば、.tekton
ディレクトリーに 3 つのパイプラインが実行され、リポジトリー設定に concurrency_limit
が 1
のプルリクエストを作成する場合、すべてのパイプライン実行はアルファベット順に実行されます。常に 1 つのパイプライン実行のみが running 状態にあり、残りはキューに入れられます。
4.4. パイプライン定義のソースブランチの変更
デフォルトでは、プッシュイベントまたはプルリクエストイベントを処理するときに、Pipelines as Code はイベントをトリガーしたブランチからパイプライン定義をフェッチします。Repository
カスタムリソース定義 (CRD) の pipelinerun_provenance
設定を使用して、Git リポジトリープロバイダーに設定されているデフォルトブランチ (main
、master
、または trunk
など) から定義をフェッチできます。
apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: my-repo namespace: target-namespace spec: # ... settings: pipelinerun_provenance: "default_branch" # ...
この設定はセキュリティー対策として使用できます。デフォルトの動作では、Pipelines as Code は送信されたプルリクエスト内のパイプライン定義を使用します。default-branch
設定では、パイプライン定義を実行する前にデフォルトブランチにマージする必要があります。この要件により、マージレビュー中に変更が最大限に検証されることが保証されます。
4.5. カスタムパラメーターの拡張
Pipelines as Code を使用すると、params
フィールドを使用して PipelineRun
リソース内のカスタムパラメーターをデプロイメントできます。Repository
カスタムリソース (CR) のテンプレート内のカスタムパラメーターの値を指定できます。指定された値は、パイプライン実行のカスタムパラメーターを置き換えます。
カスタムパラメーターは次のシナリオで使用できます。
- プッシュまたはプルリクエストに基づいて変化するレジストリー URL などの URL パラメーターを定義します。
-
Git リポジトリー内の
PipelineRun
実行に変更を加えることなく、管理者が管理できるアカウント UUID などのパラメーターを定義します。
Tekton パラメーターは Pipeline
リソースで定義され、Git リポジトリー内でそれに沿ってカスタマイズされるため、Tekton PipelineRun
パラメーターを使用できない場合にのみ、カスタムパラメーター拡張機能を使用してください。ただし、カスタムパラメーターは、Repository
CR が配置されている場所で定義およびカスタマイズされます。したがって、CI/CD パイプラインを 1 つのポイントから管理することはできません。
次の例は、Repository
CR 内の company
という名前のカスタムパラメーターを示しています。
... spec: params: - name: company value: "ABC Company" ...
値 ABC Company
は、パイプライン実行およびリモートでフェッチされたタスクのパラメーター名 company
を置き換えます。
次の例に示すように、Kubernetes シークレットからカスタムパラメーターの値を取得することもできます。
... spec: params: - name: company secretRef: name: my-secret key: companyname ...
Pipelines as Code は、以下の方法でカスタムパラメーターを解析して使用します。
-
value
とsecretRef
が定義されている場合、Pipelines as Code はvalue
を使用します。 -
params
セクションにname
がない場合、Pipelines as Code はパラメーターを解析しません。 -
同じ
name
のparams
が複数ある場合、Pipelines as Code は最後のパラメーターを使用します。
カスタムパラメーターを定義し、指定された条件が CEL フィルターに一致した場合にのみその拡張を使用することもできます。次の例は、プルリクエストイベントがトリガーされたときに company
という名前のカスタムパラメーターに適用される CEL フィルターを示しています。
... spec: params: - name: company value: "ABC Company" filter: - name: event value: | pac.event_type == "pull_request" ...
同じ名前と異なるフィルターを持つ複数のパラメーターがある場合、Pipelines as Code はフィルターに一致する最初のパラメーターを使用します。そのため、Pipelines as Code を使用すると、さまざまなイベントタイプに応じてパラメーターを拡張できます。たとえば、プッシュリクエストイベントとプルリクエストイベントを組み合わせることができます。
第5章 Pipelines as Code の使用
Pipelines as Code リゾルバーは、実行中のパイプライン実行が他のパイプライン実行と競合しないようにします。
5.1. Pipelines as Code リゾルバーについて
パイプラインとパイプライン実行を分割するには、ファイルを .tekton/
ディレクトリーまたはそのサブディレクトリーに保存します。
Pipelines as Code が、.tekton/
ディレクトリーにある YAML ファイル内のタスクまたはパイプラインへの参照を使用してパイプライン実行を監視すると、Pipelines as Code は、参照されたタスクを自動的に解決して、PipelineRun
オブジェクトに埋め込まれた仕様と合わせて単一のパイプラインを実行します。
Pipelines as Code が Pipeline
または PipelineSpec
定義で参照されるタスクを解決できない場合に、実行はクラスターに適用される前に失敗します。Git プロバイダープラットフォームと、Repository
CR が置かれているターゲット namespace のイベント内で問題を確認できます。
リゾルバーは、以下のタイプのタスクを監視する場合に解決を省略します。
- クラスタータスクへの参照。
- タスクまたはパイプラインバンドル。
-
API バージョンに
tekton.dev/
接頭辞のないカスタムタスク。
リゾルバーは、そのようなタスクを変換せずにそのまま使用します。
プルリクエストに送信する前にパイプライン実行をローカルでテストするには、tkn pac resolve
コマンドを使用します。
リモートパイプラインおよびタスクを参照することもできます。
5.2. Pipelines as Code でのリモートタスクアノテーションの使用
Pipelines as Code は、パイプライン実行でアノテーションを使用してリモートタスクまたはパイプラインの取得をサポートします。パイプライン実行、または PipelineRun
または PipelineSpec
オブジェクトのパイプラインでリモートタスクを参照する場合に、Pipelines as Code リゾルバーにはこれが自動的に含まれます。リモートタスクのフェッチまたは解析中にエラーが発生した場合、Pipelines as Code はタスクの処理を停止します。
リモートタスクを含めるには、以下のアノテーションの例を参照してください。
Tekton Hub でのリモートタスクの参照
Tekton Hub で単一のリモートタスクを参照します。
... pipelinesascode.tekton.dev/task: "git-clone" 1 ...
- 1
- Pipelines as Code には、Tekton Hub からのタスクの最新バージョンが含まれています。
Tekton Hub から複数のリモートタスクを参照します。
... pipelinesascode.tekton.dev/task: "[git-clone, golang-test, tkn]" ...
-<NUMBER>
接尾辞を使用して、Tekton Hub から複数のリモートタスクを参照します。... pipelinesascode.tekton.dev/task: "git-clone" pipelinesascode.tekton.dev/task-1: "golang-test" pipelinesascode.tekton.dev/task-2: "tkn" 1 ...
- 1
- デフォルトでは、Pipelines as Code は文字列を Tekton Hub から取得する最新のタスクとして解釈します。
Tekton Hub からリモートタスクの特定のバージョンを参照します。
... pipelinesascode.tekton.dev/task: "[git-clone:0.1]" 1 ...
- 1
- Tekton Hub からの
git-clone
リモートタスクの0.1
バージョンを参照します。
URL を使用するリモートタスク
...
pipelinesascode.tekton.dev/task: "<https://remote.url/task.yaml>" 1
...
- 1
- リモートタスクへの公開 URL。注記
GitHub を使用し、リモートタスク URL が
Repository
カスタムリソース定義 (CRD) と同じホストを使用する場合、Pipelines as Code は GitHub トークンを使用し、GitHub API を使用して URL を取得します。たとえば、
https://github.com/<organization>/<repository>
のようなリポジトリー URL があり、リモート HTTP URL がhttps://github.com/<organization>/<repository>/blob/<mainbranch>/<path>/<file>
のような GitHub ブロブを参照している場合に、Pipelines as Code は、GitHub アプリトークンを使用して、そのプライベートリポジトリーからタスク定義ファイルをフェッチします。パブリック GitHub リポジトリーで作業する場合、Pipelines as Code は
https://raw.githubusercontent.com/<organization>/<repository>/<mainbranch>/<path>/<file>
などの GitHub の raw URL と同様に機能します。- GitHub アプリケーショントークンは、リポジトリーが置かれている所有者または組織に対してスコープが設定されます。GitHub Webhook メソッドを使用すると、個人トークンが許可されている任意の組織のプライベートまたはパブリックリポジトリーを取得できます。
リポジトリー内の YAML ファイルからのタスク参照
...
pipelinesascode.tekton.dev/task: "<share/tasks/git-clone.yaml>" 1
...
- 1
- タスク定義を含むローカルファイルへの相対パス。
5.3. Pipelines as Code でのリモートパイプラインアノテーションの使用
リモートパイプラインアノテーションを使用すると、複数のリポジトリーでパイプライン定義を共有できます。
...
pipelinesascode.tekton.dev/pipeline: "<https://git.provider/raw/pipeline.yaml>" 1
...
- 1
- リモートパイプライン定義への URL。同じリポジトリー内のファイルの場所を指定することもできます。
アノテーションを使用してパイプライン定義を 1 つだけ参照できます。
5.3.1. リモートパイプラインのタスクをオーバーライドする
デフォルトでは、パイプライン実行でリモートパイプラインアノテーションを使用する場合、Pipelines as Code はリモートパイプラインの一部であるすべてのタスクを使用します。
パイプラインの実行にタスクのアノテーションを追加することで、リモートパイプラインのタスクをオーバーライドできます。追加されたタスクは、リモートパイプライン内のタスクと同じ名前を持つ必要があります。
たとえば、次のパイプライン実行定義を使用できます。
リモートパイプラインを参照し、タスクをオーバーライドするパイプライン実行定義の例
apiVersion: tekton.dev/v1 kind: PipelineRun metadata: annotations: pipelinesascode.tekton.dev/pipeline: "https://git.provider/raw/pipeline.yaml" pipelinesascode.tekton.dev/task: "./my-git-clone-task.yaml"
この例では、https://git.provider/raw/pipeline.yaml
にあるリモートタスクに git-clone
という名前のタスクが含まれており、my-git-clone-task.yaml
ファイルで定義されているタスクの名前も git-clone
であると仮定します。
この場合は、パイプライン実行によりリモートパイプラインが実行されますが、パイプライン内の git-clone
という名前のタスクが定義したタスクに置き換えられます。
第6章 パイプライン実行の管理
Pipelines as Code を使用すると、コードリポジトリーにパイプラインを作成し、これらのパイプラインを実行できます。
6.1. Pipelines as Code を使用したパイプライン実行の作成
Pipelines as Code を使用してパイプラインを実行するには、リポジトリーの .tekton/
ディレクトリーにパイプライン実行定義またはテンプレートを YAML ファイルとして作成します。リモート URL を使用して他のリポジトリー内の YAML ファイルを参照できますが、パイプラインの実行は、.tekton/
ディレクトリーを含むリポジトリー内のイベントによってのみトリガーされます。
Pipelines as Code リゾルバーは、パイプラインの実行をすべてのタスクと共に、外部依存関係のない単一のパイプラインの実行としてバンドルします。
-
Pipeline の場合、spec または分離された
Pipeline
オブジェクトと共に少なくとも 1 つのパイプライン実行を使用します。 - タスクの場合、パイプライン内にタスク仕様を埋め込むか、Task オブジェクトとして個別に定義します。
コミットと URL のパラメーター化
{{<var>}} 形式の動的でデプロイメント可能な変数を使用して、コミットと URL のパラメーターを指定できます。現在、以下の変数を使用できます。
-
{{repo_owner}}
: リポジトリーの所有者。 -
{{repo_name}}
: リポジトリー名。 -
{{repo_url}}
: リポジトリーの完全な URL。 -
{{revision}}
: コミットの完全 SHA リビジョン。 -
{{sender}}
: コミットの送信者のユーザー名またはアカウント ID。 -
{{source_branch}}
: イベントが発生したブランチ名。 -
{{target_branch}}
: イベントが対象とするブランチ名。プッシュイベントの場合、これはsource_branch
と同じです。 -
{{pull_request_number}}
:pull_request
イベントタイプに対してのみ定義されたプルまたはマージリクエスト番号。 -
{{git_auth_secret}}
: プライベートリポジトリーをチェックアウトするための Git プロバイダーのトークンで自動的に生成されるシークレット名。
イベントのパイプライン実行へのマッチング
パイプライン実行の特別なアノテーションを使用して、異なる Git プロバイダーイベントを各パイプライン実行に一致させることができます。イベントトガッチする複数のパイプライン実行がある場合に、Pipelines as Code はそれらを並行して実行し、パイプライン実行の終了直後に結果を Git プロバイダーに Post します。
プルイベントのパイプライン実行へのマッチング
次の例を使用して、main
ブランチを対象とする pull_request
イベントと、pipeline-pr-main
パイプライン実行を一致させることができます。
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-pr-main
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[main]" 1
pipelinesascode.tekton.dev/on-event: "[pull_request]"
# ...
- 1
- コンマ区切りのエントリーを追加して、複数のブランチを指定できます。たとえば、
"[main, release-nightly]"
です。さらに、以下を指定できます。-
"refs/heads/main"
などのブランチへの完全な参照 -
"refs/heads/\*"
などのパターンマッチングを含む glob -
"refs/tags/1.\*"
などのタグ
-
プッシュイベントのパイプライン実行とのマッチング
次の例を使用して、pipeline-push-on-main
パイプライン実行を refs/heads/main
ブランチを対象とする push
イベントと一致させることができます。
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: pipeline-push-on-main
annotations:
pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" 1
pipelinesascode.tekton.dev/on-event: "[push]"
# ...
- 1
- コンマ区切りのエントリーを追加して、複数のブランチを指定できます。たとえば、
"[main, release-nightly]"
です。さらに、以下を指定できます。-
"refs/heads/main"
などのブランチへの完全な参照 -
"refs/heads/\*"
などのパターンマッチングを含む glob -
"refs/tags/1.\*"
などのタグ
-
コメントイベントのパイプライン実行へのマッチング
次の例を使用すると、コメントのテキストが ^/merge-pr
正規表現と一致する場合に、pipeline-comment
パイプライン実行をプルリクエストのコメントと一致させることができます。
apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: pipeline-comment annotations: pipelinesascode.tekton.dev/on-comment: "^/merge-pr" # ...
パイプラインの実行は、コメント作成者が次のいずれかの要件を満たしている場合にのみ開始されます。
- 作成者がリポジトリーの所有者である。
- 作成者がリポジトリーのコラボレーターである。
- 作成者がリポジトリーの組織のパブリックメンバーである。
-
コメントの作成者が Kubernetes ドキュメント で定義されているように、リポジトリーのルートにある
OWNERS
ファイルのapprovers
またはreviewers
のセクションにリストされている。Pipelines as Code はOWNERS
およびOWNERS_ALIASES
ファイルの仕様をサポートします。OWNERS
ファイルに フィルター セクションが含まれている場合、Pipelines as Code は approvers と reviewers を.*
フィルターに対してのみ照合します。
コメントイベントをパイプライン実行に一致させる機能は、テクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品サポートのサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではない場合があります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
高度なイベントマッチング
コードとしてのパイプラインは、高度なイベントマッチングのための Common Expression Language (CEL) ベースのフィルタリングの使用をサポートします。パイプラインの実行に pipelinesascode.tekton.dev/on-cel-expression
アノテーションがある場合に、Pipelines as Code は CEL 式を使用し、on-target-branch
アノテーションをスキップします。単純な オンターゲットブランチ
アノテーションマッチングと比較して、CEL 式では複雑なフィルタリングと否定が可能です。
Pipelines as Code で CEL ベースのフィルタリングを使用するには、次のアノテーションの例を検討してください。
main
ブランチを対象とし、wip
ブランチからのpull_request
イベントを一致させるには、次のようにします。apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: pipeline-advanced-pr annotations: pipelinesascode.tekton.dev/on-cel-expression: | event == "pull_request" && target_branch == "main" && source_branch == "wip" ...
パスが変更された場合にのみパイプラインを実行するには、glob パターンで
.pathChanged
接尾辞関数を使用できます。apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: pipeline-advanced-pr-pathchanged annotations: pipelinesascode.tekton.dev/on-cel-expression: | event == "pull_request" && "docs/\*.md".pathChanged() 1 # ...
- 1
docs
ディレクトリー内のすべてのマークダウンファイルと一致します。
[DOWNSTREAM]
で始まるすべてのプルリクエストとマッチさせるには、以下を実行します。apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: pipeline-advanced-pr-downstream annotations: pipelinesascode.tekton.dev/on-cel-expression: | event == "pull_request && event_title.startsWith("[DOWNSTREAM]") # ...
pull_request
イベントでパイプラインを実行し、experimental
ブランチを省略するには、以下を実行します。apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: pipeline-advanced-pr-not-experimental annotations: pipelinesascode.tekton.dev/on-cel-expression: | event == "pull_request" && target_branch != experimental" # ...
Pipelines as Code を使用しながら高度な CEL ベースのフィルタリングを行うには、次のフィールドと接尾辞関数を使用できます。
-
event
:push
またはpull_request
イベント。 -
target_branch
: ターゲットブランチ。 -
source_branch
: 元のpull_request
イベントのブランチ。push
イベントの場合は、target_branch
と同じです。 -
event_title
:push
イベントのコミットタイトルや、pull_request
イベントのプルまたはマージリクエストのタイトルなど、イベントのタイトルとマッチします。現在、サポートされているプロバイダーは GitHub、Gitlab、および Bitbucket Cloud のみです。 -
.pathChanged
: 文字列への接尾辞関数です。文字列は、パスが変更されたかどうかを確認するパスの glob にすることができます。現在、GitHub と Gitlab のみがプロバイダーとしてサポートされています。
さらに、Git リポジトリープロバイダーによって渡された完全なペイロードにアクセスできます。headers
フィールドを使用して、ペイロードのヘッダー (headers['x-github-event']
など) にアクセスします。body
フィールドを使用して、ペイロードの本文 (body.pull_request.state
など) にアクセスします。
Pipelines as Code による CEL ベースのフィルタリングにペイロードのヘッダーと本文を使用するのは、テクノロジープレビューのみの機能です。テクノロジープレビュー機能は、Red Hat 製品サポートのサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではない場合があります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
次の例では、次の条件がすべて満たされる場合にのみパイプラインの実行が開始します。
-
プルリクエストは
main
ブランチをターゲットとしています。 -
プルリクエストの作成者は
superuser
です。 -
アクションは
synchronize
です。このアクションは、プルリクエストで更新が発生したときにトリガーされます。
apiVersion: tekton.dev/v1 kind: PipelineRun metadata: annotations: pipelinesascode.tekton.dev/on-cel-expression: | body.pull_request.base.ref == "main" && body.pull_request.user.login == "superuser" && body.action == "synchronize" # ...
イベントの一致に header
または body
フィールドを使用する場合は、retest
などの Git コマンドを使用してパイプラインの実行をトリガーできない可能性があります。Git コマンドを使用する場合、ペイロード本体は、元のペイロードではなく、このコマンドを含むコメントになります。
イベント一致に body
フィールドを使用するときにパイプラインの実行を再度トリガーする場合は、プルリクエストまたはマージリクエストを閉じて再度開くか、たとえば次のコマンドを使用して新しい SHA コミットを追加します。
git commit --amend --no-edit && git push --force-with-lease
Github API 操作への一時的な GitHub App トークンの使用
GitHub アプリケーションの Pipelines as Code によって生成された一時インストールトークンを使用して、GitHub API にアクセスできます。トークン値は git-provider-token
キーのプライベートリポジトリー用に生成された一時的な {{git_auth_secret}}
動的変数に格納されます。
たとえば、プル要求にコメントを追加するには、Pipelines as Code アノテーションを使用して Tekton Hub からの github-add-comment
タスクを使用できます。
... pipelinesascode.tekton.dev/task: "github-add-comment" ...
その後、タスクをパイプライン実行定義の tasks
セクションまたは finally
タスクに追加できます。
[...]
tasks:
- name:
taskRef:
name: github-add-comment
params:
- name: REQUEST_URL
value: "{{ repo_url }}/pull/{{ pull_request_number }}" 1
- name: COMMENT_OR_FILE
value: "Pipelines as Code IS GREAT!"
- name: GITHUB_TOKEN_SECRET_NAME
value: "{{ git_auth_secret }}"
- name: GITHUB_TOKEN_SECRET_KEY
value: "git-provider-token"
...
- 1
- 動的変数を使用すると、任意のリポジトリーからのプルリクエストに対して、このスニペットテンプレートを再利用できます。
GitHub アプリでは、生成されたインストールトークンは 8 時間利用可能で、クラスターで別の設定を行わない限り、イベントの発生元のリポジトリーにスコープが設定されます。
6.2. Pipelines as Code を使用したパイプライン実行
デフォルト設定では、Pipelines as Code は、プルリクエストやプッシュなどの指定されたイベントがリポジトリーで発生したときに、リポジトリーのデフォルトブランチの .tekton/
ディレクトリーで実行されるすべてのパイプラインを実行します。たとえば、デフォルトのブランチで実行されるパイプラインに、アノテーション pipelinesascode.tekton.dev/on-event: "[pull_request]"
がある場合に、これはプル要求イベントが発生するたびに実行されます。
プルリクエストまたはマージリクエストが発生した場合、プルリクエストの作成者が次の条件を満たしている場合、Pipelines as Code はデフォルトブランチ以外のブランチからもパイプラインを実行します。
- 作成者がリポジトリーの所有者である。
- 作成者がリポジトリーのコラボレーターである。
- 作成者がリポジトリーの組織のパブリックメンバーである。
-
プルリクエストの作成者が Kubernetes ドキュメント で定義されているように、リポジトリーのルートにある
OWNERS
ファイルのapprovers
またはreviewers
セクションにリストされている。Pipelines as Code はOWNERS
およびOWNERS_ALIASES
ファイルの仕様をサポートします。OWNERS
ファイルに フィルター セクションが含まれている場合、Pipelines as Code は approvers と reviewers を.*
フィルターに対してのみ照合します。
プル要求の作成者は、要件を満たす別のユーザーがプル要求で /ok-to-test
をコメントして、パイプライン実行を開始できます。
パイプライン実行
パイプラインの実行は常に、イベントを生成したリポジトリーに関連付けられた Repository
カスタムリソース定義 (CRD) の名前空間で実行されます。
tkn pac
CLI ツールを使用して、パイプライン実行を確認できます。
最後のパイプライン実行を追跡するには、以下の例を使用します。
$ tkn pac logs -n <my-pipeline-ci> -L 1
- 1
my-pipeline-ci
はRepository
CRD の namespace です。
任意のパイプライン実行を対話的に行うには、以下の例を使用します。
$ tkn pac logs -n <my-pipeline-ci> 1
- 1
my-pipeline-ci
はRepository
CRD の namespace です。最後のパイプライン実行以外のパイプライン実行を表示する必要がある場合は、tkn pac logs
コマンドを使用して、リポジトリーにアタッチされたPipelineRun
を選択できます。
GitHub アプリケーションで Pipelines as Code を設定している場合に、Pipelines as Code は GitHub アプリケーションの Checks タブで URL を Post します。URL をクリックし、パイプラインの実行をたどることができます。
6.3. Pipelines as Code を使用したパイプライン実行の再開またはキャンセル
ブランチへの新しいコミットの送信やプルリクエストの発行など、イベントなしでパイプラインの実行を再開またはキャンセルできます。すべてのパイプライン実行を再開するには、GitHub アプリの Re-run all checks 機能を使用します。
すべてまたは特定のパイプラインの実行を再開するには、次のコメントを使用します。
-
/test
コメントおよび/retest
コメントはすべてのパイプラインの実行を再開します。 -
/test <pipeline_run_name>
および/retest <pipeline_run_name>
コメントは、特定のパイプラインの実行を開始または再開します。このコマンドを使用すると、このパイプライン実行のイベントによってトリガーされたかどうかに関係なく、リポジトリー上の Pipelines as Code パイプライン実行を開始できます。
すべてまたは特定のパイプラインの実行をキャンセルするには、次のコメントを使用します。
-
/cancel
コメントは、すべてのパイプライン実行をキャンセルします。 -
/cancel <pipeline_run_name>
コメントは、特定のパイプラインの実行をキャンセルします。
コメントの結果は、GitHub アプリケーションの Checks タブに表示されます。
コメントの作成者が次のいずれかの要件を満たしている場合にのみ、コメントはパイプラインの実行を開始、再開、またはキャンセルします。
- 作成者がリポジトリーの所有者である。
- 作成者がリポジトリーのコラボレーターである。
- 作成者がリポジトリーの組織のパブリックメンバーである。
-
コメントの作成者が Kubernetes ドキュメント で定義されているように、リポジトリーのルートにある
OWNERS
ファイルのapprovers
またはreviewers
のセクションにリストされている。Pipelines as Code はOWNERS
およびOWNERS_ALIASES
ファイルの仕様をサポートします。OWNERS
ファイルに フィルター セクションが含まれている場合、Pipelines as Code は approvers と reviewers を.*
フィルターに対してのみ照合します。
コメントを使用して、イベントに一致しないパイプライン実行を開始することは、テクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品サポートのサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではない場合があります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
手順
- プルリクエストを対象にしており、GitHub アプリを使用している場合は、Checks タブに移動して Re-run all checks をクリックします。
プルリクエストまたはマージリクエストを対象にする場合は、プルリクエスト内のコメントを使用します。
すべてのパイプラインの実行をキャンセルするコメントの例
This is a comment inside a pull request. /cancel
プッシュリクエストを対象とする場合は、コミットメッセージ内にコメントを含めます。
注記この機能は、GitHub プロバイダーのみでサポートされています。
- GitHub リポジトリーに移動します。
- Commits セクションをクリックします。
- パイプライン実行を再開するコミットをクリックします。
コメントを追加する行番号をクリックします。
特定のパイプラインの実行を開始または再開するコメントの例
This is a comment inside a commit. /retest example_pipeline_run
注記プッシュリクエスト内の複数のブランチに存在するコミットに対してコマンドを実行すると、最新のコミットを持つブランチが使用されます。
これにより、次の 2 つの状況が発生します。
-
/test
など、引数を指定せずにコミットでコマンドを実行すると、テストはmain
ブランチで自動的に実行されます。 -
/test branch:user-branch
などのブランチ仕様を含めると、user-branch
ブランチのコンテキストを使用して、コメントが配置されているコミットでテストが実行されます。
-
6.4. Pipelines as Code を使用したパイプライン実行ステータスの監視
コンテキストおよびサポートされるツールに応じて、パイプライン実行のステータスをさまざまな方法で監視できます。
GitHub アプリケーションのステータス
パイプラインの実行が完了すると、チェック タブにステータスが追加され、パイプラインの各タスクにかかった時間に関する情報少しと、tkn pipelinerun describe
コマンドの出力が表示されます。
ログエラーのスニペット
Pipelines as Code がパイプラインのタスクの 1 つでエラーを検出すると、最初に失敗したタスクのタスク内訳の最後の 3 行で構成される小さなスニペットが表示されます。
Pipelines as Code は、パイプラインの実行を調べて秘密の値を隠し文字に置き換えることで、シークレットの漏洩を回避します。ただし、Pipelines as Code は、ワークスペースおよび envFrom ソースからのシークレットを非表示にできません。
ログエラースニペットのアノテーション
TektonConfig
カスタムリソースの pipelinesAsCode.settings
仕様で、error-detection-from-container-logs
パラメーターを true
に設定できます。この場合、Pipelines as Code はコンテナーログからエラーを検出し、エラーが発生したプルリクエストにアノテーションとして追加します。
ログエラースニペットへのアノテーションの追加は、テクノロジープレビューのみの機能です。テクノロジープレビュー機能は、Red Hat 製品のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行いフィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
現在、Pipelines as Code は、エラーが次の形式の makefile
または grep
出力のように見える単純なケースのみをサポートしています。
<filename>:<line>:<column>: <error message>
error-detection-simple-regexp
パラメーターを使用して、エラーの検出に使用される正規表現をカスタマイズできます。正規表現は名前付きグループを使用して、マッチングを柔軟に指定できるようになります。一致する必要があるグループは、filename
、line
、および error
です。デフォルトの正規表現の Pipelines as Code config map を表示できます。
デフォルトでは、Pipelines as Code はコンテナーログの最後の 50 行のみをスキャンします。error-detection-max-number-of-lines
フィールドでこの値を増やすか、-1
を設定して行数を無制限にすることができます。ただし、このような設定では、ウォッチャーのメモリー使用量が増加する可能性があります。
Webhook のステータス
Webhook の場合、イベントがプルリクエストの場合、ステータスはプルまたはマージリクエストのコメントとして追加されます。
失敗
namespace が Repository
カスタムリソース定義 (CRD) に一致する場合に、Pipelines as Code は namespace 内の Kubernetes イベントにその失敗ログメッセージを出力します。
Repository CRD に関連付けられたステータス
パイプライン実行の最後の 5 つのステータスメッセージは、Repository
カスタムリソース内に保存されます。
$ oc get repo -n <pipelines-as-code-ci>
NAME URL NAMESPACE SUCCEEDED REASON STARTTIME COMPLETIONTIME pipelines-as-code-ci https://github.com/openshift-pipelines/pipelines-as-code pipelines-as-code-ci True Succeeded 59m 56m
tkn pac describe
コマンドを使用すると、リポジトリーおよびそのメタデータに関連付けられた実行のステータスを抽出できます。
通知
Pipelines as Code は通知を管理しません。通知が必要な場合は、パイプラインの 最後
の機能を使用します。
関連情報
6.5. Pipelines as Code を使用したパイプライン実行のクリーンアップ
ユーザー namespace には多数のパイプラインの実行があります。max-keep-runs
アノテーションを設定することで、イベントに一致するパイプライン実行を限られた数だけ保持するように Pipelines as Code を設定できます。以下に例を示します。
...
pipelinesascode.tekton.dev/max-keep-runs: "<max_number>" 1
...
- 1
- Pipelines as Code は、正常な実行の終了直後にクリーンアップを開始し、アノテーションを使用して設定されたパイプライン実行の最大数のみを保持します。注記
- コードとしてのパイプラインは、実行中のパイプラインのクリーニングをスキップしますが、ステータスが不明のパイプラインの実行をクリーンアップします。
- Pipelines as Code は、失敗したプルリクエストのクリーニングをスキップします。
6.6. Pipelines as Code での受信 Webhook の使用
受信 Webhook URL と共有シークレットを使用して、リポジトリーでパイプラインの実行を開始できます。
受信 Webhook を使用するには、Repository
カスタムリソース定義 (CRD) の spec
セクション内で次のように指定します。
- Pipelines as Code が一致する受信 Webhook URL。
Git プロバイダーおよびユーザートークン。現時点で、Pipelines as Code は
github
、gitlab
、およびbitbucket-cloud
をサポートします。注記GitHub アプリケーションのコンテキストで受信 Webhook URL を使用する場合は、トークンを指定する必要があります。
- 受信 Webhook URL のターゲットブランチおよびシークレット。
例: 受信 Webhook のあるリポジトリー
CRD
apiVersion: "pipelinesascode.tekton.dev/v1alpha1" kind: Repository metadata: name: repo namespace: ns spec: url: "https://github.com/owner/repo" git_provider: type: github secret: name: "owner-token" incoming: - targets: - main secret: name: repo-incoming-secret type: webhook-url
例: 受信 Webhook のリポジトリーンのシークレット
apiVersion: v1 kind: Secret metadata: name: repo-incoming-secret namespace: ns type: Opaque stringData: secret: <very-secure-shared-secret>
Git リポジトリーの .tekton
ディレクトリーにあるパイプライン実行をトリガーするには、以下のコマンドを使用します。
$ curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secret&repository=repo&branch=main&pipelinerun=target_pipelinerun'
Pipelines as Code は受信 URL を照合し、それを push
イベントとして扱います。ただし、Pipelines as Code は、このコマンドによってトリガーされたパイプライン実行のステータスを報告しません。
レポートまたは通知を取得するには、finally
タスクを使用してこれをパイプラインに直接追加します。または、tkn pac
CLI ツールを使用して Repository
CRD を検査できます。
6.7. 関連情報
第7章 Pipelines as Code のコマンドリファレンス
tkn pac
CLI ツールを使用して、パイプラインをコードとして制御できます。TektonConfig
カスタムリソースを使用して Pipelines as Code のロギングを設定し、oc
コマンドを使用して Pipelines as Code を表示することもできます。
7.1. Pipelines as Code のコマンドリファレンス
tkn pac
CLI ツールは、以下の機能を提供します。
- ブートストラップ Pipelines as Code のインストールおよび設定。
- 新規 Pipelines as Code リポジトリーの作成。
- すべての Pipeline as Code リポジトリーをリスト表示。
- Pipeline as Code リポジトリーおよび関連付けられた実行の記述。
- 使用を開始するための単純なパイプライン実行の生成。
- Pipelines as Code によって実行されたかのようにパイプラインの実行を解決。
アプリケーションのソースコードが含まれる Git リポジトリーに変更を加える必要がないように、テストおよび実験用に機能に対応するコマンドを使用することができます。
7.1.1. 基本的な構文
$ tkn pac [command or options] [arguments]
7.1.2. グローバルオプション
$ tkn pac --help
7.1.3. ユーティリティーコマンド
7.1.3.1. bootstrap
コマンド | 説明 |
---|---|
| GitHub および GitHub Enterprise などのサービスプロバイダーをホストする Git リポジトリーの Pipelines as Code をインストールおよび設定します。 |
| Pipelines as Code のナイトリービルドをインストールします。 |
| OpenShift ルートの URL をオーバーライドします。
デフォルトでは、 OpenShift Container Platform クラスターがない場合、受信エンドポイントをポイントするパブリック URL の入力を要求します。 |
|
GitHub アプリケーションとシークレットを |
7.1.3.2. リポジトリー
コマンド | 説明 |
---|---|
| パイプライン実行テンプレートに基づいて、新規 Pipelines as Code リポジトリーおよび namespace を作成します。 |
| すべての Pipelines as Code リポジトリーとして一覧表示し、関連する実行の最後のステータスを表示します。 |
| Pipelines as Code リポジトリーおよび関連する実行を記述します。 |
7.1.3.3. generate
コマンド | 説明 |
---|---|
| 単純なパイプライン実行を生成します。 ソースコードが含まれるディレクトリーから実行すると、現在の Git 情報を自動的に検出します。 さらに、基本的な言語検出機能を使用して、言語に応じてさらにタスクを追加します。
たとえば、リポジトリーのルートで |
7.1.3.4. resolve
コマンド | 説明 |
---|---|
| サービスで Pipelines as Code により所有されているかのようにパイプライン実行を行います。 |
|
ローカルマシンで実行中の Kubernetes インストールと組み合わせて、新しいコミットを生成せずにパイプライン実行を確認できます。 ソースコードリポジトリーからコマンドを実行すると、現在の Git 情報を検出し、現在のリビジョンやブランチなどのパラメーターを自動的に解決しようとします。 |
| Git リポジトリーからのデフォルトのパラメーター値をオーバーライドして、パイプライン実行を行います。
|
7.2. Pipelines as Code ロギングの設定
TektonConfig
カスタムリソース (CR) の pac-config-logging
config map を編集することで、Pipelines as Code ロギングを設定できます。
前提条件
- クラスターに Pipelines as Code がインストールされている。
手順
- Web コンソールの Administrator パースペクティブで、Administration → CustomResourceDefinitions に移動します。
-
Search by name ボックスを使用して、
tektonconfigs.operator.tekton.dev
カスタムリソース定義 (CRD) を検索し、TektonConfig をクリックして CRD Details ページを表示します。 - Instances タブをクリックします。
-
config インスタンスをクリックして、
TektonConfig
CR の詳細を表示します。 - YAML タブをクリックします。
要件に応じて、
.options.configMaps.pac-config-logging.data
のloglevel.
フォールドを編集します。Pipelines as Code のログレベルフィールドが
warn
に設定されているTektonConfig
CR の例apiVersion: operator.tekton.dev/v1alpha1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: options: configMaps: pac-config-logging: data: loglevel.pac-watcher: warn 1 loglevel.pipelines-as-code-webhook: warn 2 loglevel.pipelinesascode: warn 3 zap-logger-config: | { "level": "info", "development": false, "sampling": { "initial": 100, "thereafter": 100 }, "outputPaths": ["stdout"], "errorOutputPaths": ["stderr"], "encoding": "json", "encoderConfig": { "timeKey": "ts", "levelKey": "level", "nameKey": "logger", "callerKey": "caller", "messageKey": "msg", "stacktraceKey": "stacktrace", "lineEnding": "", "levelEncoder": "", "timeEncoder": "iso8601", "durationEncoder": "", "callerEncoder": "" } }
オプション:
.options.deployments
フィールドで各コンポーネントの.env.value
を変更して、Pipelines as Code コンポーネントのカスタムロギング config map を作成します。以下の例はcustom-pac-config-logging
というカスタム config map を使用した設定を示しています。Pipelines as Code カスタムロギング config map を使用した
TektonConfig
CR の例apiVersion: operator.tekton.dev/v1alpha1 kind: TektonConfig metadata: name: config spec: platforms: openshift: pipelinesAsCode: enable: true options: configMaps: custom-pac-config-logging: data: loglevel.pac-watcher: warn loglevel.pipelines-as-code-webhook: warn loglevel.pipelinesascode: warn zap-logger-config: | { "level": "info", "development": false, "sampling": { "initial": 100, "thereafter": 100 }, "outputPaths": ["stdout"], "errorOutputPaths": ["stderr"], "encoding": "json", "encoderConfig": { "timeKey": "ts", "levelKey": "level", "nameKey": "logger", "callerKey": "caller", "messageKey": "msg", "stacktraceKey": "stacktrace", "lineEnding": "", "levelEncoder": "", "timeEncoder": "iso8601", "durationEncoder": "", "callerEncoder": "" } } deployments: pipelines-as-code-controller: spec: template: spec: containers: - name: pac-controller env: - name: CONFIG_LOGGING_NAME value: custom-pac-config-logging pipelines-as-code-watcher: spec: template: spec: containers: - name: pac-watcher env: - name: CONFIG_LOGGING_NAME value: custom-pac-config-logging pipelines-as-code-webhook: spec: template: spec: containers: - name: pac-webhook env: - name: CONFIG_LOGGING_NAME value: custom-pac-config-logging
7.3. namespace ごとにパイプラインをコードログとして分割する
コードとしてのパイプラインのログには、ログをフィルタリングしたり、特定の名前空間ごとにログを分割したりできるようにする名前空間情報が含まれています。たとえば、mynamespace
namespace に関連する Pipelines as Code ログを表示するには、以下のコマンドを入力します。
$ oc logs pipelines-as-code-controller-<unique-id> -n openshift-pipelines | grep mynamespace 1
- 1
Pipelines-as-code-controller-<unique-id>
を、Pipelines as Code コントローラー名に置き換えます。