付録 A: GitHub (OAuth アプリ経由) ソースアクション

この付録では、CodePipeline での GitHub アクションの (OAuth アプリ経由) について説明します。

注記

GitHub (OAuth アプリ経由) アクションの使用はお勧めしませんが、GitHub (OAuth アプリ経由) アクションを持つ既存のパイプラインは何の影響なく引き続き動作します。GitHub (OAuth アプリ経由) アクションを持つパイプラインの場合、CodePipeline は OAuth ベースのトークンを使用して GitHub リポジトリに接続します。対照的に、GitHub アクション (GitHub アプリ経由) は接続リソースを使用して AWS リソースを GitHub リポジトリへ関連付けることができます。接続リソースは、アプリベースのトークンを使用して接続します。接続を使用する推奨される GitHub アクションにパイプラインを更新する方法の詳細については GitHub (OAuth アプリ経由) ソースアクションを GitHub (GitHub アプリ経由) ソースアクションに更新する を参照してください。アプリベースの GitHub アクセスとは対照的な OAuth ベースの GitHub アクセスの詳細については、https://docs.github.com/en/developers/apps/differences-between-github-apps-and-oauth-apps を参照してください。

GitHub と統合するために、CodePipeline はパイプライン用の OAuth アプリケーションを作成します。CodePipeline は、GitHub (OAuth アプリ経由) ソースアクションでパイプラインの変更検出を管理するためにウェブフックを使用します。

注記

CloudFormation で GitHub (GitHub アプリ経由) ソースアクションを設定する場合、GitHub トークン情報を含めたり、ウェブフックリソースを追加することはありません。「AWS::CodeStarConnections::Connection」の CloudFormation ユーザーガイド が示すように接続リソースを構成します。

このリファレンスには、GitHub (OAuth アプリ経由) アクションに関する次のセクションが含まれています。

• パイプラインに GitHub (OAuth アプリ経由) ソースアクションとウェブフックを追加する方法については、「GitHub (OAuth アプリ経由) ソースアクションの追加」を参照してください。

• GitHub (OAuth アプリ経由) ソースアクションの設定パラメータと YAML/JSON スニペットの例については、「GitHub (OAuth アプリ経由) ソースアクションリファレンス」を参照してください。

重要

CodePipeline ウェブフックを作成するときは、独自の認証情報を使用したり、複数のウェブフック間で同じシークレットトークンを再利用したりしないでください。セキュリティを最適化するには、作成するウェブフックごとに一意のシークレットトークンを生成します。シークレットトークンは、ユーザーが指定する任意の文字列で、ウェブフックペイロードの整合性と信頼性を保護するために、CodePipeline に送信するウェブフックペイロードを GitHub で計算して署名するために使用します。独自の認証情報を使用したり、複数のウェブフック間で同じトークンを再利用したりすると、セキュリティの脆弱性につながる可能性があります。

注記

シークレットトークンを指定していた場合は、レスポンスで編集されます。

GitHub (OAuth アプリ経由) ソースアクションの追加

GitHub (OAuth アプリ経由) ソースアクションを CodePipeline に追加するには、次の手順を実行します。

• CodePipeline コンソールの [パイプラインの作成] ウィザード (カスタムパイプラインを作成する (コンソール))、または [アクションを編集する] ページを使用して、[GitHub] プロバイダオプションを選択します。コンソールは、ソースが変更されたときにパイプラインを開始するウェブフックを作成します。

• CLI を使用して、GitHub アクションのアクション設定を追加し、次のようにリソースを追加作成します。

  • GitHub でのアクション設定の例を GitHub (OAuth アプリ経由) ソースアクションリファレンス で使用し、パイプラインを作成する (CLI) で表示されるようなアクションを作成します。

  • 定期的にチェックを無効にし、変更検出を手動で作成します。これは、変更検出方法によりソースをポーリングすることでパイプラインが開始されるためです。ポーリングパイプラインを GitHub (OAuth アプリ経由) アクションのウェブフックに移行します。

GitHub (OAuth アプリ経由) ソースアクションリファレンス

注記

GitHub (OAuth アプリ経由) アクションの使用はお勧めしませんが、GitHub (OAuth アプリ経由) アクションを持つ既存のパイプラインは何の影響なく引き続き動作します。GitHub (OAuth アプリ経由) アクションを持つパイプラインの場合、CodePipeline は OAuth ベースのトークンを使用して GitHub リポジトリに接続します。対照的に、新しい GitHub アクション (GitHub アプリ経由) は接続リソースを使用して AWS リソースを GitHub リポジトリへ関連付けることができます。接続リソースは、アプリベースのトークンを使用して接続します。推奨される GitHub アクションを使用した接続でパイプラインを更新する方法の詳細については「GitHub (OAuth アプリ経由) ソースアクションを GitHub (GitHub アプリ経由) ソースアクションに更新する」 を参照してください。

設定された GitHub リポジトリとブランチで新しいコミットが行われたときに、パイプラインをトリガーします。

GitHub と統合するため、CodePipeline はパイプラインの OAuth アプリケーションまたは個人用アクセストークンを使用します。コンソールを使用してパイプラインを作成または編集する場合、CodePipeline は GitHub Webhook を作成し、リポジトリに変更が生じた場合に、パイプラインを開始するようにします。

GitHub アクションを介してパイプラインを接続する前に、GitHub アカウントとリポジトリを作成しておく必要があります。

CodePipeline のリポジトリへのアクセスを制限する場合は、GitHub アカウントを作成し、CodePipeline と統合するリポジトリのみにアカウントのアクセス許可を付与します。CodePipeline を設定する際は、そのアカウントを使用し、パイプラインのソースステージの GitHub リポジトリを使用します。

詳細については、GitHub ウェブサイトの GitHub 開発者向けドキュメントを参照してください。

トピック

• アクションタイプ

• 設定パラメータ

• 入力アーティファクト

• 出力アーティファクト

• 出力変数

• アクションの宣言 (GitHub の例)

• GitHub (OAuth) への接続

• 関連情報

アクションタイプ

• カテゴリ: Source

• 所有者: ThirdParty

• プロバイダー: GitHub

• バージョン: 1

設定パラメータ

所有者

必須: はい

GitHub リポジトリを所有する GitHub ユーザーまたは組織の名前。

Repo

必須: はい

ソースの変更が検出されるリポジトリの名前。

ブランチ

必須: はい

ソースの変更が検出されるブランチの名前。

OAuthToken

必須: はい

GitHub リポジトリで CodePipeline が操作を実行できるようにするための GitHub 認証トークンを表します。エントリは、常に 4 つのアスタリスクでマスクされた状態で表示されます。これは、次のいずれかの値を表します。

• コンソールを使用してパイプラインを作成すると、CodePipeline は、OAuth トークンを使用して GitHub 接続を登録します。

• AWS CLI を使用してパイプラインを作成する場合、このフィールドに GitHub 個人用アクセストークンを渡すことができます。アスタリスク (****) を GitHub からコピーした個人用アクセストークンに置き換えます。get-pipeline を実行してアクション設定を表示すると、この値の 4 つのアスタリスクマスクが表示されます。

• CloudFormation テンプレートを使用してパイプラインを作成する場合、最初にトークンをシークレットとして AWS Secrets Manager に保存する必要があります。このフィールドの値は、{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}} など Secrets Manager に保存されたシークレットへの動的リファレンスとして含めます。

GitHub のスコープに関する詳細については、GitHub ウェブサイトの「GitHub 開発者 API リファレンス」を参照してください。

PollForSourceChanges

必須: いいえ

PollForSourceChanges は、 CodePipeline が GitHub リポジトリをポーリングしてソースを変更するかどうかを制御します。この方法の代わりに、ウェブフックを使用してソースの変更を検出することをお勧めします。ウェブフックの設定に関する詳細は、「ポーリングパイプラインを Webhook に移行する (GitHub (OAuth アプリ経由) ソースアクション) (CLI)」または「プッシュイベント用にパイプラインを更新する (GitHub (OAuth アプリ経由) ソースアクション) (CloudFormation テンプレート)」を参照してください。

重要

ウェブフックを設定する場合、パイプライン実行の重複を避けるため、PollForSourceChanges を false に設定します。

このパラメータの有効な値:

• True: 設定されている場合、CodePipeline はソースの変更についてポーリングします。

  注記

  PollForSourceChanges を省略すると、CodePipeline はデフォルトでソースの変更についてポーリングします。この動作は、PollForSourceChanges が true に設定されている場合と同じです。

• False: 設定されている場合、CodePipeline は、ソースの変更についてリポジトリをポーリングしません。ソースの変更を検出するようにウェブフックを構成する場合は、この設定を使用します。

入力アーティファクト

• アーティファクトの数: 0

• 説明: 入力アーティファクトは、このアクションタイプには適用されません。

出力アーティファクト

• アーティファクトの数: 1

• 説明: このアクションの出力アーティファクトは、パイプライン実行のソースリビジョンとして指定されたコミットで設定されたリポジトリとブランチの内容を含む ZIP ファイルです。リポジトリから生成されたアーティファクトは、GitHub アクションの出力アーティファクトです。ソースコードのコミット ID は、パイプライン実行のトリガーとなるソースリビジョンとして、CodePipeline に表示されます。

出力変数

このアクションを設定すると、パイプライン内のダウンストリームアクションのアクション設定によって参照できる変数が生成されます。このアクションは、アクションに名前空間がない場合でも、出力変数として表示できる変数を生成します。名前空間を使用してアクションを設定し、これらの変数をダウンストリームアクションの設定で使用できるようにします。

CodePipeline の変数についての詳細は、「変数リファレンス」を参照してください。

CommitId

パイプライン実行をトリガーした GitHub コミット ID。コミット ID は、コミットの完全な SHA です。

CommitMessage

パイプライン実行をトリガーしたコミットに関連付けられた説明メッセージ (存在する場合)。

CommitUrl

パイプラインをトリガーしたコミットの URL アドレス。

RepositoryName

パイプラインをトリガーしたコミットが実行された GitHub リポジトリの名前。

BranchName

ソースの変更が行われた GitHub リポジトリのブランチの名前。

AuthorDate

コミットが認証された日付 (タイムスタンプ形式)。

CommitterDate

コミットがコミットされた日付 (タイムスタンプ形式)。

アクションの宣言 (GitHub の例)

YAML

Name: Source
Actions:
  - InputArtifacts: []
    ActionTypeId:
      Version: '1'
      Owner: ThirdParty
      Category: Source
      Provider: GitHub
    OutputArtifacts:
      - Name: SourceArtifact
    RunOrder: 1
    Configuration:
      Owner: MyGitHubAccountName
      Repo: MyGitHubRepositoryName
      PollForSourceChanges: 'false'
      Branch: main
      OAuthToken: '{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}'
    Name: ApplicationSource

JSON

{
    "Name": "Source",
    "Actions": [
        {
            "InputArtifacts": [],
            "ActionTypeId": {
                "Version": "1",
                "Owner": "ThirdParty",
                "Category": "Source",
                "Provider": "GitHub"
            },
            "OutputArtifacts": [
                {
                    "Name": "SourceArtifact"
                }
            ],
            "RunOrder": 1,
            "Configuration": {
                "Owner": "MyGitHubAccountName",
                "Repo": "MyGitHubRepositoryName",
                "PollForSourceChanges": "false",
                "Branch": "main",
                "OAuthToken": "{{resolve:secretsmanager:MyGitHubSecret:SecretString:token}}"
            },
            "Name": "ApplicationSource"
        }
    ]
},

GitHub (OAuth) への接続

初めて GitHub リポジトリをパイプラインに追加するコンソールを使用する場合、CodePipeline のリポジトリへのアクセスを承認するように要求されます。トークンには、次の GitHub スコープが必要です。

• repo スコープ。これは、パブリックおよびプライベートリポジトリからパイプラインにアーティファクトを読み込んでプルする完全制御に使用されます。

• admin:repo_hook スコープ。これは、リポジトリフックの完全制御に使用されます。

CLI または CloudFormation テンプレートを使用する場合は、すでに GitHub で作成した個人用アクセストークンの値を指定する必要があります。

関連情報

このアクションを利用する際に役立つ関連リソースは以下の通りです。

• AWS CloudFormation AWS::CodePipeline::Webhook ユーザーガイド のリソースリファレンス - これにはフィールド定義、例、および CloudFormation にあるリソースに対するスニペットが含まれます。

• AWS CloudFormation AWS::CodeStar::GitHubRepository ユーザーガイド のリソースリファレンス フィールド定義、例および CloudFormation にあるリソースに対するスニペットが含まれます。

• チュートリアル: AWS Device Farm で Android アプリケーションを構築してテストするパイプラインを作成する このチュートリアルでは、GitHub ソースでパイプラインを作成するためのビルド仕様ファイルとサンプルアプリケーションを提供します。CodeBuild および AWS Device Farm を使用して Android アプリ を構築し、テストします。