4.8. Pipelines as Code の使用

Pipelines as Code を使用すると、クラスター管理者と必要な権限を持つユーザーは、パイプラインテンプレートをソースコード Git リポジトリーの一部として定義できます。設定された Git リポジトリーのソースコードプッシュまたはプルリクエストによってトリガーされると、この機能はパイプラインを実行し、ステータスを報告します。

4.8.1. 主な特長

Pipelines as Code は、次の機能をサポートしています。

  • プルリクエストのステータスおよび Git リポジトリーをホストするプラットフォームの制御。
  • GitHub は API を確認し、パイプライン実行のステータスを設定します (再チェックを含む)。
  • GitHub のプルリクエストとコミットイベント。
  • /retest などのコメントでリクエストアクションをプルします。
  • Git イベントのフィルタリング、およびイベントごとの個別のパイプライン。
  • ローカルタスク、Tekton Hub、およびリモート URL を含むパイプラインの自動タスク解決。
  • GitHub blob およびオブジェクト API を使用した設定の取得。
  • GitHub 組織を介して、または Prow スタイルの OWNER ファイルを使用したアクセス制御リスト (ACL)。
  • ブートストラップおよび Pipelines as Code リポジトリーを管理するための tkn pac CLI プラグイン。
  • GitHub App、GitHub Webhook、Bitbucket Server、および Bitbucket Cloud のサポート。

4.8.2. OpenShift Container Platform への Pipelines as Code のインストール

Pipelines as Code は、Red Hat OpenShift Pipelines Operator のインストール時にデフォルトでインストールされます。Pipelines 1.7 以降のバージョンを使用している場合は、Pipelines as Code を手動でインストールする手順を省略します。

Operator を使用して Pipelines as Code のデフォルトインストールを無効にするには、TektonConfig カスタムリソースで enable パラメーターの値を false に設定します。

...
 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 に設定します。

...
spec:
    addon:
      enablePipelinesAsCode: false
...

必要に応じて、以下のコマンドを実行できます。

$ oc patch tektonconfig config --type="merge" -p '{"spec": {"platforms": {"openshift":{"pipelinesAsCode": {"enable": true}}}}}'

4.8.3. Pipelines as Code CLI のインストール

クラスター管理者は、ローカルマシンで、またはテスト用のコンテナーとして tkn-pac および opc CLI ツールを使用できます。tkn pac および opc CLI ツールは、Red Hat OpenShift Pipelines の tkn CLI をインストールすると自動的にインストールされます。

サポート対象プラットフォーム用の tkn pac および opc バージョン 1.9.1 バイナリーをインストールできます。

4.8.4. サービスプロバイダーをホストする Git リポジトリーでの Pipelines as Code の使用

Pipelines as Code をインストールした後に、クラスター管理者はサービスプロバイダーをホストする Git リポジトリーを設定できます。現在、以下のサービスがサポートされています。

  • GitHub アプリケーション
  • GitHub Webhook
  • GitLab
  • Bitbucket Server
  • Bitbucket Cloud
注記

GitHub アプリケーションは、Pipelines as Code での使用に推奨されるサービスです。

4.8.5. GitHub アプリケーションでの Pipelines as Code の使用

GitHub アプリケーションは Red Hat OpenShift Pipeline とのインテグレーションポイントとして機能し、Git ベースのワークフローのメリットを OpenShift Pipelines にもたらします。クラスター管理者は、すべてのクラスターユーザーに単一の GitHub アプリケーションを設定できます。GitHub アプリケーションが Pipelines as Code と連携するには、GitHub アプリケーションの Webhook が GitHub イベントをリッスンする Pipelines as Code イベントリスナールート (または受信エンドポイント) をポイントするようにします。

4.8.5.1. GitHub アプリケーションの設定

クラスター管理者は、以下のコマンドを実行して GitHub アプリケーションを作成できます。

$ tkn pac bootstrap github-app

tkn pac CLI プラグインがインストールされていない場合は、GitHub アプリケーションを手動で作成できます。

手順

Pipelines as Code 用に GitHub アプリケーションを手動で作成および設定するには、以下の手順を実行します。

  1. GitHub アカウントにサインインします。
  2. 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}') を実行して見つけることができます。
    • Webhook secret: 任意のシークレット。コマンド openssl rand -hex 20 を実行してシークレットを生成することができます。
  4. 以下の リポジトリーのパーミッション を選択します。

    • チェック: 読み取り/書き込み
    • コンテンツ: 読み取り/書き込み
    • 問題: 読み取り/書き込み
    • メタデータ: 読み取り専用
    • プルリクエスト: 読み取り/書き込み
  5. 以下の 組織のパーミッション を選択します。

    • メンバー: 読み取り専用
    • プラン: 読み取り専用
  6. 以下の ユーザーパーミッション を選択します。

    • コミットコメント
    • 問題のコメント
    • プルリクエスト
    • プルリクエストのレビュー
    • プルリクエストのレビューコメント
    • プッシュ
  7. Create GitHub App をクリックします。
  8. 新たに作成された GitHub App の Details ページで、上部に表示される App ID を書き留めます。
  9. Private keys セクションで、Generate Private key をクリックして GitHub アプリケーションの秘密鍵を自動的に生成およびダウンロードします。今後の参照や使用のために秘密鍵を安全に保管します。

4.8.5.2. GitHub アプリケーションにアクセスするための Pipelines as Code の設定

新たに作成された GitHub アプリケーションにアクセスするために Pipelines as Code を設定するには、以下のコマンドを実行します。

+

$ oc -n openshift-pipelines create secret generic pipelines-as-code-secret \
        --from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \ 1
        --from-literal github-application-id="<APP_ID>" \ 2
        --from-literal webhook.secret="<WEBHOOK_SECRET>" 3
1
GitHub アプリケーションの設定時にダウンロードした秘密鍵へのパス。
2
GitHub アプリケーションの App ID
3
GitHub アプリケーションの作成時に提供された Webhook シークレット。
注記

GitHub Enterprise から設定されたヘッダーを検出し、それを GitHub Enterprise API 承認 URL に使用することで、Pipelines as Code は自動的に GitHub Enterprise と連携します。

4.8.5.3. 管理者パースペクティブでの GitHub アプリケーションの作成

クラスター管理者は、OpenShift Container Platform クラスターで GitHub アプリケーションを Pipelines as Code を使用するように設定できます。この設定により、ビルドのデプロイに必要な一連のタスクを実行できます。

前提条件

Operator Hub から Red Hat OpenShift Pipelines pipelines-1.10 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 アプリの表示 をクリックします。

4.8.6. 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 で個人アクセストークンを作成する。

    • セキュアで粒度の細かいトークンを生成するには、そのスコープを特定のリポジトリーに制限し、以下のパーミッションを付与します。

      表4.7 粒度の細かいトークンのパーミッション

      Nameアクセス

      管理

      Read-only

      メタデータ

      Read-only

      コンテンツ

      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 pipelines-as-code 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 の場合は、パーソナルアクセストークンを更新します。

    • tkn pac CLI ツールを使用してパーソナルアクセストークンを更新します。

      例: tkn pac CLI を使用したパーソナルアクセストークンの更新

      $ 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 を変更してパーソナルアクセストークンを更新します。

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

        ...
        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)\"}}"

4.8.7. GitLab での Pipelines as Code の使用

組織またはプロジェクトが優先プラットフォームとして GitLab を使用する場合は、GitLab の Webhook を使用してリポジトリーの Pipelines as Code を使用できます。

前提条件

  • Pipelines as Code がクラスターにインストールされている。
  • 承認には、GitLab のプロジェクトまたは組織のマネージャーとしてパーソナルアクセストークンを生成します。

    注記
    • 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 pipelines-as-code 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" 1
          git_provider:
            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
        現時点で、Pipelines as Code では GitLab のプライベートインスタンスは自動検出されません。このような場合には、git_provider.url 仕様の下に API URL を指定します。通常、git_provider.url 仕様を使用して API URL を手動で上書きできます。
    注記
    • 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 の場合は、パーソナルアクセストークンを更新します。

    • tkn pac CLI ツールを使用してパーソナルアクセストークンを更新します。

      例: tkn pac CLI を使用したパーソナルアクセストークンの更新

      $ 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 を変更してパーソナルアクセストークンを更新します。

      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)\"}}"

4.8.8. 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 pipelines-as-code 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 アドレスからのみ行われるようにします。

      • デフォルトの動作を無効にするには、pipelines-as-code namespace の Pipelines as Code config map で bitbucket-cloud-check-source-ip キーfalse に設定します。
      • 追加の安全な IP アドレスまたはネットワークを許可するには、pipelines-as-code namespace の Pipelines as Code config map の 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 の場合は、パーソナルアクセストークンを更新します。

    • tkn pac CLI ツールを使用してパーソナルアクセストークンを更新します。

      例: tkn pac CLI を使用したパーソナルアクセストークンの更新

      $ 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 を変更してパーソナルアクセストークンを更新します。

      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)\"}}"

4.8.9. Bitbucket サーバーでの Pipelines as Code の使用

組織またはプロジェクトが優先プラットフォームとして Bitbucket Server を使用する場合は、Bitbucket Server の Webhook でリポジトリーの Pipelines as Code を使用できます。

前提条件

  • Pipelines as Code がクラスターにインストールされている。
  • Bitbucket Server でプロジェクトのマネージャーとしてパーソナルアクセストークンを生成し、そのコピーを別の場所に保存します。

    注記
    • トークンには、PROJECT_ADMIN および REPOSITORY_ADMIN 権限が必要です。
    • トークンには、プルリクエストでフォークされたリポジトリーへのアクセスが必要です。

手順

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

    $ echo https://$(oc get route -n pipelines-as-code 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 サーバーではサポートされません。

4.8.10. 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 コンポーネントおよびワークロードの証明書を公開します。

4.8.11. Pipelines as Code での Repository CRD の使用

Repository カスタムリソース (CR) には、次の主要な機能があります。

  • URL からのイベントの処理について Pipelines as Code に通知します。
  • Pipeline 実行の namespace について Pipelines as Code に通知します。
  • Webhook メソッドを使用する場合、Git プロバイダープラットフォームに必要な API シークレット、ユーザー名、または API URL を参照します。
  • リポジトリーの最後のパイプライン実行ステータスを指定します。

tkn pac CLI またはその他の代替方法を使用して、ターゲット namespace 内に 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 CRD を作成する必要があります。これは別の namespace をターゲットにすることはできません。
  • 複数の リポジトリー CRD が同じイベントとマッチする場合には、Pipelines as Code は最も古いもののみを処理します。特定の namespace と同じにする必要がある場合は、pipelinesascode.tekton.dev/target-namespace: "<mynamespace>" アノテーションを追加します。このような明示的なターゲティングにより、悪意のあるアクターがアクセス権のない namespace でパイプラインの実行を防ぎます。

4.8.11.1. Repository CRD での同時実行制限の設定

Repository CRD の concurrency_limit 仕様を使用して、リポジトリーに対して同時に実行されるパイプライン実行の最大数を定義できます。

...
spec:
  concurrency_limit: <number>
  ...

イベントに一致する複数のパイプラインが実行される場合、パイプラインは、イベントの開始に一致するアルファベット順に実行されます。

たとえば、.tekton ディレクトリーに 3 つのパイプラインが実行され、リポジトリー設定に concurrency_limit1 のプルリクエストを作成する場合、すべてのパイプライン実行はアルファベット順に実行されます。常に 1 つのパイプライン実行のみが running 状態にあり、残りはキューに入れられます。

4.8.12. Pipelines as Code リゾルバーの使用

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 コマンドを使用します。

リモートパイプラインおよびタスクを参照することもできます。

4.8.12.1. 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
タスク定義を含むローカルファイルへの相対パス。

4.8.12.2. Pipelines as Code でのリモートパイプラインアノテーションの使用

リモートパイプラインアノテーションを使用すると、複数のリポジトリーでパイプライン定義を共有できます。

...
    pipelinesascode.tekton.dev/pipeline: "<https://git.provider/raw/pipeline.yaml>" 1
...
1
リモートパイプライン定義への URL。同じリポジトリー内のファイルの場所を指定することもできます。
注記

アノテーションを使用してパイプライン定義を 1 つだけ参照できます。

4.8.13. 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 パイプラインをマッチさせることができます。

...
  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 ブランチを対象とする プッシュ イベントとマッチさせることができます。

...
  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.\* などのタグ

高度なイベントマッチング

コードとしてのパイプラインは、高度なイベントマッチングのための 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 イベントを一致させるには、次のようにします。

    ...
      pipelinesascode.tekton.dev/on-cel-expression: |
        event == "pull_request" && target_branch == "main" && source_branch == "wip"
    ...
  • パスが変更された場合にのみパイプラインを実行するには、glob パターンで .pathChanged 接尾辞関数を使用できます。

    ...
      pipelinesascode.tekton.dev/on-cel-expression: |
        event == "pull_request" && "docs/\*.md".pathChanged() 1
    ...
    1
    docs ディレクトリー内のすべてのマークダウンファイルと一致します。
  • [DOWNSTREAM] で始まるすべてのプルリクエストとマッチさせるには、以下を実行します。

    ...
      pipelinesascode.tekton.dev/on-cel-expression: |
        event == "pull_request && event_title.startsWith("[DOWNSTREAM]")
    ...
  • pull_request イベントでパイプラインを実行し、experimental ブランチを省略するには、以下を実行します。

    ...
      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 のみがプロバイダーとしてサポートされています。

Github API 操作への一時的な GitHub App トークンの使用

GitHub API にアクセスするための Pipelines as Code によって生成された一時的なインストールトークンを使用できます。トークン値は 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 時間利用可能で、クラスターで別の設定を行わない限り、イベントの発生元のリポジトリーにスコープが設定されます。

4.8.14. Pipelines as Code を使用したパイプライン実行

デフォルト設定では、Pipelines as Code は、プルリクエストやプッシュなどの指定されたイベントがリポジトリーで発生したときに、リポジトリーのデフォルトブランチの .tekton/ ディレクトリーで実行されるすべてのパイプラインを実行します。たとえば、デフォルトのブランチで実行されるパイプラインに、アノテーション pipelinesascode.tekton.dev/on-event: "[pull_request]" がある場合に、これはプル要求イベントが発生するたびに実行されます。

プルリクエストまたはマージリクエストが発生した場合、プルリクエストの作成者が次の条件を満たしている場合、Pipelines as Code はデフォルトブランチ以外のブランチからもパイプラインを実行します。

  • 作成者はリポジトリーの所有者です。
  • 作成者は、リポジトリーのコラボレーターです。
  • 作成者はリポジトリーの組織のパブリックメンバーです。
  • プルリクエストの作成者は、リポジトリーの GitHub 設定で定義されているように、main ブランチのリポジトリールートにある OWNER ファイルに一覧表示されます。また、プルリクエストの作成者は、approvers または reviewers セクションに追加されます。たとえば、作成者が approvers セクションにリストされている場合、その作成者が発行したプルリクエストによってパイプラインの実行が開始されます。
...
  approvers:
    - approved
...

プル要求の作成者は、要件を満たす別のユーザーがプル要求で /ok-to-test をコメントして、パイプライン実行を開始できます。

パイプライン実行

パイプラインの実行は常に、イベントを生成したリポジトリーに関連付けられた Repository CRD の namespace で実行されます。

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 をクリックし、パイプラインの実行をたどることができます。

パイプライン実行の再起動

ブランチへの新しいコミットの送信やプルリクエストの発行など、イベントなしでパイプラインの実行を再開できます。GitHub アプリで、Checks タブに移動し、Re-run をクリックします。

プルまたはマージ要求をターゲットにする場合は、プル要求内で以下のコメントを使用して、すべてまたは特定のパイプライン実行を再起動します。

  • /retest コメントは、すべてのパイプラインの実行を再開します。
  • /retest <pipelinerun-name> コメントは、特定のパイプラインの実行を再開します。
  • /cancel コメントは、すべてのパイプライン実行をキャンセルします。
  • /cancel <pipelinerun-name> コメントは、特定のパイプラインの実行をキャンセルします。

コメントの結果は、GitHub アプリケーションの Checks タブに表示されます。

4.8.15. Pipelines as Code を使用したパイプライン実行ステータスの監視

コンテキストおよびサポートされるツールに応じて、パイプライン実行のステータスをさまざまな方法で監視できます。

GitHub アプリケーションのステータス

パイプラインの実行が完了すると、チェック タブにステータスが追加され、パイプラインの各タスクにかかった時間に関する情報少しと、tkn pipelinerun describe コマンドの出力が表示されます。

ログエラーのスニペット

コードとしてのパイプラインがパイプラインのタスクの 1 つでエラーを検出すると、最初に失敗したタスクのタスク内訳の最後の 3 行で設定される小さなスニペットが表示されます。

注記

Pipelines as Code は、パイプラインの実行を調べて秘密の値を隠し文字に置き換えることで、シークレットの漏洩を回避します。ただし、Pipelines as Code は、ワークスペースおよび envFrom ソースからのシークレットを非表示にできません。

ログエラースニペットのアノテーション

Pipelines as Code config map で、error-detection-from-container-logs パラメーターを true に設定すると、Pipelines as Code はコンテナーログからエラーを検出し、エラーが発生したプルリクエストにアノテーションとして追加します。

重要

この機能はテクノロジープレビューです。

現在、Pipelines as Code は、エラーが次の形式の makefile または grep 出力のように見える単純なケースのみをサポートしています。

<filename>:<line>:<column>: <error message>

error-detection-simple-regexp フィールドを使用して、エラーの検出に使用される正規表現をカスタマイズできます。正規表現は名前付きグループを使用して、マッチングを柔軟に指定できるようになります。マッチングに必要なグループは filename、line、および error です。デフォルトの正規表現の Pipelines as Code config map を表示できます。

注記

デフォルトでは、コードとしての Pipelines はコンテナーログの最後の 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 は通知を管理しません。通知が必要な場合は、パイプラインの 最後 の機能を使用します。

4.8.16. 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 ワークスペースを取得し、これを使用してプライベートリポジトリーのクローンを作成します。

Pipelines as Code config map で必要に応じて、secret-auto-create フラグを false または true の値に設定することで、この設定を変更できます。

4.8.17. 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 は、失敗したプルリクエストのクリーニングをスキップします。

4.8.18. 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 を検査できます。

4.8.19. Pipelines as Code 設定のカスタマイズ

クラスター管理者は pipelines-as-code namespace の pipelines-as-code 設定マップを使用して以下のパラメーターを設定し、Pipelines as Code をカスタマイズすることができます。

表4.8 Pipelines as Code 設定のカスタマイズ

パラメーター説明デフォルト

application-name

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

"Pipelines as Code CI"

max-keep-days

実行されたパイプライン実行が pipelines-as-code namespace に保持される日数。

この configmap の設定は、ユーザーのパイプライン実行のクリーンアップには影響しません。これは、ユーザーの GitHub リポジトリーのパイプライン実行定義のアノテーションによって制御されます。

 

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

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

enabled

4.8.20. Pipelines as Code のコマンドリファレンス

tkn pac CLI ツールは、以下の機能を提供します。

  • ブートストラップ Pipelines as Code のインストールおよび設定。
  • 新規 Pipelines as Code リポジトリーの作成。
  • すべての Pipeline as Code リポジトリーをリスト表示。
  • Pipeline as Code リポジトリーおよび関連付けられた実行の記述。
  • 使用を開始するための単純なパイプライン実行の生成。
  • Pipelines as Code によって実行されたかのようにパイプラインの実行を解決。
ヒント

アプリケーションのソースコードが含まれる Git リポジトリーに変更を加える必要がないように、テストおよび実験用に機能に対応するコマンドを使用することができます。

4.8.20.1. 基本的な構文

$ tkn pac [command or options] [arguments]

4.8.20.2. グローバルオプション

$ tkn pac --help

4.8.20.3. ユーティリティーコマンド

4.8.20.3.1. bootstrap

表4.9 ブートストラップ 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

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

4.8.20.3.2. repository

表4.10 Pipelines as Code リポジトリーの管理

コマンド説明

tkn pac repo create

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

tkn pac repo list

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

tkn pac repo describe

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

4.8.20.3.3. generate

表4.11 Pipelines as Code を使用したパイプライン実行の生成

コマンド説明

tkn pac generate

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

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

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

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

4.8.20.3.4. resolve

表4.12 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 ブランチをリビジョンおよび異なるリポジトリー名として使用できます。

4.8.21. 関連情報