GitHub リポジトリに接続する

このページでは、GitHub リポジトリを Cloud Build に接続する方法について説明します。Cloud Build リポジトリの詳細については、 Cloud Build リポジトリをご覧ください。

始める前に

  • GitHub リポジトリにソースコードを用意します。
  • GitHub ソース リポジトリに、Dockerfile または Cloud Build 構成ファイルを配置します。
  • 最初にリポジトリを Cloud Build に接続する場合は、リポジトリに対する管理者レベルの権限があることを確認してください。GitHub リポジトリの権限の詳細については、 組織におけるリポジトリ権限レベルをご覧ください。

  • このページで gcloud コマンドを使用するには、 Google Cloud CLI をインストールします。

GitHub ホストに接続する

コンソール

GitHub リポジトリを Cloud Build に接続するには:

  1. [リポジトリ] ページを Google Cloud コンソールで開きます。

    [リポジトリ] ページを開く

    [リポジトリ] ページが表示されます。

  2. 上部のバーにあるプロジェクト セレクタで、 プロジェクトを選択します。 Google Cloud

  3. ページ上部の [第 2 世代] タブを選択します。

  4. [ホスト接続の作成] をクリックして、新しいホストを Cloud Build に接続します。

  5. 左側のパネルで、ソース プロバイダとして GitHub を選択します。

  6. [接続の構成] セクションで、次の情報を入力します。

    • [リージョン]: 接続のリージョンを選択します。

    • [**名前**]: 接続の名前を入力します。

  7. 省略可: GitHub リポジトリのアクセス トークンの暗号化に使用する暗号鍵を管理する場合は、[暗号化] セクションに移動して、Cloud Key Management Service 鍵を選択します。 詳細については、 Secret Manager の顧客管理の暗号鍵を有効にするをご覧ください。

  8. [接続] をクリックします。

    [接続] ボタンをクリックすると、Cloud Build GitHub アプリから GitHub アカウントへのアクセスを承認するように求められます。ホストからアプリをアンインストールまたは削除することで、いつでもアクセス権を取り消すことができます。

    Cloud Build は、GitHub ユーザー アカウントの承認をリクエストし、生成された認証トークンをプロジェクトの Secret Manager に保存します。認証トークンは、ユーザー アカウントによる Cloud Build GitHub アプリのインストールとリンクされたリポジトリへのアクセスを検証するために使用されます。Cloud Build サービス エージェント アカウント（service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com）が、シークレットへのアクセスに使用されます。シークレットを表示するには、 シークレットを一覧表示し、シークレットの詳細を確認するをご覧ください。

    Cloud Build GitHub アプリを承認すると、Cloud Build の [リポジトリ] ページにリダイレクトされます。

gcloud

gcloud を使用して GitHub ホストを接続する手順は次のとおりです。

  1. 次のコマンドを入力して、GitHub リポジトリへの接続を開始します。

     gcloud builds connections create github CONNECTION_NAME --region=REGION

    ここで

    • CONNECTION_NAME は、Cloud Build に表示される接続の名前です。

    • REGION はトリガーの region です 。

    gcloud builds connections コマンドを実行すると、Cloud Build GitHub アプリを承認するためのリンクが表示されます。

  2. github.com アカウントにログインします。

  3. リンクをクリックして、Cloud Build GitHub アプリを承認します。

    アプリを承認すると、Cloud Build は、認証 トークンを プロジェクトの Secret Manager にシークレットとして保存します。 Google Cloudシークレットは [Secret Manager] ページで確認できます。

  4. Cloud Build GitHub アプリを、ご利用のアカウントか、所有する組織アカウントにインストールします。

    GitHub アカウントを使用してインストールを許可し、指示が表示されたらリポジトリの権限を選択します。

  5. 次のコマンドを実行して、GitHub 接続のインストールを確認します。

     gcloud builds connections describe CONNECTION_NAME --region=REGION

    ここで

    • CONNECTION_NAME は、Cloud Build の GitHub ホスト 接続の名前です。
    • REGION はトリガーの region です 。

    installationState フィールドが COMPLETE に設定されている場合は、接続が正常にインストールされています。それ以外の場合、installationState フィールドには、必要な追加の手順へのリンクが表示されます。

GitHub ホストにプログラムで接続する

プログラムによる接続を安全に設定するには、 Google Cloud's セキュリティに関するおすすめの方法に従ってください。

  • Workload Identity 連携（WIF）: デプロイ スクリプトまたは Terraform 構成を CI/CD パイプライン（GitHub Actions や GitLab CI など）で実行する場合は、 Workload Identity 連携 を構成し、IAM ロールを使用して有効期間の短い認証情報を 利用して、パイプラインを Google Cloudに対して認証します。これにより、有効期間の長いサービス アカウント キーを管理して公開する必要がなくなります。
  • 最小権限の原則: 認証トークンに必要な最小限のスコープと 権限のみを選択します。
  • きめ細かい個人用アクセス トークン: クラシック個人用アクセス トークンではなく、有効期限の短いきめ細かい 個人用アクセス トークン（PAT）を使用することをおすすめします。

  • ロボット アカウントを使用する: 従業員の役割の変更や退職によるパイプラインの中断のリスクを軽減するには、従業員の個人アカウントではなく、専用の GitHub ロボット アカウントまたはサービス アカウントを使用します。

Terraform

Google Terraform プロバイダを使用して GitHub ホストを Cloud Build に接続するには、次の手順を行います。

  1. Cloud Build GitHub アプリ をご利用の GitHub アカウントか所有する組織にインストールします。

  2. GitHub で 個人アクセス トークン を作成します。専用の GitHub ロボット アカウントを使用してこのトークンを生成することをおすすめします。

    • きめ細かい個人用アクセス トークン （PAT）を作成することを強くおすすめします。

      • 有効期限を短く設定します。有効期限のないトークンはおすすめしません。
      • 設定に必要な 最小限の権限 を選択します。

    • フォールバックとして従来の個人用アクセス トークン を使用する必要がある場合（広範なリポジトリ スコープが付与されるため安全性が低い）、GitHub でプロンプトが表示されたら、次の OAuth スコープ を選択します。

    • repo を使用して、公開リポジトリと非公開リポジトリへの完全なアクセス権を付与します。

    • read:user を使用して、ユーザーのプロファイル データを読み取るアクセス権を付与します。

    • read:org を使用して、組織のメンバーシップとプロジェクトへの読み取り専用アクセス権を付与します（アプリが組織にインストールされている場合）。

  3. トークンを生成したら、安全な場所に保存します。このトークンは、以降の手順で使用します。

以下の例では、コード スニペットで次のことを行います。

  • Terraform Google プロバイダを構成します。デプロイ パイプラインから構成を実行する場合は、有効期間の短い認証情報で Workload Identity 連携を使用するようにプロバイダを構成します。

  • GitHub 個人用アクセス トークン（PAT）を表すシークレットを作成し、Cloud Build サービス エージェントにシークレットへのアクセス権を付与します。

  • GitHub 接続を作成します。

    // Configure the terraform google provider
terraform {
  required_providers {
    google = {}
   }
}

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project = PROJECT_ID
    secret_id = SECRET_ID

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

data "google_iam_policy" "serviceagent_secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

ここで

  • PROJECT_NUMBER は Google Cloud プロジェクト番号です。
  • SECRET_ID は、Secret Manager のトークンまたはシークレットの ID です。
  • GITHUB_PAT は、GitHub の個人用アクセス トークンのアクセス トークンです。
  • PROJECT_ID は Google Cloud プロジェクト ID です。
  • REGION は、接続の リージョン です。
  • CONNECTION_NAME は、Cloud Build に表示される接続の名前です。
  • INSTALLATION_ID は、Cloud Build GitHub アプリのインストール ID です。インストール ID は、Cloud Build GitHub アプリの URL にあります。次の URL https://github.com/settings/installations/1234567 では、インストール ID は数値 1234567 です。

gcloud

以前の接続から取得した既存のトークンとインストール ID を使用して GitHub ホストを接続する手順は次のとおりです。

  1. Cloud Build GitHub アプリ をご利用の GitHub アカウントか所有する組織にインストールします。

  2. GitHub で 個人アクセス トークン を作成します。専用の GitHub ロボット アカウントを使用してこのトークンを生成することをおすすめします。

    • きめ細かい個人用アクセス トークン （PAT）を作成することを強くおすすめします。

      • 有効期限を短く設定します。有効期限のないトークンはおすすめしません。
      • 設定に必要な 最小限の権限 を選択します。

    • フォールバックとして従来の個人用アクセス トークン を使用する必要がある場合（広範なリポジトリ スコープが付与されるため安全性が低い）、GitHub でプロンプトが表示されたら、次の OAuth スコープ を選択します。

    • repo を使用して、公開リポジトリと非公開リポジトリへの完全なアクセス権を付与します。

    • read:user を使用して、ユーザーのプロファイル データを読み取るアクセス権を付与します。

    • read:org を使用して、組織のメンバーシップとプロジェクトへの読み取り専用アクセス権を付与します（アプリが組織にインストールされている場合）。

    トークンを生成したら、安全な場所に保存します。このトークンは、以降の手順で使用します。

  3. 次のコマンドを実行して、 Google Cloud プロジェクト の Secret Manager にトークンを保存します。

        echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-

    ここで

    • TOKEN は、個人用のアクセス トークンです。
    • SECRET_NAME は、Secret Manager で シークレットに付ける名前です。

  4. シークレットの Cloud Build サービス エージェントへのアクセス権を付与します。 SECRET_NAME は Secret Manager に保存されているシークレットの名前です。

      PROJECT_ID=$(gcloud config list --format="value(core.project)")
  PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
  CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
  gcloud secrets add-iam-policy-binding SECRET_NAME \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
    --role="roles/secretmanager.secretAccessor"

  5. GitHub 接続を作成します。

      gcloud builds connections create github CONNECTION_NAME \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/1  \
    --app-installation-id=INSTALLATION_ID --region=REGION

    ここで

    • CONNECTION_NAME は、Cloud Build の GitHub ホスト接続の名前です。
    • PROJECT_ID は Google Cloud プロジェクト ID です。
    • SECRET_NAME はシークレット マネージャーに保存されているシークレットの名前です。
    • INSTALLATION_ID は、GitHub アプリのインストール ID です。インストール ID は、Cloud Build GitHub アプリの URL にあります。次の URL https://github.com/settings/installations/1234567 では、インストール ID は数値 1234567 です。
    • REGION は、接続のリージョンです。

GitHub リポジトリを接続する

コンソール

GitHub リポジトリをホスト接続に接続する手順は次のとおりです。

  1. [リポジトリ] ページを Google Cloud コンソールで開きます。

    [リポジトリ] ページを開く

    [リポジトリ] ページが表示されます。

  2. ページ上部の [第 2 世代] タブを選択します。

  3. [リポジトリをリンク] をクリックして、接続からリポジトリをリンクします。

    [リポジトリをリンク] パネルが表示されます。

  4. [リポジトリをリンク] パネルで、次の情報を入力します。

    1. [接続]: プルダウン メニューから接続を選択します。

    2. [Repository]: 接続にリンクするリポジトリを選択します。

    3. リポジトリ名: リポジトリの名前を入力します。

      1. 生成済み: このオプションを選択すると、Cloud Build によって選択したリポジトリのリポジトリ名が自動的に生成されます。

      2. 手動: このオプションを選択して、選択したリポジトリの名前を手動で指定します。

        [手動] を選択した場合、リポジトリ名セクションで選択したリポジトリの名前を変更できます。

  5. [リンク] をクリックして、リポジトリを接続にリンクします。

gcloud

GitHub リポジトリを接続に追加するには、次のコマンドを入力します。

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

ここで

  • REPO_NAME はリポジトリの名前です。
  • REPO_URI は GitHub リポジトリへのリンクです。例: https://github.com/cloud-build/test-repo.git
  • CONNECTION_NAME は、GitHub ホストに接続するで Cloud Build に作成された GitHub Enterprise ホスト接続の名前です。
  • REGION は、接続の リージョン です。

Terraform

GitHub リポジトリを接続に追加するには、次のコード スニペットを Terraform 構成に追加します。

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

ここで

  • PROJECT_ID は Google Cloud プロジェクト ID です。
  • REPO_NAME は GitHub リポジトリの名前です。
  • REGION は、接続の リージョン です。
  • URI はリポジトリのホスト URI です。例: https://github.com/myuser/myrepo.git

次のステップ