CodePipeline
ユーザーガイド (API バージョン 2015-07-09)

CodePipeline パイプライン構造のリファレンス

デフォルトでは、AWS CodePipeline に正常に作成されたパイプラインには、有効な構造が含まれます。ただし、JSON ファイルを手動で作成または編集して、AWS CLI からパイプラインを作成するか、アップデートする場合、意図せずに無効な構造が作成される場合があります。次のリファレンスは、パイプライン構造の要件や、問題をトラブルシューティングする方法を理解するのに役立ちます。すべてのパイプラインに適用される AWS CodePipeline 制限 の制約を参照してください。

CodePipeline の有効なアクションタイプとアクションプロバイダ

パイプライン構造の形式は、パイプラインのステージとアクションをビルドするために使用します。アクションタイプは、アクションカテゴリとアクションプロバイダタイプの組み合わせで構成されます。

CodePipeline の有効なアクションカテゴリは以下のとおりです。

  • ソース

  • ビルド

  • テスト

  • デプロイ

  • 承認

  • 呼び出し

アクションカテゴリごとにプロバイダのセットが指定されています。次の表は、アクションタイプ別の有効なプロバイダのリストです。

アクションタイプ別の有効なアクションプロバイダ

アクションカテゴリ 有効なアクションプロバイダ
ソース Amazon S3
CodeCommit
GitHub
Amazon ECR
ビルド CodeBuild
カスタム CloudBees
カスタム Jenkins
カスタム TeamCity
テスト CodeBuild
AWS Device Farm
カスタム BlazeMeter
サードパーティー GhostInspector
カスタム Jenkins
サードパーティー Micro Focus StormRunner Load
サードパーティー Nouvola
サードパーティー Runscope
デプロイ Amazon S3
AWS CloudFormation
CodeDeploy
Amazon ECS
Elastic Beanstalk
AWS OpsWorks
AWS Service Catalog
Amazon Alexa
カスタム XebiaLabs
承認 手動
呼び出し AWS Lambda

CodePipeline の一部のアクションタイプは、限定された AWS リージョンでのみ使用できます。AWS リージョンでアクションタイプが使用できても、そのアクションタイプの AWS プロバイダが使用できない場合があります。

各アクションプロバイダの詳細については、「CodePipeline アクションの種類との統合」を参照してください。

以下のセクションでは、アクションタイプ別のプロバイダ情報と設定プロパティの例を示します。

CodePipeline のパイプラインおよびステージ構造の要件

ステージが 2 つのパイプラインの基本構造は次のとおりです。

{ "roleArn": "An IAM ARN for a service role, such as arn:aws:iam::80398EXAMPLE:role/AWS-CodePipeline-Service", "stages": [ { "name": "SourceStageName", "actions": [ ... See CodePipeline のアクション構造の要件 ... ] }, { "name": "NextStageName", "actions": [ ... See CodePipeline のアクション構造の要件 ... ] } ], "artifactStore": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated for you the first time you create a pipeline using the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose" }, "name": "YourPipelineName", "version": 1 }

パイプライン構造には、次の要件があります。

  • パイプラインに少なくとも 2 つのステージを含める必要がある

  • パイプラインの最初のステージには、少なくとも 1 つのソースアクションが含まれている必要があるソースアクションのみを含めることができる

  • ソースアクションは、パイプラインの最初のステージにのみ含める

  • 各パイプラインのいずれかのステージには、必ずソースアクション以外のアクションを含めること

  • パイプライン内の全てのステージ名は必ず一意であること

  • ステージ名は、CodePipeline コンソール内で編集することはできません。AWS CLI を使用してステージ名を編集し、そのステージのアクションにシークレットパラメータ (OAuth トークンなど) が含まれる場合、そのシークレットパラメータの値が保持されることはありません。パラメータ値 (AWS CLI より返る JSON で、4 つのアスタリスクでマスクされている) は手動で入力し、JSON 構造に含める必要があります。

  • artifactStore フィールドには、同じ AWS リージョン内のすべてのアクションを含むパイプラインのアーティファクトバケットタイプと場所が含まれます。パイプラインと異なるリージョンにアクションを追加すると、artifactStores マッピングを使用して、アクションを実行する各 AWS リージョンのアーティファクトバケットが一覧表示されます。パイプラインを作成または編集する場合は、パイプラインリージョンにアーティファクトバケットが必要であり、アクションを実行する予定のリージョンごとに 1 つのアーティファクトバケットが必要です。

    次の例は、artifactStores パラメータを使用するクロスリージョンアクションを含むパイプラインの基本構造を示しています。

    "pipeline": { "name": "YourPipelineName", "roleArn": "ServiceRoleARN", "artifactStores": { "us-east-1": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated as the default when you use the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose" }, "us-west-2": { "type": "S3", "location": "The name of the Amazon S3 bucket automatically generated as the default when you use the console, such as codepipeline-us-east-2-1234567890, or any Amazon S3 bucket you provision for this purpose" } }, "stages": [ { ...
  • パイプラインメタデータフィールドはパイプライン構造とは異なり、編集することはできません。パイプラインを更新すると、updated メタデータフィールドの日付が自動的に変更されます。

  • パイプラインを編集または更新する場合、パイプライン名は変更できません。

    注記

    既存のパイプラインの名前を変更するには、CLI get-pipeline コマンドを使用して、パイプライン構造を含む JSON ファイルを作成します。次に CLI create-pipeline コマンドを使用してその構造を持つ新しいパイプラインを作成し、新しい名前を付けて保存します。

パイプラインのバージョン番号は自動的に生成され、パイプラインを更新する度に更新されます。

CodePipeline のアクション構造の要件

アクション構造の概要は次のとおりです。

[ { "inputArtifacts": [ An input artifact structure, if supported for the action category ], "name": "ActionName", "region": "Region", "namespace": "source_namespace", "actionTypeId": { "category": "An action category", "owner": "AWS", "version": "1" "provider": "A provider type for the action category", }, "outputArtifacts": [ An output artifact structure, if supported for the action category ], "configuration": { Configuration details appropriate to the provider type }, "runOrder": A positive integer that indicates the run order within the stage, } ]

このプロバイダタイプに該当する configuration 例の詳細については、「プロバイダタイプ別の設定の詳細」を参照してください。

アクション構造には、次の要件があります。

  • ステージ内のアクション名が必ず一意であること

  • アクションの入力アーティファクトが、前述のアクションで宣言された出力アーティファクトと完全に一致する必要があります。たとえば、前述のアクションに次の宣言が含まれているとします。

    "outputArtifacts": [ { "MyApp" } ],

    それ以外に出力アーティファクトが存在しない場合、次のアクションの入力アーティファクトは次のようになります。

    "inputArtifacts": [ { "MyApp" } ],

    これは、同じステージか、次のステージかにかかわらず、すべてのアクションで当てはまりますが、出力アーティファクトを提供したアクションから厳密なシーケンスで、入力アーティファクトを次のアクションにする必要はありません。アクションは並行して、さまざまな出力アーティファクトバンドルを宣言することがあります。これらは、以下のアクションによって、順番に消費されます。

    次の図は、パイプラインのアクションでの入力および出力アーティファクトの例を示します。

    
                        パイプラインのアクションでの入力および出力アーティファクトの例。
  • 出力アーティファクト名は、パイプライン内で一意である必要があります。たとえば、パイプラインには出力アーティファクト ("MyApp") を含むアクションと、出力アーティファクト ("MyBuiltApp") を含む別のアクションが含まれる場合があります。ただし、いずれも出力アーティファクト ("MyApp") の 2 つのアクションをパイプラインに含むことはできません。

  • クロスリージョンアクションでは、Region フィールドを使用して、アクションが作成される AWS リージョンを指定します。このアクション用に作成された AWS リソースは、region フィールドで指定されているリージョンと同じリージョンに作成する必要があります。以下のアクションタイプのクロスリージョンアクションは作成できません。

    • ソースアクション

    • サードパーティープロバイダによるアクション

    • カスタムプロバイダによるアクション

  • アクションは変数で設定できます。namespace フィールドを使用して、実行変数の名前空間と変数の情報を設定します。実行変数とアクション出力変数のリファレンス情報については、「変数」を参照してください。

  • GitHub ソースアクションの OAuth トークンなど、値が secret のパラメータがアクションに含まれる場合、そのパラメータの値は、4 つのアスタリスク (****) によって JSON でマスクされます。実際の値は保存され、値を編集するか、アクション名、またはアクションを実行しているステージ名を変更しない限り、AWS CLI または CodePipeline API を用いて JSON を編集する際に値を入力する必要はありません。ただし、アクションの名前、またはアクションを実行しているステージの名前を変更する場合、secret パラメータの値は失われます。secret パラメータの値を手動で JSON に入力する必要があります。入力しない場合、アクションは次回パイプライン実行時に失敗します。

  • 現在サポートされているすべてのアクションの種類で、有効なバージョン文字列は「1」のみです。

  • 現在サポートされているすべてのアクションの種類で、有効な所有者の文字列は「AWS」、「ThirdParty」、「Custom」のみです。詳細については、「CodePipeline API リファレンス」を参照してください。

  • アクションの [runOrder] のデフォルト値は 1 です。値は、正の整数 (自然数) にする必要があります。分数、10 進数、負の数値、ゼロを使用することはできません。アクションのシリアルシーケンスを指定するには、最初のアクションに最小値を使用し、シーケンスの残りの各アクションにそれより大きい数値を使用します。同時に実行するアクションを指定するには、同時に実行する各アクションに同一の整数を使用します。

    たとえば、3 つのアクションをステージのシーケンスで実行する場合、最初のアクションは runOrder 値 1、2 番目のアクションは runOrder 値 2、3 番目のアクションは runOrder 値 3 になります。ただし、2 番目と 3 番目のアクションを同時に行う場合、最初のアクションは runOrder 値 1 になり、2 番目と 3 番目のアクションはいずれも runOrder 値 2 になります。

    注記

    シリアルアクションは、厳密なシーケンスでナンバリングする必要はありません。たとえば、シーケンスに 3 つのアクションがあり、2 番目のアクションを削除する場合、3 番目のアクションの runOrder 値をナンバリングし直す必要はありません。アクション (3) の runOrder 値は、最初のアクション (1) の runOrder 値より大きいため、ステージの最初のアクションが終わってから順番に実行されます。

  • デプロイ場所として Amazon S3 バケットを使用するときは、オブジェクトキーも指定します。オブジェクトキーはファイル名 (オブジェクト) にするか、プレフィックス (フォルダパス) とファイル名の組み合わせにすることができます。変数を使用して、パイプラインで使用する場所名を指定できます。Amazon S3 デプロイアクションでは、Amazon S3 オブジェクトキーでの以下の変数の使用がサポートされています。

    Amazon S3 での変数の使用

    変数 コンソール入力の例 出力
    datetime js-application/{datetime}.zip この形式の UTC タイムスタンプ: <YYYY>-<MM>-DD>_<HH>-<MM>-<SS>

    例:

    js-application/2019-01-10_07-39-57.zip

    uuid js-application/{uuid}.zip UUID は、他のすべての識別子と異なることが保証されるグローバル一意識別子です。この形式の UUID (すべての桁は 16 進形式): <8-digits>-<4-digits>-4-digits>-<4-digits>-<12-digits>

    例:

    js-application/54a60075-b96a-4bf3-9013-db3a9EXAMPLE.zip

  • アクションの種類によっては、次の入力および出力アーティファクトの数値になる場合があります。

    アーティファクトのアクションの種類の制約

    所有者 アクションの種類 プロバイダ 有効な数の入力アーティファクト 有効な数の出力アーティファクト
    AWS ソース Amazon S3 0 1
    AWS ソース CodeCommit 0 1
    AWS ソース Amazon ECR 0 1
    サードパーティー ソース GitHub 0 1
    AWS ビルド CodeBuild 1〜5 0〜5
    AWS テスト CodeBuild 1〜5 0〜5
    AWS テスト AWS Device Farm 1 0
    AWS 承認 手動 0 0
    AWS デプロイ Amazon S3 1 0
    AWS デプロイ AWS CloudFormation 0〜10 0〜1
    AWS デプロイ CodeDeploy 1 0
    AWS デプロイ AWS Elastic Beanstalk 1 0
    AWS デプロイ AWS OpsWorks Stacks 1 0
    AWS デプロイ Amazon ECS 1 0
    AWS デプロイ AWS Service Catalog 1 0
    AWS 呼び出し AWS Lambda 0〜5 0〜5
    サードパーティー デプロイ Alexa Skills Kit 1〜2 0
    Custom ビルド Jenkins 0〜5 0〜5
    Custom テスト Jenkins 0〜5 0〜5
    Custom サポートされているカテゴリ カスタムアクションで指定 0〜5 0〜5
  • 以下に示すのは、CodePipeline の有効な actionTypeId カテゴリです。

    • Source

    • Build

    • Approval

    • Deploy

    • Test

    • Invoke

    一部のプロバイダのタイプと設定オプションを以下に示します。

  • アクションカテゴリの有効なプロバイダタイプは、カテゴリによって異なります。たとえば、ソースアクションタイプの場合、有効なプロバイダタイプは S3GitHubCodeCommit、または Amazon ECR です。次の例は、S3 プロバイダのソースアクションの構造を示しています。

    "actionTypeId": { "category": "Source", "owner": "AWS", "version": "1", "provider": "S3"},
  • 各アクションに有効なアクションを設定する必要があります。この設定は、アクションのプロバイダのタイプによって異なります。次のテーブルでは、有効な各プロバイダのタイプで必要なアクション設定要素を示します。

    プロバイダのタイプのアクション設定プロパティ

    プロバイダ名 アクションの種類のプロバイダ名 設定プロパティ 必須プロパティ
    Amazon S3 (デプロイアクションプロバイダ) S3 BucketName 必須
    Extract 必須
    ObjectKey Extract = false の場合は必須
    KMSEncryptionKeyARN1 オプション
    CannedACL2 オプション
    CacheControl3 オプション
    Amazon ECR Amazon ECR パラメータに関連する例など、詳細については、「Amazon ECR」を参照してください。
    CodeCommit CodeCommit パラメータに関連する例など、詳細については、「CodeCommit」を参照してください。
    GitHub GitHub パラメータに関連する例など、詳細については、「GitHub」を参照してください。
    Amazon S3 (ソースアクションプロバイダ) Amazon S3 ソースアクションパラメータに関連する例など、詳細については、「Amazon S3」を参照してください。
    AWS CloudFormation AWS CloudFormation パラメータに関連する例など、詳細については、AWS CloudFormation を参照してください。
    CodeBuild CodeBuild パラメータに関する詳細な説明と例については、AWS CodeBuild を参照してください。
    CodeDeploy CodeDeploy ApplicationName 必須
    DeploymentGroupName 必須
    AWS Device Farm DeviceFarm RecordAppPerformanceData 必須
    AppType 必須
    ProjectId 必須
    App 必須
    RadioBluetoothEnabled デフォルト = true
    RecordVideo デフォルト = true
    RadioWifiEnabled デフォルト = true
    RadioNfcEnabled デフォルト = true
    RadioGpsEnabled デフォルト = true
    Test 必須
    DevicePoolArn 必須
    TestType 必須
    AppiumVersion 必須
    AWS Elastic Beanstalk ElasticBeanstalk ApplicationName 必須
    EnvironmentName 必須
    AWS Lambda AWS Lambda パラメータに関連する例など、詳細については、AWS Lambda を参照してください。
    AWS OpsWorks Stacks OpsWorks Stack 必須
    Layer オプション
    App 必須
    Amazon ECS ECS ClusterName 必須
    ServiceName 必須
    FileName オプション
    Amazon ECS (Blue/Green) CodeDeployToECS4 ApplicationName 必須
    DeploymentGroupName 必須
    TaskDefinitionTemplateArtifact 必須
    AppSpecTemplateArtifact 必須
    AppSpecTemplatePath 必須
    TaskDefinitionTemplatePath オプション
    Image1ArtifactName オプション
    Image1ContainerName オプション
    Image2ArtifactName オプション
    Image2ContainerName オプション
    Image3ArtifactName オプション
    Image3ContainerName オプション
    Image4ArtifactName オプション
    Image4ContainerName オプション
    AWS Service Catalog ServiceCatalog TemplateFilePath 必須
    ProductVersionName 必須
    ProductType 必須
    ProductVersionDescription オプション
    ProductId 必須
    Alexa Skills Kit AlexaSkillsKit ClientId 必須
    ClientSecret 必須
    RefreshToken 必須
    SkillId 必須
    Jenkins Jenkins の CodePipeline プラグイン で指定したアクションの名前 (MyJenkinsProviderName など) ProjectName 必須
    手動承認 Manual CustomData オプション
    ExternalEntityLink オプション
    NotificationArn オプション

    1KMSEncryptionKeyARN パラメータは、提供された KMS キーを使用してアップロードされたアーティファクトを暗号化します。AWS KMS キーの場合、キー ID、キー ARN、またはエイリアス ARN を使用できます。

    注記

    エイリアスは、カスタマーマスターキー (CMK) を作成したカウントでのみ認識されます。クロスアカウントアクションの場合、キー ID またはキー ARN のみを使用してキーを識別できます。

    2CannedACL パラメータは、指定された 既定 ACL を、Amazon S3 にデプロイされたオブジェクトに適用します。このオブジェクトに適用された既存の ACL が上書きされます。

    3CacheControl パラメータは、バケットのオブジェクトのリクエストやレスポンスのキャッシュ動作を制御します。有効な値のリストについては、HTTP オペレーションの Cache-Control ヘッダーフィールドを参照してください。CacheControl に複数の値を入力するには、各値の間にカンマを使用します。CLI の例に示すように、各カンマの後にスペースを追加できます (オプション)。

    "CacheControl": "public, max-age=0, no-transform"

    4Image1ContainerName など、これらのパラメータのいくつかを使用してパイプラインを作成するチュートリアルについては「ステップ 6: パイプラインの作成 」を参照してください。

PollForSourceChanges パラメータのデフォルト設定

PollForSourceChanges パラメータのデフォルトは、以下の表に示すように、パイプラインの作成に使用した方法によって決まります。多くの場合、PollForSourceChanges パラメータはデフォルトで true になるため、必要に応じて無効にする必要があります。PollForSourceChanges パラメータがデフォルトで true になる場合は、以下の操作を行う必要があります。

  • PollForSourceChanges パラメータを JSON ファイルまたは AWS CloudFormation テンプレートに追加します。

  • 変更検出リソース(必要に応じて CloudWatch イベント ルールまたはウェブフック)を作成します。

  • PollForSourceChanges パラメータを false に設定します。

    注記

    CloudWatch イベント ルールまたはウェブフックを作成する場合は、このパラメータを false に設定してパイプラインが複数回トリガーされるのを避ける必要があります。

    PollForSourceChanges パラメータは、Amazon ECR ソースアクションには使用されません。

  • PollForSourceChanges パラメータのデフォルト

    ソース 作成方法 「設定」JSON 構造の出力例
    CodeCommit パイプラインはコンソールで作成されます (変更検出リソースもコンソールで作成されます)。パラメータは、パイプライン構造の出力に表示され、デフォルトで false になります。
    BranchName": "master", "PollForSourceChanges": "false", "RepositoryName": "my-repo"
    パイプラインは CLI または AWS CloudFormation で作成されます。PollForSourceChanges パラメータ行は JSON 出力に表示されませんが、true に設定されます。²
    BranchName": "master", "RepositoryName": "my-repo"
    Amazon S3 パイプラインはコンソールで作成されます (変更検出リソースもコンソールで作成されます)。パラメータは、パイプライン構造の出力に表示され、デフォルトで false になります。
    "S3Bucket": "my-bucket", "S3ObjectKey": "object.zip", "PollForSourceChanges": "false"
    パイプラインは CLI または AWS CloudFormation で作成されます。PollForSourceChanges パラメータ行は JSON 出力に表示されませんが、true に設定されます。²
    "S3Bucket": "my-bucket", "S3ObjectKey": "object.zip"
    GitHub パイプラインはコンソールで作成されます (変更検出リソースもコンソールで作成されます)。パラメータは、パイプライン構造の出力に表示され、デフォルトで false になります。
    "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName" "PollForSourceChanges": "false", "Branch": "master" "OAuthToken": "****"
    パイプラインは CLI または AWS CloudFormation で作成されます。PollForSourceChanges パラメータ行は JSON 出力に表示されませんが、true に設定されます。²
    "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName", "Branch": "master", "OAuthToken": "****"

    ² PollForSourceChanges は、特定のポイントで JSON 構造または AWS CloudFormation テンプレートに追加されると、次のように表示されます。

    "PollForSourceChanges": "true",

    ³ 各ソースプロバイダに適用される変更検出リソースの詳細については、「変更検出方法」を参照してください。

プロバイダタイプ別の設定の詳細

このセクションでは、アクションプロバイダ別の有効な configuration パラメータを示します。

次の例は、Amazon S3 を使用するソースアクションの有効なアクション設定を示しています。

"configuration": { "S3Bucket": "awscodepipeline-demobucket-example-date", "S3ObjectKey": "CodePipelineDemoApplication.zip", "PollForSourceChanges": "false" }

次の例は、GitHub を使用するソースアクションに返されるアクション設定を示しています。

"configuration": { "Owner": "MyGitHubAccountName", "Repo": "MyGitHubRepositoryName", "PollForSourceChanges": "false", "Branch": "master", "OAuthToken": "****" },

次の例は、Amazon ECR を使用するソースアクションに返されるアクション設定を示しています。

"configuration": { "ImageTag": "latest", "RepositoryName": "my-image-repo" },

次の例は、Amazon ECS を使用するデプロイアクションの有効な設定を示しています。

"configuration": { "ClusterName": "my-ecs-cluster", "ServiceName": "sample-app-service", "FileName": "imagedefinitions.json", }

次の例は、AWS Device Farm を使用するテストアクションの有効な設定を示しています。

"configuration": { "RecordAppPerformanceData": "true", "AppType": "Android", "ProjectId": "Project_ID", "App": "app-release.apk", "RadioBluetoothEnabled": "true", "RecordVideo": "true", "RadioWifiEnabled": "true", "RadioNfcEnabled": "true", "RadioGpsEnabled": "true", "Test": "tests.zip", "DevicePoolArn": "ARN", "TestType": "Calabash", "AppiumVersion": "1.7.2" }

次の例は、AWS Service Catalog を使用するデプロイアクションの有効な設定を示しています。個別の設定ファイルを使用しないでパイプラインをコンソールで作成する場合のものです。

"configuration": { "TemplateFilePath": "S3_template.json", "ProductVersionName": "devops S3 v2", "ProductType": "CLOUD_FORMATION_TEMPLATE", "ProductVersionDescription": "Product version description", "ProductId": "prod-example123456" }

次の例は、AWS Service Catalog を使用するデプロイアクションの有効な設定を示しています。個別の sample_config.json 設定ファイルを使用してパイプラインをコンソールで作成する場合のものです。

"configuration": { "ConfigurationFilePath": "sample_config.json", "ProductId": "prod-example123456" }

次の例は、Alexa Skills Kit を使用するデプロイアクションの有効な設定を示しています。

"configuration": { "ClientId": "amzn1.application-oa2-client.aadEXAMPLE", "ClientSecret": "****", "RefreshToken": "****", "SkillId": "amzn1.ask.skill.22649d8f-0451-4b4b-9ed9-bfb6cEXAMPLE" }

次の例は、Amazon S3 を使用するデプロイアクションの有効な設定を示しています。

"configuration": { "BucketName": "website-bucket", "Extract": "true", "ObjectKey": "MyWebsite" }

次の例は、Amazon ECS および CodeDeploy の Blue/Green デプロイの有効な設定を示しています。

"configuration": { "ApplicationName": "codedeploy-ecs-application", "DeploymentGroupName": "ecs-codedeploy-deplgroup", "Image1ArtifactName": "MyImage", "TaskDefinitionTemplateArtifact": "SourceArtifact", "Image1ContainerName": "IMAGE1_NAME", "TaskDefinitionTemplatePath": "taskdef.json", "AppSpecTemplateArtifact": "SourceArtifact", "AppSpecTemplatePath": "appspec.yaml", }

次の例は、手動承認の有効な設定を示しています。

"configuration": { "CustomData": "Comments on the manual approval", "ExternalEntityLink": "http://my-url.com", "NotificationArn": "arn:aws:sns:us-west-2:12345EXAMPLE:Notification" }