Pipelines as Code


Red Hat OpenShift Pipelines 1.15

Pipelines as Code の設定と使用

Red Hat OpenShift Documentation Team

概要

このドキュメントでは、Git ソースコードリポジトリーの一部としてパイプラインテンプレートを定義できるようにする OpenShift Pipelines のサブシステムである 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 カスタムリソースで次のパラメーターを設定できます。

表2.1 Pipelines as Code 設定のカスタマイズ
パラメーター説明デフォルト

application-name

アプリケーションの名前。たとえば、GitHub Checks ラベルに表示される名前です。

"Pipelines as Code CI"

secret-auto-create

GitHub アプリケーションで生成されたトークンを使用してシークレットを自動的に作成するかどうかを示します。このシークレットは、プライベートリポジトリーで使用できます。

enabled

remote-tasks

有効にすると、パイプライン実行アノテーションからのリモートタスクを許可します。

enabled

hub-url

Tekton Hub API のベース URL。

https://hub.tekton.dev/

hub-catalog-name

Tekton Hub のカタログ名。

tekton

tekton-dashboard-url

Tekton Hub ダッシュボードの URL。Pipelines as Code は、この URL を使用して、Tekton Hub ダッシュボードに PipelineRun URL を生成します。

NA

bitbucket-cloud-check-source-ip

パブリック Bitbucket の IP 範囲をクエリーしてサービス要求を保護するかどうかを示します。パラメーターのデフォルト値を変更すると、セキュリティーの問題が発生する可能性があります。

enabled

bitbucket-cloud-additional-source-ip

コンマで区切られた追加の IP 範囲またはネットワークのセットを提供するかどうかを示します。

NA

max-keep-run-upper-limit

パイプライン実行の max-keep-run 値の上限。

NA

default-max-keep-runs

パイプライン実行の max-keep-run 値のデフォルトの制限。定義されている場合、値は max-keep-run アノテーションを持たないすべてのパイプライン実行に適用されます。

NA

auto-configure-new-github-repo

新しい GitHub リポジトリーを自動的に設定します。Pipelines as Code は namespace を設定し、リポジトリーのカスタムリソースを作成します。このパラメーターは、GitHub アプリケーションでのみサポートされています。

disabled

auto-configure-repo-namespace-template

auto-configure-new-github-repo が有効になっている場合は、新しいリポジトリーの namespace を自動的に生成するようにテンプレートを設定します。

{repo_name}-pipelines

error-log-snippet

失敗したタスク (パイプラインにエラーがある) のログスニペットの表示を有効または無効にします。パイプラインからのデータ漏えいの場合は、このパラメーターを無効にすることができます。

true

error-detection-from-container-logs

エラーメッセージを検出し、プルリクエストのアノテーションとして公開するためのコンテナーログの検査を有効または無効にします。この設定は、GitHub アプリを使用している場合にのみ適用されます。

true

error-detection-max-number-of-lines

エラーメッセージを検索するためにコンテナーログ内で検査される最大行数。無制限の行数を検査するには、-1 に設定します。

50

secret-github-app-token-scoped

true に設定すると、Pipelines as Code が GitHub アプリを使用して生成する GitHub アクセストークンのスコープは、Pipelines as Code がパイプライン定義を取得するリポジトリーのみに限定されます。false に設定すると、TektonConfig カスタムリソースと Repository カスタムリソースの両方を使用して、トークンのスコープを追加のリポジトリーに設定できます。

true

secret-github-app-scope-extra-repos

生成された GitHub アクセストークンのスコープを設定するための追加のリポジトリー。

 

2.4. 追加の GitHub アプリケーションをサポートするための、追加の Pipelines as Code コントローラー設定

デフォルトでは、Pipelines as Code を設定して、1 つの GitHub アプリケーションと対話できます。場合によっては、複数の GitHub アプリケーションを使用する必要があることがあります。たとえば、異なる GitHub アカウントや、GitHub Enterprise や GitHub SaaS などの異なる GitHub インスタンスを使用する必要がある場合などです。複数の GitHub アプリケーションを使用する場合は、追加の GitHub アプリケーションごとに追加の Pipelines as Code コントローラーを設定する必要があります。

手順

  1. 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. オプション: 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 をインストールしている。

手順

  1. 管理者パースペクティブで、ナビゲーションペインを使用して Pipelines に移動します。
  2. Pipelines ページで GitHub アプリのセットアップ をクリックします。
  3. GitHub のアプリケーション名を入力します。例: pipelines-ci-clustername-testui
  4. Setup をクリックします。
  5. ブラウザーでプロンプトが表示されたら、Git パスワードを入力します。
  6. Create GitHub App for <username> をクリックします。ここで、<username> は GitHub ユーザー名です。

検証

GitHub App の作成に成功すると、OpenShift Container Platform Web コンソールが開き、アプリケーションの詳細を表示します。

Github アプリの詳細

GitHub App の詳細は、openShift-pipelines namespace にシークレットとして保存されます。

GitHub アプリケーションに関連付けられている名前、リンク、シークレットなどの詳細を表示するには、パイプライン に移動し、GitHub アプリの表示 をクリックします。

3.1.3. GitHub アプリケーションの手動設定および Pipelines as Code のシークレットの作成

GitHub ユーザーインターフェイスを使用して GitHub アプリケーションを作成できます。次に、GitHub アプリケーションに接続するために Pipelines as Code を設定するシークレットを作成する必要があります。

追加の GitHub アプリケーションをサポートするために追加の Pipelines as Code コントローラーを作成した場合は、追加のコントローラーに対してこの手順を使用する必要があります。

手順

  1. GitHub アカウントにサインインします。
  2. GitHub メニューで、SettingsDeveloper settingsGitHub Apps を選択し、New GitHub App をクリックします。
  3. 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
  4. Repository permissions セクションで次の項目を選択します。

    • Checks: Read & Write
    • Contents: Read & Write
    • Issues: Read & Write
    • Metadata: Read-only
    • Pull request: Read & Write
  5. Organization permissions セクションで次の項目を選択します。

    • Members: Read-only
    • Plan: Read-only
  6. 次のイベントにサブスクライブします。

    • Check run
    • Check suite
    • Commit comment
    • Issue comment
    • Pull request
    • プッシュ
  7. Create GitHub App をクリックします。
  8. 新たに作成された GitHub App の Details ページで、上部に表示される App ID を書き留めます。
  9. Private keys セクションで、Generate Private key をクリックして GitHub アプリケーションの秘密鍵を自動的に生成およびダウンロードします。今後の参照や使用のために秘密鍵を安全に保管します。
  10. 作成したアプリを Pipelines as Code で使用するリポジトリーにインストールします。
  11. 次のコマンドを入力して、新しく作成された 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
    1
    追加の GitHub アプリケーションをサポートするために追加の Pipelines as Code コントローラーを作成し、追加のコントローラー用にアプリケーションを設定する場合は、pipelines-as-code-secret を、コントローラーの secretName パラメーターで設定した名前に置き換えます。
    2
    GitHub アプリケーションの設定時にダウンロードした秘密鍵へのパス。
    3
    GitHub アプリケーションの App ID
    4
    GitHub アプリケーションの作成時に提供された Webhook シークレット。
注記

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 に存在するリポジトリーのリストに拡張できます。この設定を設定するために管理者権限は必要ありません。

手順

  1. TektonConfig カスタムリソース (CR) の pipelinesAsCode.settings 仕様で、secret-github-app-token-scoped パラメーターを false に設定します。この設定により、GitHub トークンのスコープを、グローバルおよびリポジトリーレベルの設定にリストされているプライベートおよびパブリックリポジトリーに設定できるようになります。
  2. 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"
  3. 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/projectowner1/project1owner2/project2owner3/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 スコープを追加します。

手順

  1. 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 を 手動 で作成するには、以下の手順を実行します。

      1. OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。

        $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
      2. GitHub リポジトリーまたは組織で、以下の手順を実行します。

        1. Settings -> Webhooks に移動し、Add webhook をクリックします。
        2. Payload URL を Pipelines as Code コントローラーのパブリック URL に設定します。
        3. コンテンツタイプを application/json として選択します。
        4. Webhook シークレットを追加し、別の場所に書き留めます。openssl がローカルマシンにインストールされた状態で、ランダムなシークレットを生成します。

          $ openssl rand -hex 20
        5. Let me select individual events をクリックし、Commit commentsIssue commentsPull request、および Pushes のイベントを選択します。
        6. Add webhook をクリックします。
      3. 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>"
      4. Repository CR を作成します。

        例: Repository CR

        apiVersion: "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 にあることを前提としています。

  2. オプション: 既存の Repository CR の場合、複数の GitHub Webhook シークレットを追加するか、削除されたシークレットの代わりを提供します。

    1. 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.

    2. 既存の OpenShift Secret オブジェクトの webhook.secret キーを更新します。
  3. オプション: 既存の 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 トークンを更新します。

      1. Repository CR でシークレットの名前を見つけます。

        apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
        kind: Repository
        metadata:
          name: my-repo
          namespace: target-namespace
        spec:
        # ...
          git_provider:
            secret:
              name: "github-webhook-config"
        # ...
      2. 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 のコメントとして表示します。

手順

  1. 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 を 手動 で作成するには、以下の手順を実行します。

      1. OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。

        $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
      2. GitLab プロジェクトで、以下の手順を実行します。

        1. 左側のサイドバーを使用して Settings -> Webhooks に移動します。
        2. URL を Pipelines as Code コントローラーのパブリック URL に設定します。
        3. Webhook シークレットを追加し、別の場所に書き留めます。openssl がローカルマシンにインストールされた状態で、ランダムなシークレットを生成します。

          $ openssl rand -hex 20
        4. Let me select individual events をクリックし、Commit commentsIssue commentsPull request、および Pushes のイベントを選択します。
        5. Save changes をクリックします。
      3. 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>"
      4. Repository CR を作成します。

        例: Repository CR

        apiVersion: "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 にあることを前提としています。
  2. オプション: 既存の Repository CR の場合、複数の GitLab Webhook シークレットを追加するか、削除されたシークレットの代わりを提供します。

    1. 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.

    2. 既存の OpenShift Secret オブジェクトの webhook.secret キーを更新します。
  3. オプション: 既存の 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 トークンを更新します。

      1. Repository CR でシークレットの名前を見つけます。

        ...
        spec:
          git_provider:
            secret:
              name: "gitlab-webhook-config"
        ...
      2. 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:ReadWrite パーミッションをトークンに追加します。
        • 生成されたら、パスワードまたはトークンのコピーを別の場所に保存します。

手順

  1. 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 を 手動 で作成するには、以下の手順を実行します。

      1. OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。

        $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
      2. Bitbucket Cloud で、以下の手順を実行します。

        1. Bitbucket Cloud リポジトリーの左側のナビゲーションペインを使用して Repository settings -> Webhooks に移動し、Add webhook をクリックします。
        2. Title を設定します。たとえば、"Pipelines as Code" です。
        3. URL を Pipelines as Code コントローラーのパブリック URL に設定します。
        4. Repository: PushPull Request: CreatedPull Request: Updated、および Pull Request: Comment created のイベントを選択します。
        5. Save をクリックします。
      3. OpenShift クラスターで、ターゲット namespace に app パスワードを使用して Secret オブジェクトを作成します。

        $ oc -n target-namespace create secret generic bitbucket-cloud-token \
          --from-literal provider.token="<BITBUCKET_APP_PASSWORD>"
      4. Repository CR を作成します。

        例: Repository CR

        apiVersion: "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

        1
        所有者ファイルの ACCOUNT_ID からしかユーザーの参照はできません。
        2
        Pipelines as Code は、git_provider.secret 仕様で参照され、Repository CR が同じ namespace にあることを前提としています。
    注記
    • 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 パラメーターにコンマ区切りの値として追加します。
  2. オプション: 既存の Repository CR の場合は、複数の Bitbucket Cloud Webhook シークレットを追加するか、削除されたシークレットの代わりに指定します。

    1. 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 に存在する場合のみです。

    2. 既存の OpenShift Secret オブジェクトの webhook.secret キーを更新します。
  3. オプション: 既存の 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 を更新します。

      1. Repository CR でシークレットの名前を見つけます。

        ...
        spec:
          git_provider:
            user: "<BITBUCKET_USERNAME>"
            secret:
              name: "bitbucket-cloud-token"
              key: "provider.token"
        ...
      2. 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 権限が必要です。
    • トークンには、プルリクエストでフォークされたリポジトリーへのアクセスが必要です。

手順

  1. OpenShift クラスターで、Pipelines as Code コントローラーの公開 URL を抽出します。

    $ echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}')
  2. Bitbucket Server で、以下の手順を実行します。

    1. Bitbucket Data Center リポジトリーの左側のナビゲーションペインを使用して Repository settings -> Webhooks に移動し、Add webhook をクリックします。
    2. Title を設定します。たとえば、"Pipelines as Code" です。
    3. URL を Pipelines as Code コントローラーのパブリック URL に設定します。
    4. Webhook シークレットを追加し、そのコピーを別の場所に保存します。openssl をローカルマシンにインストールしている場合は、以下のコマンドを使用してランダムなシークレットを生成します。

      $ openssl rand -hex 20
    5. 以下のイベントを選択します。

      • Repository: Push
      • Repository: Modified
      • Pull Request: Opened
      • Pull Request: Source branch updated
      • Pull Request: Comment added
    6. Save をクリックします。
  3. 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>"
  4. Repository CR を作成します。

    例: Repository CR

    apiVersion: "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

    1
    /api/v1.0 接尾辞のない正しい Bitbucket Server API URL があることを確認します。通常、デフォルトのインストールには /rest 接尾辞があります。
    2
    所有者ファイルの ACCOUNT_ID からしかユーザーの参照はできません。
    3
    Pipelines as Code は、git_provider.secret 仕様で参照され、Repository CR が同じ namespace にあることを前提としています。
    注記

    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_limit1 のプルリクエストを作成する場合、すべてのパイプライン実行はアルファベット順に実行されます。常に 1 つのパイプライン実行のみが running 状態にあり、残りはキューに入れられます。

4.4. パイプライン定義のソースブランチの変更

デフォルトでは、プッシュイベントまたはプルリクエストイベントを処理するときに、Pipelines as Code はイベントをトリガーしたブランチからパイプライン定義をフェッチします。Repository カスタムリソース定義 (CRD) の pipelinerun_provenance 設定を使用して、Git リポジトリープロバイダーに設定されているデフォルトブランチ (mainmaster、または 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 は、以下の方法でカスタムパラメーターを解析して使用します。

  • valuesecretRef が定義されている場合、Pipelines as Code は value を使用します。
  • params セクションに name がない場合、Pipelines as Code はパラメーターを解析しません。
  • 同じ nameparams が複数ある場合、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-ciRepository CRD の namespace です。
  • 任意のパイプライン実行を対話的に行うには、以下の例を使用します。

    $ tkn pac logs -n <my-pipeline-ci> 1
    1
    my-pipeline-ciRepository 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 プロバイダーのみでサポートされています。

    1. GitHub リポジトリーに移動します。
    2. Commits セクションをクリックします。
    3. パイプライン実行を再開するコミットをクリックします。
    4. コメントを追加する行番号をクリックします。

      特定のパイプラインの実行を開始または再開するコメントの例

      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 パラメーターを使用して、エラーの検出に使用される正規表現をカスタマイズできます。正規表現は名前付きグループを使用して、マッチングを柔軟に指定できるようになります。一致する必要があるグループは、filenameline、および 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 は githubgitlab、および 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
表7.1 ブートストラップ Pipelines as Code のインストールおよび設定
コマンド説明

tkn pac bootstrap

GitHub および GitHub Enterprise などのサービスプロバイダーをホストする Git リポジトリーの Pipelines as Code をインストールおよび設定します。

tkn pac bootstrap --nightly

Pipelines as Code のナイトリービルドをインストールします。

tkn pac bootstrap --route-url <public_url_to_ingress_spec>

OpenShift ルートの URL をオーバーライドします。

デフォルトでは、tkn pac bootstrap は OpenShift ルートを検出します。これは、Pipelines as Code コントローラーサービスに自動的に関連付けられます。

OpenShift Container Platform クラスターがない場合、受信エンドポイントをポイントするパブリック URL の入力を要求します。

tkn pac bootstrap github-app

GitHub アプリケーションとシークレットを openshift-pipelines namespace に作成します。

7.1.3.2. リポジトリー
表7.2 Pipelines as Code リポジトリーの管理
コマンド説明

tkn pac create repository

パイプライン実行テンプレートに基づいて、新規 Pipelines as Code リポジトリーおよび namespace を作成します。

tkn pac list

すべての Pipelines as Code リポジトリーとして一覧表示し、関連する実行の最後のステータスを表示します。

tkn pac repo describe

Pipelines as Code リポジトリーおよび関連する実行を記述します。

7.1.3.3. generate
表7.3 Pipelines as Code を使用したパイプライン実行の生成
コマンド説明

tkn pac generate

単純なパイプライン実行を生成します。

ソースコードが含まれるディレクトリーから実行すると、現在の Git 情報を自動的に検出します。

さらに、基本的な言語検出機能を使用して、言語に応じてさらにタスクを追加します。

たとえば、リポジトリーのルートで setup.py ファイルを検出すると、pylint タスク が自動的に生成されたパイプライン実行に追加されます。

7.1.3.4. resolve
表7.4 Pipelines as Code を使用したパイプライン実行の解決および実行
コマンド説明

tkn pac resolve

サービスで Pipelines as Code により所有されているかのようにパイプライン実行を行います。

tkn pac resolve -f .tekton/pull-request.yaml | oc apply -f -

.tekton/pull-request.yaml のテンプレートを使用するライブのパイプライン実行のステータスを表示します。

ローカルマシンで実行中の Kubernetes インストールと組み合わせて、新しいコミットを生成せずにパイプライン実行を確認できます。

ソースコードリポジトリーからコマンドを実行すると、現在の Git 情報を検出し、現在のリビジョンやブランチなどのパラメーターを自動的に解決しようとします。

tkn pac resolve -f .tekton/pr.yaml -p revision=main -p repo_name=<repository_name>

Git リポジトリーからのデフォルトのパラメーター値をオーバーライドして、パイプライン実行を行います。

-f オプションはディレクトリーパスを受け入れ、そのディレクトリー内のすべての .yaml または .yml ファイルに tkn pac resolve コマンドを適用することもできます。1 つのコマンドで -f フラグを複数回使用することもできます。

-p オプションを使用してパラメーター値を指定することで、Git リポジトリーから収集したデフォルト情報をオーバーライドできます。たとえば、Git ブランチをリビジョンおよび異なるリポジトリー名として使用できます。

7.2. Pipelines as Code ロギングの設定

TektonConfig カスタムリソース (CR) の pac-config-logging config map を編集することで、Pipelines as Code ロギングを設定できます。

前提条件

  • クラスターに Pipelines as Code がインストールされている。

手順

  1. Web コンソールの Administrator パースペクティブで、AdministrationCustomResourceDefinitions に移動します。
  2. Search by name ボックスを使用して、tektonconfigs.operator.tekton.dev カスタムリソース定義 (CRD) を検索し、TektonConfig をクリックして CRD Details ページを表示します。
  3. Instances タブをクリックします。
  4. config インスタンスをクリックして、TektonConfig CR の詳細を表示します。
  5. YAML タブをクリックします。
  6. 要件に応じて、.options.configMaps.pac-config-logging.dataloglevel. フォールドを編集します。

    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": ""
                        }
                      }

    1
    Pipelines-as-code-watcher コンポーネントのログレベル。
    2
    Pipelines-as-code-Webhook コンポーネントのログレベル。
    3
    Pipelines-as-code-controller コンポーネントのログレベル。
  7. オプション: .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 コントローラー名に置き換えます。

7.4. 関連情報

法律上の通知

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.