diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9ac4b59..8e08b1f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,13 +25,13 @@ We look forward to receiving your pull requests for: To contribute, send us a pull request. For small changes, such as fixing a typo or adding a link, you can use the [GitHub Edit Button](https://blog.github.com/2011-04-26-forking-with-the-edit-button/). For larger changes: 1. [Fork the repository](https://help.github.com/articles/fork-a-repo/). -2. In your fork, make your change in a branch that's based on this repo's **master** branch. +2. In your fork, make your change in a branch that's based on this repo's **main** branch. 3. Commit the change to your fork, using a clear and descriptive commit message. 4. [Create a pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/), answering any questions in the pull request form. Before you send us a pull request, please be sure that: -1. You're working from the latest source on the **master** branch. +1. You're working from the latest source on the **main** branch. 2. You check [existing open](https://github.com/awsdocs/aws-codebuild-user-guide/pulls), and [recently closed](https://github.com/awsdocs/aws-codebuild-user-guide/pulls?q=is%3Apr+is%3Aclosed), pull requests to be sure that someone else hasn't already addressed the problem. 3. You [create an issue](https://github.com/awsdocs/aws-codebuild-user-guide/issues/new) before working on a contribution that will take a significant amount of your time. @@ -53,4 +53,4 @@ If you discover a potential security issue, please notify AWS Security via our [ ## Licensing -See the [LICENSE](https://github.com/awsdocs/aws-codebuild-user-guide/blob/master/LICENSE) file for this project's licensing. We will ask you to confirm the licensing of your contribution. We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. +See the [LICENSE](https://github.com/awsdocs/aws-codebuild-user-guide/blob/main/LICENSE) file for this project's licensing. We will ask you to confirm the licensing of your contribution. We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. diff --git a/README.md b/README.md index e633d77..c92957f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,13 @@ +# NOTICE + +**This repository is archived and the content on this branch is out of date.** You can find up-to-date AWS technical documentation on the [AWS Documentation website](https://docs.aws.amazon.com/), where you can also submit feedback and suggestions for improvement. + +# Announcement + +This repository will be archived and marked read-only next month (June 2023). For more information, read [the announcement on the AWS News Blog](https://aws.amazon.com/blogs/aws/retiring-the-aws-documentation-on-github/). + +You can find the corresponding content for this repo on [the AWS Documentation website](https://docs.aws.amazon.com/codebuild/latest/userguide). If you'd like to continue contributing to the quality of AWS documentation, you can submit feedback and suggestions for improvement there. + ## AWS CodeBuild User Guide The open source version of the AWS CodeBuild docs. You can submit feedback & requests for changes by submitting issues in this repo or by making proposed changes & submitting a pull request. @@ -9,8 +19,4 @@ The documentation is made available under the Creative Commons Attribution-Share The sample code within this documentation is made available under a modified MIT license. See the LICENSE-SAMPLECODE file. ## Default branch -The default branch for this repo has changed to `main`. If you had cloned the previous default branch, please update your local repo to use the `main` branch. You can remove the previous branch from your local repo with the following commands. -```bash -git checkout main -git fetch --all --prune -``` \ No newline at end of file +The default branch for this repo has changed to `main`. If you have checked out the previous default branch, please update your local repo to use the `main` branch. \ No newline at end of file diff --git a/doc_source/access-tokens.md b/doc_source/access-tokens.md new file mode 100644 index 0000000..eaaddd6 --- /dev/null +++ b/doc_source/access-tokens.md @@ -0,0 +1,231 @@ +# Access your source provider in CodeBuild + +For GitHub or GitHub Enterprise Server, you use a personal access token to access the source provider\. For Bitbucket, you use an app password to access the source provider\. + +**Topics** ++ [GitHub and GitHub Enterprise Server access token](#access-tokens-github) ++ [Bitbucket app password](#access-tokens-bitbucket) + +## GitHub and GitHub Enterprise Server access token + +### Access token prerequisites + +Before you begin, you must add the proper permission scopes to your GitHub access token\. + +For GitHub, your personal access token must have the following scopes\. ++ **repo**: Grants full control of private repositories\. ++ **repo:status**: Grants read/write access to public and private repository commit statuses\. ++ **admin:repo\_hook**: Grants full control of repository hooks\. This scope is not required if your token has the `repo` scope\. + +For more information, see [Understanding scopes for OAuth apps](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) on the GitHub website\. + +### Connect GitHub with an access token \(console\) + +To use the console to connect your project to GitHub using an access token, do the following when you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. + +1. For **Source provider**, choose **GitHub**\. + +1. For **Repository**, choose **Connect with a GitHub personal access token**\. + +1. In **GitHub personal access token**, enter your GitHub personal access token\. + +1. Choose **Save token**\. + +### Connect GitHub with an access token \(CLI\) + +Follow these steps to use the AWS CLI to connect your project to GitHub using an access token\. For information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. + +1. Run the import\-source\-credentials command: + + ``` + aws codebuild import-source-credentials --generate-cli-skeleton + ``` + + JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `import-source-credentials.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Modify the copied data as follows, and save your results\. + + ``` + { + "serverType": "server-type", + "authType": "auth-type", + "shouldOverwrite": "should-overwrite", + "token": "token", + "username": "username" + } + ``` + + Replace the following: + + *server\-type*: Required value\. The source provider used for this credential\. Valid values are GITHUB or GITHUB\_ENTERPRISE\. + + *auth\-type*: Required value\. The type of authentication used to connect to a GitHub or GitHub Enterprise Server repository\. Valid values include PERSONAL\_ACCESS\_TOKEN and BASIC\_AUTH\. You cannot use the CodeBuild API to create an OAUTH connection\. You must use the CodeBuild console instead\. + + *should\-overwrite*: Optional value\. Set to `false` to prevent overwriting the repository source credentials\. Set to `true` to overwrite the repository source credentials\. The default value is `true`\. + + *token*: Required value\. For GitHub or GitHub Enterprise Server, this is the personal access token\. + + *username*: Optional value\. This parameter is ignored for GitHub and GitHub Enterprise Server source providers\. + +1. To connect your account with an access token, switch to the directory that contains the `import-source-credentials.json` file you saved in step 1 and run the import\-source\-credentials command again\. + + ``` + aws codebuild import-source-credentials --cli-input-json file://import-source-credentials.json + ``` + + JSON\-formatted data appears in the output with an Amazon Resource Name \(ARN\)\. + + ``` + { + "arn": "arn:aws:codebuild:region:account-id:token/server-type" + } + ``` +**Note** +If you run the import\-source\-credentials command with the same server type and auth type a second time, the stored access token is updated\. + + After your account is connected with an access token, you can use `create-project` to create your CodeBuild project\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. + +1. To view the connected access tokens, run the list\-source\-credentials command\. + + ``` + aws codebuild list-source-credentials + ``` + + A JSON\-formatted `sourceCredentialsInfos` object appears in the output: + + ``` + { + "sourceCredentialsInfos": [ + { + "authType": "auth-type", + "serverType": "server-type", + "arn": "arn" + } + ] + } + ``` + + The `sourceCredentialsObject` contains a list of connected source credentials information: + + The `authType` is the type of authentication used by credentials\. This can be `OAUTH`, `BASIC_AUTH`, or `PERSONAL_ACCESS_TOKEN`\. + + The `serverType` is the type of source provider\. This can be `GITHUB`, `GITHUB_ENTERPRISE`, or `BITBUCKET`\. + + The `arn` is the ARN of the token\. + +1. To disconnect from a source provider and remove its access tokens, run the delete\-source\-credentials command with its ARN\. + + ``` + aws codebuild delete-source-credentials --arn arn-of-your-credentials + ``` + + JSON\-formatted data is returned with an ARN of the deleted credentials\. + + ``` + { + "arn": "arn:aws:codebuild:region:account-id:token/server-type" + } + ``` + +## Bitbucket app password + +### App password prerequisites + +Before you begin, you must add the proper permission scopes to your Bitbucket app password\. + +For Bitbucket, your app password must have the following scopes\. ++ **repository:read**: Grants read access to all the repositories to which the authorizing user has access\. ++ **pullrequest:read**: Grants read access to pull requests\. If your project has a Bitbucket webhook, then your app password must have this scope\. ++ **webhook**: Grants access to webhooks\. If your project has a webhook operation, then your app password must have this scope\. + +For more information, see [Scopes for Bitbucket Cloud REST API](https://developer.atlassian.com/cloud/bitbucket/bitbucket-cloud-rest-api-scopes/) and [OAuth on Bitbucket Cloud](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) on the Bitbucket website\. + +### Connect Bitbucket with an app password \(console\) + +To use the console to connect your project to Bitbucket using an app password, do the following when you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. + +1. For **Source provider**, choose **Bitbucket**\. +**Note** +CodeBuild does not support Bitbucket Server\. + +1. For **Repository**, choose **Connect with a Bitbucket app password**\. + +1. In **Bitbucket username**, enter your Bitbucket user name\. + +1. In **Bitbucket app password**, enter your Bitbucket app password\. + +1. Choose **Save Bitbucket credentials**\. + +### Connect Bitbucket with an app password \(CLI\) + +Follow these steps to use the AWS CLI to connect your project to Bitbucket using an app password\. For information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. + +1. Run the import\-source\-credentials command: + + ``` + aws codebuild import-source-credentials --generate-cli-skeleton + ``` + + JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `import-source-credentials.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Modify the copied data as follows, and save your results\. + + ``` + { + "serverType": "BITBUCKET", + "authType": "auth-type", + "shouldOverwrite": "should-overwrite", + "token": "token", + "username": "username" + } + ``` + + Replace the following: + + *auth\-type*: Required value\. The type of authentication used to connect to a Bitbucket repository\. Valid values include PERSONAL\_ACCESS\_TOKEN and BASIC\_AUTH\. You cannot use the CodeBuild API to create an OAUTH connection\. You must use the CodeBuild console instead\. + + *should\-overwrite*: Optional value\. Set to `false` to prevent overwriting the repository source credentials\. Set to `true` to overwrite the repository source credentials\. The default value is `true`\. + + *token*: Required value\. For Bitbucket, this is the app password\. + + *username*: Optional value\. The Bitbucket user name when `authType` is BASIC\_AUTH\. This parameter is ignored for other types of source providers or connections\. + +1. To connect your account with an app password, switch to the directory that contains the `import-source-credentials.json` file you saved in step 1 and run the import\-source\-credentials command again\. + + ``` + aws codebuild import-source-credentials --cli-input-json file://import-source-credentials.json + ``` + + JSON\-formatted data appears in the output with an Amazon Resource Name \(ARN\)\. + + ``` + { + "arn": "arn:aws:codebuild:region:account-id:token/server-type" + } + ``` +**Note** +If you run the import\-source\-credentials command with the same server type and auth type a second time, the stored access token is updated\. + + After your account is connected with an app password, you can use `create-project` to create your CodeBuild project\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. + +1. To view the connected app passwords, run the list\-source\-credentials command\. + + ``` + aws codebuild list-source-credentials + ``` + + A JSON\-formatted `sourceCredentialsInfos` object appears in the output: + + ``` + { + "sourceCredentialsInfos": [ + { + "authType": "auth-type", + "serverType": "BITBUCKET", + "arn": "arn" + } + ] + } + ``` + + The `sourceCredentialsObject` contains a list of connected source credentials information: + + The `authType` is the type of authentication used by credentials\. This can be `OAUTH`, `BASIC_AUTH`, or `PERSONAL_ACCESS_TOKEN`\. + + The `arn` is the ARN of the token\. + +1. To disconnect from a source provider and remove its app password, run the delete\-source\-credentials command with its ARN\. + + ``` + aws codebuild delete-source-credentials --arn arn-of-your-credentials + ``` + + JSON\-formatted data is returned with an ARN of the deleted credentials\. + + ``` + { + "arn": "arn:aws:codebuild:region:account-id:token/server-type" + } + ``` \ No newline at end of file diff --git a/doc_source/advanced-topics.md b/doc_source/advanced-topics.md index 2a94617..3ea57fa 100644 --- a/doc_source/advanced-topics.md +++ b/doc_source/advanced-topics.md @@ -6,4 +6,9 @@ This section includes several advanced topics that are useful to more experience + [Advanced setup](setting-up.md) + [Command line reference for AWS CodeBuild](cmd-ref.md) + [AWS SDKs and tools reference for AWS CodeBuild](sdk-ref.md) -+ [Specify the AWS CodeBuild endpoint](endpoint-specify.md) \ No newline at end of file ++ [Specify the AWS CodeBuild endpoint](endpoint-specify.md) ++ [Run AWS CodeBuild directly](how-to-run.md) ++ [Use AWS CodePipeline with AWS CodeBuild to test code and run builds](how-to-create-pipeline.md) ++ [Use AWS CodeBuild with Jenkins](jenkins-plugin.md) ++ [Use AWS CodeBuild with Codecov](codecov-integration.md) ++ [Use AWS CodeBuild with serverless applications](serverless-applications.md) \ No newline at end of file diff --git a/doc_source/auth-and-access-control-iam-access-control-identity-based.md b/doc_source/auth-and-access-control-iam-access-control-identity-based.md index 1790e4f..9664f48 100644 --- a/doc_source/auth-and-access-control-iam-access-control-identity-based.md +++ b/doc_source/auth-and-access-control-iam-access-control-identity-based.md @@ -67,7 +67,7 @@ A permissions policy describes who has access to which resources\. **Note** This section discusses the use of IAM in AWS CodeBuild\. It doesn't provide detailed information about the IAM service\. For complete IAM documentation, see [What Is IAM?](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) in the *IAM User Guide*\. For information about IAM policy syntax and descriptions, see [AWS IAM Policy Reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) in the *IAM User Guide*\. -Policies attached to an IAM identity are referred to as identity\-based policies \(IAM policies\)\. Policies attached to a resource are referred to as resource\-based policies\. CodeBuild supports identity\-based \(IAM policies\) only\. +Policies attached to an IAM identity are referred to as identity\-based policies \(IAM policies\)\. Policies attached to a resource are referred to as resource\-based policies\. CodeBuild supports identity\-based policies, and resource\-based policies for certain read only APIs for the purpose of cross\-account resource sharing\. ### Identity\-based policies @@ -90,7 +90,7 @@ You can create IAM policies to restrict the calls and resources that users in yo ### Secure access to S3 buckets We strongly recommend that you include the following permissions in your IAM role to verify the S3 bucket associated with your CodeBuild project is owned by you or someone you trust\. These permissions are not included in AWS managed policies and roles\. You must add them yourself\. -+ `s3:GetBucketACL` ++ `s3:GetBucketAcl` + `s3:GetBucketLocation` If the owner of an S3 bucket used by your project changes, you must verify you still own the bucket and update permissions in your IAM role if not\. For more information, see [Add CodeBuild access permissions to an IAM group or IAM user](setting-up.md#setting-up-service-permissions-group) and [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. diff --git a/doc_source/auth-and-access-control-iam-identity-based-access-control.md b/doc_source/auth-and-access-control-iam-identity-based-access-control.md index 83618bd..4f455e0 100644 --- a/doc_source/auth-and-access-control-iam-identity-based-access-control.md +++ b/doc_source/auth-and-access-control-iam-identity-based-access-control.md @@ -55,12 +55,18 @@ The `ListConnectedOAuthAccounts`, `ListRepositories`, and `PersistOAuthToken` AP ## AWS managed \(predefined\) policies for AWS CodeBuild -AWS addresses many common use cases by providing standalone IAM policies that are created and administered by AWS\. These AWS managed policies grant necessary permissions for common use cases so you can avoid having to investigate what permissions are needed\. The managed policies for CodeBuild also provide permissions to perform operations in other serivces, such as IAM, AWS CodeCommit,Amazon EC2, Amazon ECR, Amazon SNS, and Amazon CloudWatch Events, as required for the responsibilities for the users who have been granted the policy in question\. For example, the `AWSCodeBuildAdminAccess` policy is an administrative\-level user policy that allows users with this policy to create and manage CloudWatch Events rules for project builds and Amazon SNS topics for notifications about project\-related events \(topics whose names are prefixed with `arn:aws:codebuild:`\), as well as administer projects and report groups in CodeBuild\. For more information, see [AWS Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*\. +AWS addresses many common use cases by providing standalone IAM policies that are created and administered by AWS\. These AWS managed policies grant necessary permissions for common use cases so you can avoid having to investigate what permissions are needed\. The managed policies for CodeBuild also provide permissions to perform operations in other services, such as IAM, AWS CodeCommit,Amazon EC2, Amazon ECR, Amazon SNS, and Amazon CloudWatch Events, as required for the responsibilities for the users who have been granted the policy in question\. For example, the `AWSCodeBuildAdminAccess` policy is an administrative\-level user policy that allows users with this policy to create and manage CloudWatch Events rules for project builds and Amazon SNS topics for notifications about project\-related events \(topics whose names are prefixed with `arn:aws:codebuild:`\), as well as administer projects and report groups in CodeBuild\. For more information, see [AWS Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*\. The following AWS managed policies, which you can attach to users in your account, are specific to AWS CodeBuild\. -+ `AWSCodeBuildAdminAccess` – Provides full access to CodeBuild including permissions to administrate CodeBuild build projects\. -+ `AWSCodeBuildDeveloperAccess` – Provides access to CodeBuild but does not allow build project administration\. -+ `AWSCodeBuildReadOnlyAccess` – Provides read\-only access to CodeBuild\. + +**AWSCodeBuildAdminAccess** +Provides full access to CodeBuild including permissions to administrate CodeBuild build projects\. + +**AWSCodeBuildDeveloperAccess** +Provides access to CodeBuild but does not allow build project administration\. + +**AWSCodeBuildReadOnlyAccess** +Provides read\-only access to CodeBuild\. To access build output artifacts that CodeBuild creates, you must also attach the AWS managed policy named `AmazonS3ReadOnlyAccess`\. @@ -75,241 +81,318 @@ You can also create your own custom IAM policies to allow permissions for CodeBu ### AWSCodeBuildAdminAccess -`AWSCodeBuildAdminAccess` – Provides full access to CodeBuild, including permissions to administer CodeBuild build projects\. Apply this policy only to administrative\-level users to grant them full control over CodeBuild projects, report groups, and related resources in your AWS account, including the ability to delete projects and report groups\. +The `AWSCodeBuildAdminAccess` policy provides full access to CodeBuild, including permissions to administer CodeBuild build projects\. Apply this policy only to administrative\-level users to grant them full control over CodeBuild projects, report groups, and related resources in your AWS account, including the ability to delete projects and report groups\. The `AWSCodeBuildAdminAccess` policy contains the following policy statement: ``` { - "Version": "2012-10-17", - "Statement": [ - { - "Action": [ - "codebuild:*", - "codecommit:GetBranch", - "codecommit:GetCommit", - "codecommit:GetRepository", - "codecommit:ListBranches", - "codecommit:ListRepositories", - "cloudwatch:GetMetricStatistics", - "ec2:DescribeVpcs", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ecr:DescribeRepositories", - "ecr:ListImages", - "events:DeleteRule", - "events:DescribeRule", - "events:DisableRule", - "events:EnableRule", - "events:ListTargetsByRule", - "events:ListRuleNamesByTarget", - "events:PutRule", - "events:PutTargets", - "events:RemoveTargets", - "logs:GetLogEvents", - "s3:GetBucketLocation", - "s3:ListAllMyBuckets" - ], - "Effect": "Allow", - "Resource": "*" - }, - { - "Action": [ - "logs:DeleteLogGroup" - ], - "Effect": "Allow", - "Resource": "arn:aws:logs:*:*:log-group:/aws/codebuild/*:log-stream:*" - }, - { - "Effect": "Allow", - "Action": [ - "ssm:PutParameter" - ], - "Resource": "arn:aws:ssm:*:*:parameter/CodeBuild/*" - }, - { - "Sid": "CodeStarNotificationsReadWriteAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:CreateNotificationRule", - "codestar-notifications:DescribeNotificationRule", - "codestar-notifications:UpdateNotificationRule", - "codestar-notifications:DeleteNotificationRule", - "codestar-notifications:Subscribe", - "codestar-notifications:Unsubscribe" - ], - "Resource": "*", - "Condition": { - "StringLike": { - "codestar-notifications:NotificationsForResource": "arn:aws:codebuild:*" - } - } - }, - { - "Sid": "CodeStarNotificationsListAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:ListNotificationRules", - "codestar-notifications:ListEventTypes", - "codestar-notifications:ListTargets", - "codestar-notifications:ListTagsforResource" - ], - "Resource": "*" - }, - { - "Sid": "CodeStarNotificationsSNSTopicCreateAccess", - "Effect": "Allow", - "Action": [ - "sns:CreateTopic", - "sns:SetTopicAttributes" - ], - "Resource": "arn:aws:sns:*:*:codestar-notifications*" - }, - { - "Sid": "SNSTopicListAccess", - "Effect": "Allow", - "Action": [ - "sns:ListTopics", - "sns:GetTopicAttributes" - ], - "Resource": "*" + "Version": "2012-10-17", + "Statement": [ + { + "Action": [ + "codebuild:*", + "codecommit:GetBranch", + "codecommit:GetCommit", + "codecommit:GetRepository", + "codecommit:ListBranches", + "codecommit:ListRepositories", + "cloudwatch:GetMetricStatistics", + "ec2:DescribeVpcs", + "ec2:DescribeSecurityGroups", + "ec2:DescribeSubnets", + "ecr:DescribeRepositories", + "ecr:ListImages", + "elasticfilesystem:DescribeFileSystems", + "events:DeleteRule", + "events:DescribeRule", + "events:DisableRule", + "events:EnableRule", + "events:ListTargetsByRule", + "events:ListRuleNamesByTarget", + "events:PutRule", + "events:PutTargets", + "events:RemoveTargets", + "logs:GetLogEvents", + "s3:GetBucketLocation", + "s3:ListAllMyBuckets" + ], + "Effect": "Allow", + "Resource": "*" + }, + { + "Action": [ + "logs:DeleteLogGroup" + ], + "Effect": "Allow", + "Resource": "arn:aws:logs:*:*:log-group:/aws/codebuild/*:log-stream:*" + }, + { + "Effect": "Allow", + "Action": [ + "ssm:PutParameter" + ], + "Resource": "arn:aws:ssm:*:*:parameter/CodeBuild/*" + }, + { + "Effect": "Allow", + "Action": [ + "ssm:StartSession" + ], + "Resource": "arn:aws:ecs:*:*:task/*/*" + }, + { + "Sid": "CodeStarConnectionsReadWriteAccess", + "Effect": "Allow", + "Action": [ + "codestar-connections:CreateConnection", + "codestar-connections:DeleteConnection", + "codestar-connections:UpdateConnectionInstallation", + "codestar-connections:TagResource", + "codestar-connections:UntagResource", + "codestar-connections:ListConnections", + "codestar-connections:ListInstallationTargets", + "codestar-connections:ListTagsForResource", + "codestar-connections:GetConnection", + "codestar-connections:GetIndividualAccessToken", + "codestar-connections:GetInstallationUrl", + "codestar-connections:PassConnection", + "codestar-connections:StartOAuthHandshake", + "codestar-connections:UseConnection" + ], + "Resource": "arn:aws:codestar-connections:*:*:connection/*" + }, + { + "Sid": "CodeStarNotificationsReadWriteAccess", + "Effect": "Allow", + "Action": [ + "codestar-notifications:CreateNotificationRule", + "codestar-notifications:DescribeNotificationRule", + "codestar-notifications:UpdateNotificationRule", + "codestar-notifications:DeleteNotificationRule", + "codestar-notifications:Subscribe", + "codestar-notifications:Unsubscribe" + ], + "Resource": "*", + "Condition": { + "StringLike": { + "codestar-notifications:NotificationsForResource": "arn:aws:codebuild:*" } - ] + } + }, + { + "Sid": "CodeStarNotificationsListAccess", + "Effect": "Allow", + "Action": [ + "codestar-notifications:ListNotificationRules", + "codestar-notifications:ListEventTypes", + "codestar-notifications:ListTargets", + "codestar-notifications:ListTagsforResource" + ], + "Resource": "*" + }, + { + "Sid": "CodeStarNotificationsSNSTopicCreateAccess", + "Effect": "Allow", + "Action": [ + "sns:CreateTopic", + "sns:SetTopicAttributes" + ], + "Resource": "arn:aws:sns:*:*:codestar-notifications*" + }, + { + "Sid": "SNSTopicListAccess", + "Effect": "Allow", + "Action": [ + "sns:ListTopics", + "sns:GetTopicAttributes" + ], + "Resource": "*" + }, + { + "Sid": "CodeStarNotificationsChatbotAccess", + "Effect": "Allow", + "Action": [ + "chatbot:DescribeSlackChannelConfigurations" + ], + "Resource": "*" + } + ] } ``` ### AWSCodeBuildDeveloperAccess -`AWSCodeBuildDeveloperAccess` – Allows access to all of the functionality of CodeBuild and project and report group\-related resources\. This policy does not allow users to delete CodeBuild projects or report groups, or related resources in other AWS services, such as CloudWatch Events\. We recommend that you apply this policy to most users\. +The `AWSCodeBuildDeveloperAccess` policy allows access to all of the functionality of CodeBuild and project and report group\-related resources\. This policy does not allow users to delete CodeBuild projects or report groups, or related resources in other AWS services, such as CloudWatch Events\. We recommend that you apply this policy to most users\. The `AWSCodeBuildDeveloperAccess` policy contains the following policy statement: ``` { - "Statement": [ - { - "Action": [ - "codebuild:StartBuild", - "codebuild:StopBuild", - "codebuild:BatchGet*", - "codebuild:GetResourcePolicy", - "codebuild:DescribeTestCases", - "codebuild:List*", - "codecommit:GetBranch", - "codecommit:GetCommit", - "codecommit:GetRepository", - "codecommit:ListBranches", - "cloudwatch:GetMetricStatistics", - "events:DescribeRule", - "events:ListTargetsByRule", - "events:ListRuleNamesByTarget", - "logs:GetLogEvents", - "s3:GetBucketLocation", - "s3:ListAllMyBuckets" - ], - "Effect": "Allow", - "Resource": "*" - }, - { - "Effect": "Allow", - "Action": [ - "ssm:PutParameter" - ], - "Resource": "arn:aws:ssm:*:*:parameter/CodeBuild/*" - }, - { - "Sid": "CodeStarNotificationsReadWriteAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:CreateNotificationRule", - "codestar-notifications:DescribeNotificationRule", - "codestar-notifications:UpdateNotificationRule", - "codestar-notifications:Subscribe", - "codestar-notifications:Unsubscribe" - ], - "Resource": "*", - "Condition": { - "StringLike": { - "codestar-notifications:NotificationsForResource": "arn:aws:codebuild:*" - } - } - }, - { - "Sid": "CodeStarNotificationsListAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:ListNotificationRules", - "codestar-notifications:ListEventTypes", - "codestar-notifications:ListTargets", - "codestar-notifications:ListTagsforResource" - ], - "Resource": "*" - }, - { - "Sid": "SNSTopicListAccess", - "Effect": "Allow", - "Action": [ - "sns:ListTopics", - "sns:GetTopicAttributes" - ], - "Resource": "*" + "Statement": [ + { + "Action": [ + "codebuild:StartBuild", + "codebuild:StopBuild", + "codebuild:StartBuildBatch", + "codebuild:StopBuildBatch", + "codebuild:RetryBuild", + "codebuild:RetryBuildBatch", + "codebuild:BatchGet*", + "codebuild:GetResourcePolicy", + "codebuild:DescribeTestCases", + "codebuild:DescribeCodeCoverages", + "codebuild:List*", + "codecommit:GetBranch", + "codecommit:GetCommit", + "codecommit:GetRepository", + "codecommit:ListBranches", + "cloudwatch:GetMetricStatistics", + "events:DescribeRule", + "events:ListTargetsByRule", + "events:ListRuleNamesByTarget", + "logs:GetLogEvents", + "s3:GetBucketLocation", + "s3:ListAllMyBuckets" + ], + "Effect": "Allow", + "Resource": "*" + }, + { + "Effect": "Allow", + "Action": [ + "ssm:PutParameter" + ], + "Resource": "arn:aws:ssm:*:*:parameter/CodeBuild/*" + }, + { + "Effect": "Allow", + "Action": [ + "ssm:StartSession" + ], + "Resource": "arn:aws:ecs:*:*:task/*/*" + }, + { + "Sid": "CodeStarConnectionsUserAccess", + "Effect": "Allow", + "Action": [ + "codestar-connections:ListConnections", + "codestar-connections:GetConnection" + ], + "Resource": "arn:aws:codestar-connections:*:*:connection/*" + }, + { + "Sid": "CodeStarNotificationsReadWriteAccess", + "Effect": "Allow", + "Action": [ + "codestar-notifications:CreateNotificationRule", + "codestar-notifications:DescribeNotificationRule", + "codestar-notifications:UpdateNotificationRule", + "codestar-notifications:Subscribe", + "codestar-notifications:Unsubscribe" + ], + "Resource": "*", + "Condition": { + "StringLike": { + "codestar-notifications:NotificationsForResource": "arn:aws:codebuild:*" } - ], - "Version": "2012-10-17" + } + }, + { + "Sid": "CodeStarNotificationsListAccess", + "Effect": "Allow", + "Action": [ + "codestar-notifications:ListNotificationRules", + "codestar-notifications:ListEventTypes", + "codestar-notifications:ListTargets", + "codestar-notifications:ListTagsforResource" + ], + "Resource": "*" + }, + { + "Sid": "SNSTopicListAccess", + "Effect": "Allow", + "Action": [ + "sns:ListTopics", + "sns:GetTopicAttributes" + ], + "Resource": "*" + }, + { + "Sid": "CodeStarNotificationsChatbotAccess", + "Effect": "Allow", + "Action": [ + "chatbot:DescribeSlackChannelConfigurations" + ], + "Resource": "*" + } + ], + "Version": "2012-10-17" } ``` ### AWSCodeBuildReadOnlyAccess -`AWSCodeBuildReadOnlyAccess` – Grants read\-only access to CodeBuild and related resources in other AWS services\. Apply this policy to users who can view and run builds, view projects, and view report groups, but cannot make any changes to them\. +The `AWSCodeBuildReadOnlyAccess` policy grants read\-only access to CodeBuild and related resources in other AWS services\. Apply this policy to users who can view and run builds, view projects, and view report groups, but cannot make any changes to them\. The `AWSCodeBuildReadOnlyAccess` policy contains the following policy statement: ``` { - "Statement": [ - { - "Action": [ - "codebuild:BatchGet*", - "codebuild:GetResourcePolicy", - "codebuild:List*", - "codebuild:DescribeTestCases", - "codecommit:GetBranch", - "codecommit:GetCommit", - "codecommit:GetRepository", - "cloudwatch:GetMetricStatistics", - "events:DescribeRule", - "events:ListTargetsByRule", - "events:ListRuleNamesByTarget", - "logs:GetLogEvents" - ], - "Effect": "Allow", - "Resource": "*" - }, - { - "Sid": "CodeStarNotificationsPowerUserAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:DescribeNotificationRule" - ], - "Resource": "*", - "Condition": { - "StringLike": { - "codestar-notifications:NotificationsForResource": "arn:aws:codebuild:*" - } - } - }, - { - "Sid": "CodeStarNotificationsListAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:ListNotificationRules", - "codestar-notifications:ListEventTypes" - ], - "Resource": "*" + "Statement": [ + { + "Action": [ + "codebuild:BatchGet*", + "codebuild:GetResourcePolicy", + "codebuild:List*", + "codebuild:DescribeTestCases", + "codebuild:DescribeCodeCoverages", + "codecommit:GetBranch", + "codecommit:GetCommit", + "codecommit:GetRepository", + "cloudwatch:GetMetricStatistics", + "events:DescribeRule", + "events:ListTargetsByRule", + "events:ListRuleNamesByTarget", + "logs:GetLogEvents" + ], + "Effect": "Allow", + "Resource": "*" + }, + { + "Sid": "CodeStarConnectionsUserAccess", + "Effect": "Allow", + "Action": [ + "codestar-connections:ListConnections", + "codestar-connections:GetConnection" + ], + "Resource": "arn:aws:codestar-connections:*:*:connection/*" + }, + { + "Sid": "CodeStarNotificationsPowerUserAccess", + "Effect": "Allow", + "Action": [ + "codestar-notifications:DescribeNotificationRule" + ], + "Resource": "*", + "Condition": { + "StringLike": { + "codestar-notifications:NotificationsForResource": "arn:aws:codebuild:*" } - ], - "Version": "2012-10-17" + } + }, + { + "Sid": "CodeStarNotificationsListAccess", + "Effect": "Allow", + "Action": [ + "codestar-notifications:ListNotificationRules", + "codestar-notifications:ListEventTypes", + "codestar-notifications:ListTargets" + ], + "Resource": "*" + } + ], + "Version": "2012-10-17" } ``` @@ -549,12 +632,12 @@ The following example policy statement allows a user to create build projects wi { "Effect": "Allow", "Action": "codebuild:CreateProject", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/*" + "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/*" }, { "Effect": "Allow", "Action": "iam:PassRole", - "Resource": "arn:aws:iam:123456789012:role/CodeBuildServiceRole" + "Resource": "arn:aws:iam::123456789012:role/CodeBuildServiceRole" } ] } @@ -661,7 +744,7 @@ The following example policy statement allows a user to change information about { "Effect": "Allow", "Action": "iam:PassRole", - "Resource": "arn:aws:iam:123456789012:role/CodeBuildServiceRole" + "Resource": "arn:aws:iam::123456789012:role/CodeBuildServiceRole" } ] } @@ -883,38 +966,40 @@ The following example policy statement grants AWS CodeBuild permission to create ``` { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "ec2:CreateNetworkInterface", - "ec2:DescribeDhcpOptions", - "ec2:DescribeNetworkInterfaces", - "ec2:DeleteNetworkInterface", - "ec2:DescribeSubnets", - "ec2:DescribeSecurityGroups", - "ec2:DescribeVpcs" - ], - "Resource": "*" + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:CreateNetworkInterface", + "ec2:DescribeDhcpOptions", + "ec2:DescribeNetworkInterfaces", + "ec2:DeleteNetworkInterface", + "ec2:DescribeSubnets", + "ec2:DescribeSecurityGroups", + "ec2:DescribeVpcs" + ], + "Resource": "*" + }, + { + "Effect": "Allow", + "Action": [ + "ec2:CreateNetworkInterfacePermission" + ], + "Resource": "arn:aws:ec2:region:account-id:network-interface/*", + "Condition": { + "StringEquals": { + "ec2:AuthorizedService": "codebuild.amazonaws.com" }, - { - "Effect": "Allow", - "Action": [ - "ec2:CreateNetworkInterfacePermission" - ], - "Resource": "arn:aws:ec2:region:account-id:network-interface/*", - "Condition": { - "StringEquals": { - "ec2:Subnet": [ - "arn:aws:ec2:region:account-id:subnet/subnet-id-1", - "arn:aws:ec2:region:account-id:subnet/subnet-id-2" - ], - "ec2:AuthorizedService": "codebuild.amazonaws.com" - } - } + "ArnEquals": { + "ec2:Subnet": [ + "arn:aws:ec2:region:account-id:subnet/subnet-id-1", + "arn:aws:ec2:region:account-id:subnet/subnet-id-2" + ] } - ] + } + } + ] } ``` diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index dce479b..364ab35 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -12,71 +12,74 @@ You specify an ARN, with or without a wildcard character \(\*\), as the resource ``` arn:aws:codebuild:us-east-2:123456789012:project/my* -``` - - CodeBuild API operations and required permissions for actions +```CodeBuild API operations and required permissions for actions BatchDeleteBuilds **Action:** `codebuild:BatchDeleteBuilds` Required to delete builds\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` BatchGetBuilds **Action:** `codebuild:BatchGetBuilds` Required to get information about builds\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` BatchGetProjects **Action:** `codebuild:BatchGetProjects` Required to get information about build projects\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` BatchGetReportGroups **Action:** `codebuild:BatchGetReportGroups` Required to get information about report groups\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` BatchGetReports **Action:** `codebuild:BatchGetReports` Required to get information about reports\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` BatchPutTestCases ¹ **Action:** `codebuild:BatchPutTestCases` Required to create or update a test report\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` CreateProject **Actions:** `codebuild:CreateProject`, `iam:PassRole` Required to create build projects\. **Resources:** -+ `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` -+ `arn:aws:iam:account-ID:role/ role-name ` ++ `arn:aws:codebuild:region-ID:account-ID:project/project-name ` ++ `arn:aws:iam::account-ID:role/role-name ` CreateReport ¹ **Action:** `codebuild:CreateReport` Required to create a test report\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` CreateReportGroup **Action:** `codebuild:CreateReportGroup` Required to create a report group\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` CreateWebhook **Action:** `codebuild:CreateWebhook` Required to create a webhook\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` + +DeleteProject + **Action:** `codebuild:DeleteProject` +Required to delete a CodeBuild project\. + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` DeleteReport **Action:** `codebuild:DeleteReport` Required to delete a report\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` DeleteReportGroup **Action:** `codebuild:DeleteReportGroup` Required to delete a report group\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` DeleteSourceCredentials **Action:** `codebuild:DeleteSourceCredentials` @@ -86,12 +89,12 @@ Required to delete a set of `SourceCredentialsInfo` objects that contain informa DeleteWebhook **Action:** `codebuild:DeleteWebhook` Required to create a webhook\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` DescribeTestCases **Action:** `codebuild:DescribeTestCases` Required to return a paginated list of test cases\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` ImportSourceCredentials **Action:** `codebuild:ImportSourceCredentials` @@ -101,7 +104,17 @@ Required to import a set of `SourceCredentialsInfo` objects that contain informa InvalidateProjectCache **Action:** `codebuild:InvalidateProjectCache` Required to reset the cache for a project\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` + +ListBuildBatches + **Action:** `codebuild:ListBuildBatches` +Required to get a list of build batch IDs\. + **Resource:** `*` + +ListBuildBatchesForProject + **Action:** `codebuild:ListBuildBatchesForProject` +Required to get a list of build batch IDs for a specific project\. + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name` ListBuilds **Action:** `codebuild:ListBuilds` @@ -111,7 +124,7 @@ Required to get a list of build IDs\. ListBuildsForProject **Action:** `codebuild:ListBuildsForProject` Required to get a list of build IDs for a build project\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` ListCuratedEnvironmentImages **Action:** `codebuild:ListCuratedEnvironmentImages` @@ -136,38 +149,50 @@ Required to get a list of reports\. ListReportsForReportGroup **Action:** `codebuild:ListReportsForReportGroup` Required to get a list of reports for a report group\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` + +RetryBuild +**Action:** `codebuild:RetryBuild` +Required to retry builds\. +**Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` StartBuild **Action:** `codebuild:StartBuild` Required to start running builds\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` StopBuild **Action:** `codebuild:StopBuild` Required to attempt to stop running builds\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` UpdateProject **Actions:** `codebuild:UpdateProject`, `iam:PassRole` Required to change information about builds\. **Resources:** -+ `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` -+ `arn:aws:iam:account-ID:role/ role-name ` ++ `arn:aws:codebuild:region-ID:account-ID:project/project-name ` ++ `arn:aws:iam::account-ID:role/role-name ` + +UpdateProjectVisibility + **Actions:** `codebuild:UpdateProjectVisibility`, `iam:PassRole` +Required to change the public visibility of a project's builds\. + **Resources:** ++ `arn:aws:codebuild:region-ID:account-ID:project/project-name ` ++ `arn:aws:iam::account-ID:role/role-name ` UpdateReport ¹ **Action:** `codebuild:UpdateReport` Required to create or update a test report\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` UpdateReportGroup **Action:** `codebuild:UpdateReportGroup` Required to update a report group\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` UpdateWebhook **Action:** `codebuild:UpdateWebhook` Required to update a webhook\. - **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` + **Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name ` ¹ Used for permission only\. There is no API for this action\. \ No newline at end of file diff --git a/doc_source/auth-and-access-control-using-tags.md b/doc_source/auth-and-access-control-using-tags.md index 97e65d0..8fdc271 100644 --- a/doc_source/auth-and-access-control-using-tags.md +++ b/doc_source/auth-and-access-control-using-tags.md @@ -2,7 +2,7 @@ Conditions in IAM policy statements are part of the syntax that you can use to specify permissions to CodeBuild project\-based actions\. You can create a policy that allows or denies actions on projects based on the tags associated with those projects, and then apply those policies to the IAM groups you configure for managing IAM users\. For information about applying tags to a project using the console or AWS CLI, see [Create a build project in AWS CodeBuild](create-project.md)\. For information about applying tags using the CodeBuild SDK, see [CreateProject ](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CreateProject.html#API_CreateProject_RequestSyntax) and [Tags](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Tag.html) in the *CodeBuild API Reference*\. For information about using tags to control access to AWS resources, see [Controlling Access to AWS Resources Using Resource Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*\. -**Example Example 1: Limit CodeBuild project actions based on resource tags** +**Example 1: Limit CodeBuild project actions based on resource tags** The following example denies all `BatchGetProjects` actions on projects tagged with the key `Environment` with the key value of `Production`\. A user's administrator must attach this IAM policy in addition to the managed user policy to unauthorized IAM users\. The `aws:ResourceTag` condition key is used to control access to resources based on their tags\. ``` @@ -25,7 +25,7 @@ Conditions in IAM policy statements are part of the syntax that you can use to s } ``` -**Example Example 2: Limit CodeBuild project actions based on request tags** +**Example 2: Limit CodeBuild project actions based on request tags** The following policy denies users permission to the `CreateProject` action if the request contains a tag with the key `Environment` and the key value `Production`\. In addition, the policy prevents these unauthorized users from modifying projects by using the `aws:TagKeys` condition key to not allow `UpdateProject` if the request contains a tag with the key `Environment`\. An administrator must attach this IAM policy in addition to the managed user policy to users who are not authorized to perform these actions\. The `aws:RequestTag` condition key is used to control which tags can be passed in an IAM request ``` @@ -60,7 +60,7 @@ The following policy denies users permission to the `CreateProject` action if th } ``` -**Example Example 3: Deny or allow actions on report groups based on resource tags** +**Example 3: Deny or allow actions on report groups based on resource tags** You can create a policy that allows or denies actions on CodeBuild resources \(projects and report groups\) based on the AWS tags associated with those resources, and then apply those policies to the IAM groups you configure for managing IAM users\. For example, you can create a policy that denies all CodeBuild actions on any report group with the AWS tag key `Status` and the key value of `Secret`, and then apply that policy to the IAM group you created for general developers \(*Developers*\)\. You then need to make sure that the developers working on those tagged report groups are not members of that general *Developers* group, but belong instead to a different IAM group that does not have the restrictive policy applied \(`SecretDevelopers`\)\. The following example denies all CodeBuild actions on report groups tagged with the key `Status` and the key value of `Secret`: @@ -87,7 +87,7 @@ The following example denies all CodeBuild actions on report groups tagged with } ``` -**Example Example 4: Limit CodeBuild actions to AWSCodeBuildDeveloperAccess based on resource tags** +**Example 4: Limit CodeBuild actions to AWSCodeBuildDeveloperAccess based on resource tags** You can create policies that allow CodeBuild actions on all report groups and projects that are not tagged with specific tags\. For example, the following policy allows the equivalent of [AWSCodeBuildDeveloperAccess](auth-and-access-control-iam-identity-based-access-control.md#developer-access-policy) permissions for all report groups and projects except those tagged with the specified tags: ``` diff --git a/doc_source/available-runtimes.md b/doc_source/available-runtimes.md new file mode 100644 index 0000000..7003c5d --- /dev/null +++ b/doc_source/available-runtimes.md @@ -0,0 +1,33 @@ +# Available runtimes + +You can specify one or more runtimes in the `runtime-versions` section of your buildspec file\. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file\. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use\. If you specify one or more runtimes, CodeBuild uses only those runtimes\. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you\. For more information, see [Specify runtime versions in the buildspec file](build-spec-ref.md#runtime-versions-buildspec-file)\. + +**Topics** ++ [Linux image runtimes](#linux-runtimes) ++ [Windows image runtimes](#windows-runtimes) + +## Linux image runtimes + +The following table contains the available runtimes and the standard Linux images that support them\. + + +**Ubuntu and Amazon Linux 2 platform runtimes** +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/available-runtimes.html) + +## Windows image runtimes + +The base image of the Windows Server Core 2019 contains the following runtimes\. + + +**Windows platform runtimes** + +| Runtime name | Versions available in `windows-base:2019-1.0` | Versions available in `windows-base:2019-2.0` | +| --- | --- | --- | +| dotnet | 3\.1\.4045\.0 | 3\.1\.4196\.0\.300 | +| golang | 1\.14 | 1\.18\.2 | +| nodejs | 12\.18 | 16\.15\.0 | +| java | corretto11 | corretto11corretto17 | +| php | 7\.4\.7 | 8\.1\.6 | +| powershell | 7\.0\.2 | 7\.2\.4 | +| python | 3\.8\.3 | 3\.10\.4 | +| ruby | 2\.7 | 3\.1\.1\.1 | \ No newline at end of file diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md new file mode 100644 index 0000000..46e1415 --- /dev/null +++ b/doc_source/batch-build-buildspec.md @@ -0,0 +1,200 @@ +# Batch build buildspec reference + +This topic contains the buildspec reference for batch build properties\. + +## batch + +Optional mapping\. The batch build settings for the project\. + +batch/**fast\-fail** +Optional\. Specifies the behavior of the batch build when one or more build tasks fail\. +`false` +The default value\. All running builds will complete\. +`true` +All running builds will be stopped when one of the build tasks fails\. + +By default, all batch build tasks run with the build settings such as `env` and `phases`, specified in the buildspec file\. You can override the default build settings by specifying different `env` values or a different buildspec file in the `batch//buildspec` parameter\. + +The contents of the `batch` property varies based on the type of batch build being specified\. The possible batch build types are: ++ [`batch/build-graph`](#build-spec.batch.build-graph) ++ [`batch/build-list`](#build-spec.batch.build-list) ++ [`batch/build-matrix`](#build-spec.batch.build-matrix) + +## `batch/build-graph` + +Defines a *build graph*\. A build graph defines a set of tasks that have dependencies on other tasks in the batch\. For more information, see [Build graph](batch-build.md#batch_build_graph)\. + +This element contains an array of build tasks\. Each build task contains the following properties\. + +**identifier** +Required\. The identifier of the task\. + +**buildspec** +Optional\. The path and file name of the buildspec file to use for this task\. If this parameter is not specified, the current buildspec file is used\. + +**debug\-session** +Optional\. A Boolean value that indicates whether session debugging is enabled for this batch build\. For more information about session debugging, see [View a running build in Session Manager](session-manager.md)\. +`false` +Session debugging is disabled\. +`true` +Session debugging is enabled\. + +**depend\-on** +Optional\. An array of task identifiers that this task depends on\. This task will not run until these tasks are completed\. + +**env** +Optional\. The build environment overrides for the task\. This can contain the following properties: +**compute\-type** +The identifier of the compute type to use for the task\. See **computeType** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. +**image** +The identifier of the image to use for the task\. See **Image identifier** in [Docker images provided by CodeBuild](build-env-ref-available.md) for possible values\. +**privileged\-mode** +A Boolean value that indicates whether to run the Docker daemon inside a Docker container\. Set to `true` only if the build project is used to build Docker images\. Otherwise, a build that attempts to interact with the Docker daemon fails\. The default setting is `false`\. +**type** +The identifier of the environment type to use for the task\. See **Environment type** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. +**variables** +The environment variables that will be present in the build environment\. See [env/variables](build-spec-ref.md#build-spec.env.variables) for more information\. + +**ignore\-failure** +Optional\. A Boolean value that indicates if a failure of this build task can be ignored\. +`false` +The default value\. If this build task fails, the batch build will fail\. +`true` +If this build task fails, the batch build can still succeed\. + +The following is an example of a build graph buildspec entry: + +``` +batch: + fast-fail: false + build-graph: + - identifier: build1 + env: + variables: + BUILD_ID: build1 + ignore-failure: false + - identifier: build2 + buildspec: build2.yml + env: + variables: + BUILD_ID: build2 + depend-on: + - build1 + - identifier: build3 + env: + variables: + BUILD_ID: build3 + depend-on: + - build2 +``` + +## `batch/build-list` + +Defines a *build list*\. A build list is used to define a number of tasks that run in parallel\. For more information, see [Build list](batch-build.md#batch_build_list)\. + +This element contains an array of build tasks\. Each build task contains the following properties\. + +**identifier** +Required\. The identifier of the task\. + +**buildspec** +Optional\. The path and file name of the buildspec file to use for this task\. If this parameter is not specified, the current buildspec file is used\. + +**debug\-session** +Optional\. A Boolean value that indicates whether session debugging is enabled for this batch build\. For more information about session debugging, see [View a running build in Session Manager](session-manager.md)\. +`false` +Session debugging is disabled\. +`true` +Session debugging is enabled\. + +**env** +Optional\. The build environment overrides for the task\. This can contain the following properties: +**compute\-type** +The identifier of the compute type to use for the task\. See **computeType** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. +**image** +The identifier of the image to use for the task\. See **Image identifier** in [Docker images provided by CodeBuild](build-env-ref-available.md) for possible values\. +**privileged\-mode** +A Boolean value that indicates whether to run the Docker daemon inside a Docker container\. Set to `true` only if the build project is used to build Docker images\. Otherwise, a build that attempts to interact with the Docker daemon fails\. The default setting is `false`\. +**type** +The identifier of the environment type to use for the task\. See **Environment type** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. +**variables** +The environment variables that will be present in the build environment\. See [env/variables](build-spec-ref.md#build-spec.env.variables) for more information\. + +**ignore\-failure** +Optional\. A Boolean value that indicates if a failure of this build task can be ignored\. +`false` +The default value\. If this build task fails, the batch build will fail\. +`true` +If this build task fails, the batch build can still succeed\. + +The following is an example of a build list buildspec entry: + +``` +batch: + fast-fail: false + build-list: + - identifier: build1 + env: + variables: + BUILD_ID: build1 + ignore-failure: false + - identifier: build2 + buildspec: build2.yml + env: + variables: + BUILD_ID: build2 + ignore-failure: true +``` + +## `batch/build-matrix` + +Defines a *build matrix*\. A build matrix defines tasks with different configurations that run in parallel\. CodeBuild creates a separate build for each possible configuration combination\. For more information, see [Build matrix](batch-build.md#batch_build_matrix)\. + +**static** +The static properties apply to all build tasks\. +**ignore\-failure** +Optional\. A Boolean value that indicates if a failure of this build task can be ignored\. +`false` +The default value\. If this build task fails, the batch build will fail\. +`true` +If this build task fails, the batch build can still succeed\. +**env** +Optional\. The build environment overrides for all tasks\. +**privileged\-mode** +A Boolean value that indicates whether to run the Docker daemon inside a Docker container\. Set to `true` only if the build project is used to build Docker images\. Otherwise, a build that attempts to interact with the Docker daemon fails\. The default setting is `false`\. +**type** +The identifier of the environment type to use for the task\. See **Environment type** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. + +**dynamic** +The dynamic properties define the build matrix\. +**buildspec** +Optional\. An array that contains the path and file names of the buildspec files to use for these tasks\. If this parameter is not specified, the current buildspec file is used\. +**env** +Optional\. The build environment overrides for these tasks\. +**compute\-type** +An array that contains the identifiers of the compute types to use for these tasks\. See **computeType** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. +**image** +An array that contains the identifiers of the images to use for these tasks\. See **Image identifier** in [Docker images provided by CodeBuild](build-env-ref-available.md) for possible values\. +**variables** +An array that contains the environment variables that will be present in the build environments for these tasks\. See [env/variables](build-spec-ref.md#build-spec.env.variables) for more information\. + +The following is an example of a build matrix buildspec entry: + +``` +batch: + build-matrix: + static: + ignore-failure: false + dynamic: + buildspec: + - matrix1.yml + - matrix2.yml + env: + variables: + MY_VAR: + - VALUE1 + - VALUE2 + - VALUE3 +``` + +For more information, see [Build matrix](batch-build.md#batch_build_matrix)\. \ No newline at end of file diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md new file mode 100644 index 0000000..5119cff --- /dev/null +++ b/doc_source/batch-build.md @@ -0,0 +1,143 @@ +# Batch builds in AWS CodeBuild + +You can use AWS CodeBuild to run concurrent and coordinated builds of a project with batch builds\. + +**Topics** ++ [Security role](#batch_security_role) ++ [Batch build types](#batch_build_types) ++ [Batch report mode](#batch-report-mode) ++ [More information](#batch_more_info) + +## Security role + +Batch builds introduce a new security role in the batch configuration\. This new role is required as CodeBuild must be able to call the `StartBuild`, `StopBuild`, and `RetryBuild` actions on your behalf to run builds as part of a batch\. Customers should use a new role, and not the same role they use in their build, for two reasons: ++ Giving the build role `StartBuild`, `StopBuild`, and `RetryBuild` permissions would allow a single build to start more builds via the buildspec\. ++ CodeBuild batch builds provide restrictions that restrict the number of builds and compute types that can be used for the builds in the batch\. If the build role has these permissions, it is possible the builds themselves could bypass these restrictions\. + +## Batch build types + +CodeBuild supports the following batch build types: + +**Topics** ++ [Build graph](#batch_build_graph) ++ [Build list](#batch_build_list) ++ [Build matrix](#batch_build_matrix) + +### Build graph + +A build graph defines a set of tasks that have dependencies on other tasks in the batch\. + +The following example defines a build graph that creates a dependency chain\. + +``` +batch: + fast-fail: false + build-graph: + - identifier: build1 + env: + variables: + BUILD_ID: build1 + ignore-failure: false + - identifier: build2 + buildspec: build2.yml + env: + variables: + BUILD_ID: build2 + depend-on: + - build1 + - identifier: build3 + env: + variables: + BUILD_ID: build3 + depend-on: + - build2 +``` + +In this example: ++ `build1` runs first because it has no dependencies\. ++ `build2` has a dependency on `build1`, so `build2` runs after `build1` completes\. ++ `build3` has a dependency on `build2`, so `build3` runs after `build2` completes\. + +For more information about the build graph buildspec syntax, see [`batch/build-graph`](batch-build-buildspec.md#build-spec.batch.build-graph)\. + +### Build list + +A build list defines a number of tasks that run in parallel\. + +The following example defines a build list\. The `build1` and `build2` builds will run in parallel\. + +``` +batch: + fast-fail: false + build-list: + - identifier: build1 + env: + variables: + BUILD_ID: build1 + ignore-failure: false + - identifier: build2 + buildspec: build2.yml + env: + variables: + BUILD_ID: build2 + ignore-failure: true +``` + +For more information about the build list buildspec syntax, see [`batch/build-list`](batch-build-buildspec.md#build-spec.batch.build-list)\. + +### Build matrix + +A build matrix defines tasks with different configurations that run in parallel\. CodeBuild creates a separate build for each possible configuration combination\. + +The following example shows a build matrix with two buildspec files and three values for an environment variable\. + +``` +batch: + build-matrix: + static: + ignore-failure: false + dynamic: + buildspec: + - matrix1.yml + - matrix2.yml + env: + variables: + MY_VAR: + - VALUE1 + - VALUE2 + - VALUE3 +``` + +In this example, CodeBuild creates six builds: ++ `matrix1.yml` with `$MY_VAR=VALUE1` ++ `matrix1.yml` with `$MY_VAR=VALUE2` ++ `matrix1.yml` with `$MY_VAR=VALUE3` ++ `matrix2.yml` with `$MY_VAR=VALUE1` ++ `matrix2.yml` with `$MY_VAR=VALUE2` ++ `matrix2.yml` with `$MY_VAR=VALUE3` + +Each build will have the following settings: ++ `ignore-failure` set to `false` ++ `env/type` set to `LINUX_CONTAINER` ++ `env/image` set to `aws/codebuild/amazonlinux2-x86_64-standard:3.0` ++ `env/privileged-mode` set to `true` + +These builds run in parallel\. + +For more information about the build matrix buildspec syntax, see [`batch/build-matrix`](batch-build-buildspec.md#build-spec.batch.build-matrix)\. + +## Batch report mode + +If the source provider for your project is Bitbucket, GitHub, or GitHub Enterprise, and your project is configured to report build statuses to the source provider, you can select how you want your batch build statuses sent to the source provider\. You can select to have the statuses sent as a single aggregate status report for the batch, or have the status of each build in the batch reported individually\. + +For more information, see the following topics: ++ [Batch configuration \(create\)](create-project-console.md#create-project-console-batch-config) ++ [Batch configuration \(update\)](change-project-console.md#change-project-console-batch-config) + +## More information + +For more information, see the following topics: ++ [Batch build buildspec reference](batch-build-buildspec.md) ++ [Batch configuration](create-project-console.md#create-project-console-batch-config) ++ [Run a batch build \(AWS CLI\)](run-batch-build-cli.md) ++ [Stop a batch build in AWS CodeBuild](stop-batch-build.md) \ No newline at end of file diff --git a/doc_source/bitbucket-webhook.md b/doc_source/bitbucket-webhook.md new file mode 100644 index 0000000..f754b8e --- /dev/null +++ b/doc_source/bitbucket-webhook.md @@ -0,0 +1,247 @@ +# Bitbucket webhook events + +You can use webhook filter groups to specify which Bitbucket webhook events trigger a build\. For example, you can specify that a build is only triggered for changes to specific branches\. + +You can specify more than one webhook filter group\. A build is triggered if the filters on one or more filter groups evaluate to true\. When you create a filter group, you specify: + +**An event** +For Bitbucket, you can choose one or more of the following events: ++ `PUSH` ++ `PULL_REQUEST_CREATED` ++ `PULL_REQUEST_UPDATED` ++ `PULL_REQUEST_MERGED` +The webhook's event type is in its header in the `X-Event-Key` field\. The following table shows how `X-Event-Key` header values map to the event types\. +You must enable the `merged` event in your Bitbucket webhook setting if you create a webhook filter group that uses the `PULL_REQUEST_MERGED` event type\. +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/bitbucket-webhook.html) +For `PULL_REQUEST_MERGED`, if a pull request is merged with the squash strategy and the pull request branch is closed, the original pull request commit no longer exists\. In this case, the `CODEBUILD_WEBHOOK_MERGE_COMMIT` environment variable contains the identifier of the squashed merge commit\. + +**One or more optional filters** +Use a regular expression to specify a filter\. For an event to trigger a build, every filter associated with it must evaluate to true\. +`ACTOR_ACCOUNT_ID` \(`ACTOR_ID` in the console\) +A webhook event triggers a build when a Bitbucket account ID matches the regular expression pattern\. This value appears in the `account_id` property of the `actor` object in the webhook filter payload\. +`HEAD_REF` +A webhook event triggers a build when the head reference matches the regular expression pattern \(for example, `refs/heads/branch-name` and `refs/tags/tag-name`\)\. A `HEAD_REF` filter evaluates the Git reference name for the branch or tag\. The branch or tag name appears in the `name` field of the `new` object in the `push` object of the webhook payload\. For pull request events, the branch name appears in the `name` field in the `branch` object of the `source` object in the webhook payload\. +`BASE_REF` +A webhook event triggers a build when the base reference matches the regular expression pattern\. A `BASE_REF` filter works with pull request events only \(for example, `refs/heads/branch-name`\)\. A `BASE_REF` filter evaluates the Git reference name for the branch\. The branch name appears in the `name` field of the `branch` object in the `destination` object in the webhook payload\. +`FILE_PATH` +A webhook triggers a build when the path of a changed file matches the regular expression pattern\. +`COMMIT_MESSAGE` +A webhook triggers a build when the head commit message matches the regular expression pattern\. + +**Note** +You can find the webhook payload in the webhook settings of your Bitbucket repository\. + +**Topics** ++ [Filter Bitbucket webhook events \(console\)](#bitbucket-webhook-events-console) ++ [Filter Bitbucket webhook events \(SDK\)](#bitbucket-webhook-events-sdk) ++ [Filter Bitbucket webhook events \(AWS CloudFormation\)](#bitbucket-webhook-events-cfn) + +## Filter Bitbucket webhook events \(console\) + + To use the AWS Management Console to filter webhook events: + +1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. + +1. From **Event type**, choose one or more events\. + +1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters\. + +1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters\. + +1. Choose **Add filter group** to add another filter group\. + + For more information, see [Create a build project \(console\)](create-project-console.md) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. + +In this example, a webhook filter group triggers a build for pull requests only: + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +Using an example of two filter groups, a build is triggered when one or both evaluate to true: ++ The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/branch1!`\. ++ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build for all requests except tag events\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build only when a change is made by a Bitbucket user who does not have an account ID that matches the regular expression `actor-account-id`\. + +**Note** + For information about how to find your Bitbucket account ID, see https://api\.bitbucket\.org/2\.0/users/*user\-name*, where *user\-name* is your Bitbucket user name\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +## Filter Bitbucket webhook events \(SDK\) + + To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods\. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*\. + + To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" + } + ] +] +``` + + To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names\. Using an example of two filter groups, a build is triggered when one or both evaluate to true: ++ The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/myBranch$`\. ++ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/heads/myBranch$" + }, + { + "type": "BASE_REF", + "pattern": "^refs/heads/main$" + } + ], + [ + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/heads/myBranch$" + } + ] +] +``` + + You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build\. In this example, a build is triggered for all requests except tag events\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/tags/.*", + "excludeMatchedPattern": true + } + ] +] +``` + +You can create a filter that triggers a build only when a change is made by a Bitbucket user with account ID `actor-account-id`\. + +**Note** + For information about how to find your Bitbucket account ID, see https://api\.bitbucket\.org/2\.0/users/*user\-name*, where *user\-name* is your Bitbucket user name\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" + }, + { + "type": "ACTOR_ACCOUNT_ID", + "pattern": "actor-account-id" + } + ] +] +``` + +You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change\. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "FILE_PATH", + "pattern": "^buildspec.*" + } + ] +] +``` + +You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument\. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`\. + +``` + "filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "COMMIT_MESSAGE", + "pattern": "\[CodeBuild\]" + } + ] + ] +``` + +## Filter Bitbucket webhook events \(AWS CloudFormation\) + + To use an AWS CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property\. The following YAML\-formatted portion of an AWS CloudFormation template creates two filter groups\. Together, they trigger a build when one or both evaluate to true: ++ The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a Bitbucket user who does not have account ID `12345`\. ++ The second filter group specifies push requests are created on branches with Git reference names that match the regular expression `^refs/heads/.*`\. ++ The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`\. + +``` +CodeBuildProject: + Type: AWS::CodeBuild::Project + Properties: + Name: MyProject + ServiceRole: service-role + Artifacts: + Type: NO_ARTIFACTS + Environment: + Type: LINUX_CONTAINER + ComputeType: BUILD_GENERAL1_SMALL + Image: aws/codebuild/standard:4.0 + Source: + Type: BITBUCKET + Location: source-location + Triggers: + Webhook: true + FilterGroups: + - - Type: EVENT + Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED + - Type: BASE_REF + Pattern: ^refs/heads/main$ + ExcludeMatchedPattern: false + - Type: ACTOR_ACCOUNT_ID + Pattern: 12345 + ExcludeMatchedPattern: true + - - Type: EVENT + Pattern: PUSH + - Type: HEAD_REF + Pattern: ^refs/heads/.* + - - Type: EVENT + Pattern: PUSH + - Type: COMMIT_MESSAGE + - Pattern: \[CodeBuild\] +``` \ No newline at end of file diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 230181e..d5efdbc 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -1,6 +1,6 @@ # Build caching in AWS CodeBuild - You can save time when your project builds by using a cache\. A cache can store reusable pieces of your build environment and use them across multiple builds\. Your build project can use one of two types of caching: Amazon S3 or local\. If you use a local cache, you must choose one or more of three cache modes: source cache, Docker layer cache, and custom cache\. +You can save time when your project builds by using a cache\. A cache can store reusable pieces of your build environment and use them across multiple builds\. Your build project can use one of two types of caching: Amazon S3 or local\. If you use a local cache, you must choose one or more of three cache modes: source cache, Docker layer cache, and custom cache\. **Note** Docker layer cache mode is available for the Linux environment only\. If you choose this mode, you must run your build in privileged mode\. CodeBuild projects granted privileged mode grants its container access to all devices\. For more information, see [Runtime privilege and Linux capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. @@ -11,48 +11,53 @@ Docker layer cache mode is available for the Linux environment only\. If you cho ## Amazon S3 caching - Amazon S3 caching stores the cache in an Amazon S3 bucket that is available across multiple build hosts\. This is a good option for small intermediate build artifacts that are more expensive to build than to download\. This is not the best option for large build artifacts because they can take a long time to transfer over your network, which can affect build performance\. It also is not the best option if you use Docker layers\. +Amazon S3 caching stores the cache in an Amazon S3 bucket that is available across multiple build hosts\. This is a good option for small to intermediate sized build artifacts that are more expensive to build than to download\. This is not the best option for large build artifacts because they can take a long time to transfer over your network, which can affect build performance\. It also is not the best option if you use Docker layers\. ## Local caching - Local caching stores a cache locally on a build host that is available to that build host only\. This is a good option for large intermediate build artifacts because the cache is immediately available on the build host\. This is not the best option if your builds are infrequent\. This means that build performance is not impacted by network transfer time\. If you choose local caching, you must choose one or more of the following cache modes: -+ Source cache mode caches Git metadata for primary and secondary sources\. After the cache is created, subsequent builds pull only the change between commits\. This mode is a good choice for projects with a clean working directory and a source that is a large Git repository\. If you choose this option and your project does not use a Git repository \(GitHub, GitHub Enterprise Server, or Bitbucket\), the option is ignored\. -+ Docker layer cache mode caches existing Docker layers\. This mode is a good choice for projects that build or pull large Docker images\. It can prevent the performance issues caused by pulling large Docker images down from the network\. +Local caching stores a cache locally on a build host that is available to that build host only\. This is a good option for intermediate to large build artifacts because the cache is immediately available on the build host\. This is not the best option if your builds are infrequent\. This means that build performance is not impacted by network transfer time\. + +If you choose local caching, you must choose one or more of the following cache modes: ++ Source cache mode caches Git metadata for primary and secondary sources\. After the cache is created, subsequent builds pull only the change between commits\. This mode is a good choice for projects with a clean working directory and a source that is a large Git repository\. If you choose this option and your project does not use a Git repository \(GitHub, GitHub Enterprise Server, or Bitbucket\), the option is ignored\. ++ Docker layer cache mode caches existing Docker layers\. This mode is a good choice for projects that build or pull large Docker images\. It can prevent the performance issues caused by pulling large Docker images down from the network\. **Note** - You can use a Docker layer cache in the Linux environment only\. - The `privileged` flag must be set so that your project has the required Docker permissions\. +You can use a Docker layer cache in the Linux environment only\. +The `privileged` flag must be set so that your project has the required Docker permissions\. By default, Docker containers do not allow access to any devices\. Privileged mode grants a build project's Docker container access to all devices\. For more information, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. - You should consider the security implication before you use a Docker layer cache\. -+ Custom cache mode caches directories you specify in the buildspec file\. This mode is a good choice if your build scenario is not suited to one of the other two local cache modes\. If you use a custom cache: - + Only directories can be specified for caching\. You cannot specify individual files\. - + Symlinks are used to reference cached directories\. - + Cached directories are linked to your build before it downloads its project sources\. Cached items overrides source items if they have the same name\. Directories are specified using cache paths in the buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. +You should consider the security implication before you use a Docker layer cache\. ++ Custom cache mode caches directories you specify in the buildspec file\. This mode is a good choice if your build scenario is not suited to one of the other two local cache modes\. If you use a custom cache: + + Only directories can be specified for caching\. You cannot specify individual files\. + + Symlinks are used to reference cached directories\. + + Cached directories are linked to your build before it downloads its project sources\. Cached items overrides source items if they have the same name\. Directories are specified using cache paths in the buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. + Avoid directory names that are the same in the source and in the cache\. Locally\-cached directories may override, or delete the contents of, directories in the source repository that have the same name\. **Note** -The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_GENERAL1_2XLARGE` compute type do not support the use of a local cache\. For more information, see [Build environment compute types](build-env-ref-compute-types.md)\. +Local caching is not supported with the `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_GENERAL1_2XLARGE` compute type\. For more information, see [Build environment compute types](build-env-ref-compute-types.md)\. + +**Note** +Local caching is not supported when you configure CodeBuild to work with a VPC\. For more information on using VPCs with CodeBuild, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. **Topics** + [Specify local caching \(CLI\)](#caching-local-cli) + [Specify local caching \(console\)](#caching-local-console) + [Specify local caching \(AWS CloudFormation\)](#caching-local-cfn) - You can use the AWS CLI, console, SDK, or AWS CloudFormation to specify a local cache\. +You can use the AWS CLI, console, SDK, or AWS CloudFormation to specify a local cache\. ### Specify local caching \(CLI\) - You can use the the `--cache` parameter in the AWS CLI to specify each of the three local cache types\. -+ To specify a source cache: +You can use the the `--cache` parameter in the AWS CLI to specify each of the three local cache types\. ++ To specify a source cache: ``` --cache type=LOCAL,mode=[LOCAL_SOURCE_CACHE] ``` -+ To specify a Docker layer cache: ++ To specify a Docker layer cache: ``` --cache type=LOCAL,mode=[LOCAL_DOCKER_LAYER_CACHE] ``` -+ To specify a custom cache: ++ To specify a custom cache: ``` --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE] @@ -70,7 +75,7 @@ For more information, see [Create a build project \(console\)](create-project-co ### Specify local caching \(AWS CloudFormation\) - If you use AWS CloudFormation to specify a local cache, on the `Cache` property, for `Type`, specify `LOCAL`\. The following sample YAML\-formatted AWS CloudFormation code specifies all three local cache types\. You can specify any combination of the types\. If you use a Docker layer cache, under `Environment`, you must set `PrivilegedMode` to `true` and `Type` to `LINUX_CONTAINER`\. +If you use AWS CloudFormation to specify a local cache, on the `Cache` property, for `Type`, specify `LOCAL`\. The following sample YAML\-formatted AWS CloudFormation code specifies all three local cache types\. You can specify any combination of the types\. If you use a Docker layer cache, under `Environment`, you must set `PrivilegedMode` to `true` and `Type` to `LINUX_CONTAINER`\. ``` CodeBuildProject: @@ -87,7 +92,7 @@ CodeBuildProject: Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:4.0 + Image: aws/codebuild/standard:5.0 Certificate: bucket/cert.zip # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE PrivilegedMode: true diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index ab8344c..e5547a1 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -6,66 +6,30 @@ AWS CodeBuild manages the following Docker images that are available in the Code | Platform | Image identifier | Definition | | --- | --- | --- | | Amazon Linux 2 | aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0 | [al2/standard/3\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/3.0) | -| Amazon Linux 2 | aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0 | [al2/standard/2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/2.0) | +| Amazon Linux 2 | aws/codebuild/amazonlinux2\-x86\_64\-standard:4\.0 | [al2/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/4.0) | | Amazon Linux 2 | aws/codebuild/amazonlinux2\-aarch64\-standard:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.0) | +| Amazon Linux 2 | aws/codebuild/amazonlinux2\-aarch64\-standard:2\.0 | [al2/aarch64/standard/2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/2.0) | | Ubuntu 18\.04 | aws/codebuild/standard:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | -| Ubuntu 18\.04 | aws/codebuild/standard:3\.0 | [ubuntu/standard/3\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/3.0) | -| Ubuntu 18\.04 | aws/codebuild/standard:2\.0 ¹ | [ubuntu/standard/2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/2.0) | -| Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | +| Ubuntu 20\.04 | aws/codebuild/standard:5\.0 | [ubuntu/standard/5\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/5.0) | +| Ubuntu 22\.04 | aws/codebuild/standard:6\.0 | [ubuntu/standard/6\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/6.0) | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | +| Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-2\.0 | N/A | -¹ No longer maintained after June 2020\. - - The latest version of each image is cached\. If you specify a more specific version, then CodeBuild provisions that version instead of the cached version\. This can result in longer build times\. For example, to benefit from caching, specify `aws/codebuild/amazonlinux2-x86_64-standard:3.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:3.0-1.0.0`\. - - You can specify one or more runtimes in the `runtime-versions` section of your buildspec file\. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file\. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use\. If you specify one or more runtimes, CodeBuild uses only those runtimes\. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you\. For more information, see [Specify runtime versions in the buildspec file](build-spec-ref.md#runtime-versions-buildspec-file)\. - - When you specify a runtime in the `runtime-versions` section of your buildspec file, you can specify a specific version, a specific major version and the latest minor version, or the latest version\. The following table lists the available runtimes and how to specify them\. - - -**Ubuntu 18\.04 and Amazon Linux 2 platforms runtimes** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) - -**Note** -The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the Android Runtime \(ART\)\. - -The base image of the Windows Server Core 2016 contains the following runtimes\. - - -| Runtime name | Version in `windows-base:2.0` | -| --- | --- | -| dotnet | 2\.2, 3\.1 | -| golang | 1\.13 | -| nodejs | 10\.18, 12\.14 | -| java | openjdk11 | -| php | 7\.3, 7\.4 | -| python | 3\.7 | -| ruby | 2\.6 | - -The base image of the Windows Server Core 2019 contains the following runtimes\. - - -| Runtime name | Version in `windows-base:2019-1.0` | -| --- | --- | -| dotnet | 3\.1\.3 | -| golang | 1\.14 | -| nodejs | 12\.18 | -| java | corretto11 | -| php | 7\.4\.7 | -| powershell | 7\.0\.2 | -| python | 3\.8\.3 | -| ruby | 2\.7 | - -**Note** - The base image of the Windows Server Core 2016 and Windows Server Core 2016 platforms are available in the US East \(N\. Virginia\), US East \(Ohio\), US West \(Oregon\), and Europe \(Ireland\) Regions only\. - -You can use a build specification to install other components \(for example, the AWS CLI, Apache Maven, Apache Ant, Mocha, RSpec, or similar\) during the `install` build phase\. For more information, see [Buildspec example](build-spec-ref.md#build-spec-ref-example)\. +The base image of the Windows Server Core 2019 platform is only available in the following regions: ++ US East \(N\. Virginia\) ++ US East \(Ohio\) ++ US West \(Oregon\) ++ Europe \(Ireland\) CodeBuild frequently updates the list of Docker images\. To get the most current list, do one of the following: -+ In the CodeBuild console, in the **Create build project** wizard or **Edit Build Project** page, for **Environment image**, choose **Managed image**\. Choose from the **Operating system**, **Runtime**, and **Runtime version** drop\-down lists\. For more information, see [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. ++ In the CodeBuild console, in the **Create build project** wizard or **Edit Build Project** page, for **Environment image**, choose **Managed image**\. Choose from the **Operating system**, **Runtime**, and **Runtime version** drop\-down lists\. For more information, see [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project-console.md)\. + For the AWS CLI, run the `list-curated-environment-images` command: ``` aws codebuild list-curated-environment-images ``` -+ For the AWS SDKs, call the `ListCuratedEnvironmentImages` operation for your target programming language\. For more information, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file ++ For the AWS SDKs, call the `ListCuratedEnvironmentImages` operation for your target programming language\. For more information, see the [AWS SDKs and tools reference](sdk-ref.md)\. + +**Topics** ++ [Available runtimes](available-runtimes.md) ++ [Runtime versions](runtime-versions.md) \ No newline at end of file diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index 93a3e4d..e9119d3 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.md @@ -3,7 +3,7 @@ You provide a set of commands for AWS CodeBuild to run in a build environment during the lifecycle of a build \(for example, installing build dependencies and testing and compiling your source code\)\. There are several ways to specify these commands: + Create a build specification file and include it with your source code\. In this file, specify the commands you want to run in each phase of the build lifecycle\. For more information, see the [Build specification reference for CodeBuild](build-spec-ref.md)\. + Use the CodeBuild console to create a build project\. In **Insert build commands**, for **Build commands**, enter the commands you want to run in the `build` phase\. For more information, see [Create a build project \(console\)](create-project-console.md)\. -+ Use the CodeBuild console to change the settings of a build project\. In **Insert build commands**, for **Build commands**, enter the commands you want to run in the `build` phase\. For more information, see [Change a build project's settings \(console\)](change-project.md#change-project-console)\. ++ Use the CodeBuild console to change the settings of a build project\. In **Insert build commands**, for **Build commands**, enter the commands you want to run in the `build` phase\. For more information, see [Change a build project's settings \(console\)](change-project-console.md)\. + Use the AWS CLI or AWS SDKs to create a build project or change the settings of a build project\. Reference the source code that contains a buildspec file with your commands, or specify a single string that includes the contents of an equivalent buildspec file\. For more information, see [Create a build project](create-project.md) or [Change a build project's settings](change-project.md)\. + Use the AWS CLI or AWS SDKs to start a build, specifying a buildspec file or a single string that includes the contents of an equivalent buildspec file\. For more information, see the description for the `buildspecOverride` value in [Run a build](run-build.md)\. @@ -13,4 +13,4 @@ You can specify any Shell Command Language \(sh\) command\. In buildspec version If CodeBuild encounters an error, the error might be more difficult to troubleshoot compared to running a single command in its own instance of the default shell\. -Commands that are run in a Windows Server Core 2016 image use the PowerShell shell\. \ No newline at end of file +Commands that are run in a Windows Server Core image use the PowerShell shell\. \ No newline at end of file diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index eba2a82..8b634bf 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -1,44 +1,88 @@ # Build environment compute types -AWS CodeBuild provides build environments with the following available memory, vCPUs, and disk space: +AWS CodeBuild provides build environments with the following available memory, vCPUs, and disk space: -**Operating system: Linux** - -| Compute type | computeType value | Memory | vCPUs | Disk space | Environment type | +| Compute type | Environment computeType value | Environment type value | Memory | vCPUs | Disk space | | --- | --- | --- | --- | --- | --- | -| build\.general1\.small | BUILD\_GENERAL1\_SMALL | 3 GB | 2 | 64 GB | LINUX\_CONTAINER | -| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | LINUX\_CONTAINER | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | LINUX\_CONTAINER | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 255 GB | 32 | 50 GB | LINUX\_GPU\_CONTAINER | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 16 GB | 8 | 50 GB | ARM\_CONTAINER | -| build\.general1\.2xlarge | BUILD\_GENERAL1\_2XLARGE | 145 GB | 72 | 824 GB \(SSD\) | LINUX\_CONTAINER | +| ARM Small | BUILD\_GENERAL1\_SMALL | ARM\_CONTAINER | 4 GB | 2 | 50 GB | +| ARM Large | BUILD\_GENERAL1\_LARGE | ARM\_CONTAINER | 16 GB | 8 | 50 GB | +| Linux Small ¹ | BUILD\_GENERAL1\_SMALL | LINUX\_CONTAINER | 3 GB | 2 | 64 GB | +| Linux Medium ¹ | BUILD\_GENERAL1\_MEDIUM | LINUX\_CONTAINER | 7 GB | 4 | 128 GB | +| Linux Large ¹ | BUILD\_GENERAL1\_LARGE | LINUX\_CONTAINER | 15 GB | 8 | 128 GB | +| Linux 2XLarge | BUILD\_GENERAL1\_2XLARGE | LINUX\_CONTAINER | 145 GB | 72 | 824 GB \(SSD\) | +| Linux GPU Large | BUILD\_GENERAL1\_LARGE | LINUX\_GPU\_CONTAINER | 255 GB | 32 | 50 GB | +| Windows Medium | BUILD\_GENERAL1\_MEDIUM | WINDOWS\_SERVER\_2019\_CONTAINER | 7 GB | 4 | 128 GB | +| Windows Large | BUILD\_GENERAL1\_LARGE | WINDOWS\_SERVER\_2019\_CONTAINER | 15 GB | 8 | 128 GB | -The disk space listed for each build environment is available only in the directory specified by the `CODEBUILD_SRC_DIR` environment variable\. +¹ The latest version of this image type is cached\. If you specify a more specific version, then CodeBuild provisions that version instead of the cached version\. This can result in longer build times\. For example, to benefit from caching, specify `aws/codebuild/amazonlinux2-x86_64-standard:3.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:3.0-1.0.0`\. -**Note** - Some environment and compute types have limitations: -The environment type `LINUX_GPU_CONTAINER` is available only in Regions US East \(N\. Virginia\), US West \(Oregon\), Canada \(Central\), Europe \(Ireland\), Europe \(London\), Europe \(Frankfurt\), Asia Pacific \(Tokyo\), Asia Pacific \(Seoul\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), China \(Beijing\), and China \(Ningxia\)\. -The environment type `ARM_CONTAINER` is available only in Regions US East \(N\. Virginia\), US East \(Ohio\), US West \(Oregon\), Europe \(Ireland\), Asia Pacific \(Mumbai\), Asia Pacific \(Tokyo\), Asia Pacific \(Sydney\), and Europe \(Frankfurt\)\. -The compute type `build.general1.2xlarge` is available only in Regions US East \(N\. Virginia\), US East \(Ohio\), US West \(N\. California\), US West \(Oregon\), Canada \(Central\), South America \(São Paulo\), Europe \(Stockholm\), Europe \(Ireland\), Europe \(London\), Europe \(Paris\), Europe \(Frankfurt\), Middle East \(Bahrain\), Asia Pacific \(Hong Kong\), Asia Pacific \(Tokyo\), Asia Pacific \(Seoul\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), Asia Pacific \(Mumbai\), China \(Beijing\), and China \(Ningxia\)\. -For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncompressed are supported\. +When using other environment types, it is recommended that you use a custom image to reduce build times\. +The disk space listed for each build environment is available only in the directory specified by the `CODEBUILD_SRC_DIR` environment variable\. -**Operating system: Windows** +To choose a compute type: ++ In the CodeBuild console, in the **Create build project** wizard or **Edit Build Project** page, in **Environment** expand **Additional configuration**, and then choose one of the options from **Compute type**\. For more information, see [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project-console.md)\. ++ For the AWS CLI, run the `create-project` or `update-project` command, specifying the `computeType` value of the `environment` object\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md) or [Change a build project's settings \(AWS CLI\)](change-project-cli.md)\. ++ For the AWS SDKs, call the equivalent of the `CreateProject` or `UpdateProject` operation for your target programming language, specifying the equivalent of `computeType` value of the `environment` object\. For more information, see the [AWS SDKs and tools reference](sdk-ref.md)\. -| Compute type | computeType value | Memory | vCPUs | Disk space | Environment type | -| --- | --- | --- | --- | --- | --- | -| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | WINDOWS\_CONTAINER WINDOWS\_SERVER\_2019\_CONTAINER | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | WINDOWS\_CONTAINER WINDOWS\_SERVER\_2019\_CONTAINER | +Some environment and compute types have Region availability limitations: ++ The environment type `LINUX_GPU_CONTAINER` is only available in these Regions: + + US East \(N\. Virginia\) + + US West \(Oregon\) + + Asia Pacific \(Seoul\) + + Asia Pacific \(Singapore\) + + Asia Pacific \(Sydney\) + + Asia Pacific \(Tokyo\) + + Canada \(Central\) + + China \(Beijing\) + + China \(Ningxia\) + + Europe \(Frankfurt\) + + Europe \(Ireland\) + + Europe \(London\) ++ The environment type `ARM_CONTAINER` is only available in these Regions: + + US East \(Ohio\) + + US East \(N\. Virginia\) + + US West \(N\. California\) + + US West \(Oregon\) + + Asia Pacific \(Mumbai\) + + Asia Pacific \(Seoul\) + + Asia Pacific \(Singapore\) + + Asia Pacific \(Sydney\) + + Asia Pacific \(Tokyo\) + + Canada \(Central\) + + Europe \(Frankfurt\) + + Europe \(Ireland\) + + Europe \(London\) + + Europe \(Paris\) ++ The compute type `BUILD_GENERAL1_2XLARGE` is only available in these Regions: + + US East \(Ohio\) + + US East \(N\. Virginia\) + + US West \(N\. California\) + + US West \(Oregon\) + + Asia Pacific \(Hong Kong\) + + Asia Pacific \(Jakarta\) + + Asia Pacific \(Mumbai\) + + Asia Pacific \(Seoul\) + + Asia Pacific \(Singapore\) + + Asia Pacific \(Sydney\) + + Asia Pacific \(Tokyo\) + + Canada \(Central\) + + China \(Beijing\) + + China \(Ningxia\) + + Europe \(Frankfurt\) + + Europe \(Ireland\) + + Europe \(London\) + + Europe \(Paris\) + + Europe \(Stockholm\) + + Middle East \(Bahrain\) + + South America \(São Paulo\) + +For the compute type `BUILD_GENERAL1_2XLARGE`, Docker images up to 100 GB uncompressed are supported\. **Note** For custom build environment images, CodeBuild supports Docker images up to 50 GB uncompressed in Linux and Windows, regardless of the compute type\. To check your build image's size, use Docker to run the `docker images REPOSITORY:TAG` command\. -To choose a compute type: -+ In the CodeBuild console, in the **Create build project** wizard or **Edit Build Project** page, in **Environment** expand **Additional configuration**, and then choose one of the options from **Compute type**\. For more information, see [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. -+ For the AWS CLI, run the `create-project` or `update-project` command, specifying the `computeType` value of the `environment` object\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md) or [Change a build project's settings \(AWS CLI\)](change-project.md#change-project-cli)\. -+ For the AWS SDKs, call the equivalent of the `CreateProject` or `UpdateProject` operation for your target programming language, specifying the equivalent of `computeType` value of the `environment` object\. For more information, see the [AWS SDKs and tools reference](sdk-ref.md)\. - You can use Amazon EFS to access more space in your build container\. For more information, see [Amazon Elastic File System sample for AWS CodeBuild](sample-efs.md)\. If you want to manipulate container disk space during a build, then the build must run in privileged mode\. **Note** diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 5525e31..f760c22 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -1,44 +1,103 @@ # Environment variables in build environments AWS CodeBuild provides several environment variables that you can use in your build commands: -+ `AWS_DEFAULT_REGION`: The AWS Region where the build is running \(for example, `us-east-1`\)\. This environment variable is used primarily by the AWS CLI\. -+ `AWS_REGION`: The AWS Region where the build is running \(for example, `us-east-1`\)\. This environment variable is used primarily by the AWS SDKs\. -+ `CODEBUILD_BUILD_ARN`: The Amazon Resource Name \(ARN\) of the build \(for example, `arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:b1e6661e-e4f2-4156-9ab9-82a19EXAMPLE`\)\. -+ `CODEBUILD_BUILD_ID`: The CodeBuild ID of the build \(for example, `codebuild-demo-project:b1e6661e-e4f2-4156-9ab9-82a19EXAMPLE`\)\. -+ `CODEBUILD_BUILD_IMAGE`: The CodeBuild build image identifier \(for example, `aws/codebuild/standard:2.0`\)\. -+ `CODEBUILD_BUILD_NUMBER`: The current build number for the project\. -+ `CODEBUILD_BUILD_SUCCEEDING`: Whether the current build is succeeding\. Set to `0` if the build is failing, or `1` if the build is succeeding\. -+ `CODEBUILD_INITIATOR`: The entity that started the build\. If CodePipeline started the build, this is the pipeline's name \(for example, `codepipeline/my-demo-pipeline`\)\. If an IAM user started the build, this is the user's name \(for example, `MyUserName`\)\. If the Jenkins plugin for CodeBuild started the build, this is the string `CodeBuild-Jenkins-Plugin`\. -+ `CODEBUILD_KMS_KEY_ID`: The identifier of the AWS KMS key that CodeBuild is using to encrypt the build output artifact \(for example, `arn:aws:kms:region-ID:account-ID:key/key-ID` or `alias/key-alias`\)\. -+ `CODEBUILD_LOG_PATH`: The log stream name in CloudWatch Logs for the build\. -+ `CODEBUILD_RESOLVED_SOURCE_VERSION`: An identifier for the version of a build's source code\. Its format depends on the source code repository: - + For CodeCommit, GitHub, GitHub Enterprise Server, and Bitbucket, it is the commit ID\. For these repositories, `CODEBUILD_RESOLVED_SOURCE_VERSION` is only available after the `DOWNLOAD_SOURCE` phase\. - + For CodePipeline, it is the source revision is provided by CodePipeline\. For CodePipeline, the `CODEBUILD_RESOLVED_SOURCE_VERSION` environment variable may not always be available\. - + For Amazon S3, this does not apply\. -+ `CODEBUILD_SOURCE_REPO_URL`: The URL to the input artifact or source code repository\. For Amazon S3, this is `s3://` followed by the bucket name and path to the input artifact\. For CodeCommit and GitHub, this is the repository's clone URL\. If a build originates from CodePipeline, then this might be empty\. -+ `CODEBUILD_SOURCE_VERSION`: The value's format depends on the source repository\. - + For Amazon S3, it is the version ID associated with the input artifact\. - + For CodeCommit, it is the commit ID or branch name associated with the version of the source code to be built\. - + For GitHub, GitHub Enterprise Server, and Bitbucket it is the commit ID, branch name, or tag name associated with the version of the source code to be built\. + +AWS\_DEFAULT\_REGION +The AWS Region where the build is running \(for example, `us-east-1`\)\. This environment variable is used primarily by the AWS CLI\. + +AWS\_REGION +The AWS Region where the build is running \(for example, `us-east-1`\)\. This environment variable is used primarily by the AWS SDKs\. + +CODEBUILD\_BATCH\_BUILD\_IDENTIFIER +The identifier of the build in a batch build\. This is specified in the batch buildspec\. For more information, see [Batch build buildspec reference](batch-build-buildspec.md)\. + +CODEBUILD\_BUILD\_ARN +The Amazon Resource Name \(ARN\) of the build \(for example, `arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:b1e6661e-e4f2-4156-9ab9-82a19EXAMPLE`\)\. + +CODEBUILD\_BUILD\_ID +The CodeBuild ID of the build \(for example, `codebuild-demo-project:b1e6661e-e4f2-4156-9ab9-82a19EXAMPLE`\)\. + +CODEBUILD\_BUILD\_IMAGE +The CodeBuild build image identifier \(for example, `aws/codebuild/standard:2.0`\)\. + +CODEBUILD\_BUILD\_NUMBER +The current build number for the project\. + +CODEBUILD\_BUILD\_SUCCEEDING +Whether the current build is succeeding\. Set to `0` if the build is failing, or `1` if the build is succeeding\. + +CODEBUILD\_INITIATOR +The entity that started the build\. If CodePipeline started the build, this is the pipeline's name \(for example, `codepipeline/my-demo-pipeline`\)\. If an IAM user started the build, this is the user's name \(for example, `MyUserName`\)\. If the Jenkins plugin for CodeBuild started the build, this is the string `CodeBuild-Jenkins-Plugin`\. + +CODEBUILD\_KMS\_KEY\_ID +The identifier of the AWS KMS key that CodeBuild is using to encrypt the build output artifact \(for example, `arn:aws:kms:region-ID:account-ID:key/key-ID` or `alias/key-alias`\)\. + +CODEBUILD\_LOG\_PATH +The log stream name in CloudWatch Logs for the build\. + +CODEBUILD\_PUBLIC\_BUILD\_URL +The URL of the build results for this build on the public builds website\. This variable is only set if the build project has public builds enabled\. For more information, see [Public build projects in AWS CodeBuild](public-builds.md)\. + +CODEBUILD\_RESOLVED\_SOURCE\_VERSION +The version identifier of a build's source code\. The contents depends on the source code repository: +CodeCommit, GitHub, GitHub Enterprise Server, and Bitbucket +This variable contains the commit ID\. +CodePipeline +This variable contains the source revision provided by CodePipeline\. +If CodePipeline is not able to resolve the source revision, such as when the source is an Amazon S3 bucket that does not have versioning enabled, this environment variable is not set\. +Amazon S3 +This variable is not set\. +When applicable, the `CODEBUILD_RESOLVED_SOURCE_VERSION` variable is only available after the `DOWNLOAD_SOURCE` phase\. + +CODEBUILD\_SOURCE\_REPO\_URL +The URL to the input artifact or source code repository\. For Amazon S3, this is `s3://` followed by the bucket name and path to the input artifact\. For CodeCommit and GitHub, this is the repository's clone URL\. If a build originates from CodePipeline, this environment variable may be empty\. +For secondary sources, the environment variable for the secondary source repository URL is `CODEBUILD_SOURCE_REPO_URL_`, where `` is the source identifier you create\. + +CODEBUILD\_SOURCE\_VERSION +The value's format depends on the source repository\. ++ For Amazon S3, it is the version ID associated with the input artifact\. ++ For CodeCommit, it is the commit ID or branch name associated with the version of the source code to be built\. ++ For GitHub, GitHub Enterprise Server, and Bitbucket it is the commit ID, branch name, or tag name associated with the version of the source code to be built\. **Note** For a GitHub or GitHub Enterprise Server build that is triggered by a webhook pull request event, it is `pr/pull-request-number`\. -+ `CODEBUILD_SRC_DIR`: The directory path that CodeBuild uses for the build \(for example, `/tmp/src123456789/src`\)\. -**Note** -If you use a secondary source, the environment variable for its directory path is `CODEBUILD_SRC_DIR_sourceIdentifier`, where `sourceIdentifier` is the source identifier you create\. For more information, see [Multiple input sources and output artifacts sample](sample-multi-in-out.md)\. -+ `CODEBUILD_START_TIME`: The start time of the build specified as a Unix timestamp in milliseconds\. -+ `CODEBUILD_WEBHOOK_ACTOR_ACCOUNT_ID`: The account ID of the user that triggered the webhook event\. -+ `CODEBUILD_WEBHOOK_BASE_REF`: The base reference name of the webhook event that triggers the current build\. For a pull request, this is the branch reference\. -+ `CODEBUILD_WEBHOOK_EVENT`: The webhook event that triggers the current build\. -+ `CODEBUILD_WEBHOOK_PREV_COMMIT`: The ID of the most recent commit before the webhook push event that triggers the current build\. -+ `CODEBUILD_WEBHOOK_HEAD_REF`: The head reference name of the webhook event that triggers the current build\. It can be a branch reference or a tag reference\. -+ `CODEBUILD_WEBHOOK_TRIGGER`: Shows the webhook event that triggered the build\. This variable is available only for builds triggered by a webhook\. The value is parsed from the payload sent to CodeBuild by GitHub, GitHub Enterprise Server, or Bitbucket\. The value's format depends on what type of event triggered the build\. - + For builds triggered by a pull request, it is `pr/pull-request-number`\. - + For builds triggered by creating a new branch or pushing a commit to a branch, it is `branch/branch-name`\. - + For builds triggered by a pushing a tag to a repository, it is `tag/tag-name`\. -+ `HOME`: This environment variable is always set to `/root`\. +For secondary sources, the environment variable for the secondary source version is `CODEBUILD_SOURCE_VERSION_`, where `` is the source identifier you create\. For more information, see [Multiple input sources and output artifacts sample](sample-multi-in-out.md)\. + +CODEBUILD\_SRC\_DIR +The directory path that CodeBuild uses for the build \(for example, `/tmp/src123456789/src`\)\. +For secondary sources, the environment variable for the secondary source directory path is `CODEBUILD_SRC_DIR_`, where `` is the source identifier you create\. For more information, see [Multiple input sources and output artifacts sample](sample-multi-in-out.md)\. + +CODEBUILD\_START\_TIME +The start time of the build specified as a Unix timestamp in milliseconds\. + +CODEBUILD\_WEBHOOK\_ACTOR\_ACCOUNT\_ID +The account ID of the user that triggered the webhook event\. + +CODEBUILD\_WEBHOOK\_BASE\_REF +The base reference name of the webhook event that triggers the current build\. For a pull request, this is the branch reference\. + +CODEBUILD\_WEBHOOK\_EVENT +The webhook event that triggers the current build\. + +CODEBUILD\_WEBHOOK\_MERGE\_COMMIT +The identifier of the merge commit used for the build\. This variable is set when a Bitbucket pull request is merged with the squash strategy and the pull request branch is closed\. In this case, the original pull request commit no longer exists, so this environment variable contains the identifier of the squashed merge commit\. + +CODEBUILD\_WEBHOOK\_PREV\_COMMIT +The ID of the most recent commit before the webhook push event that triggers the current build\. + +CODEBUILD\_WEBHOOK\_HEAD\_REF +The head reference name of the webhook event that triggers the current build\. It can be a branch reference or a tag reference\. + +CODEBUILD\_WEBHOOK\_TRIGGER +Shows the webhook event that triggered the build\. This variable is available only for builds triggered by a webhook\. The value is parsed from the payload sent to CodeBuild by GitHub, GitHub Enterprise Server, or Bitbucket\. The value's format depends on what type of event triggered the build\. ++ For builds triggered by a pull request, it is `pr/pull-request-number`\. ++ For builds triggered by creating a new branch or pushing a commit to a branch, it is `branch/branch-name`\. ++ For builds triggered by a pushing a tag to a repository, it is `tag/tag-name`\. + +HOME +This environment variable is always set to `/root`\. You can also provide build environments with your own environment variables\. For more information, see the following topics: -+ [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md) ++ [Use CodePipeline with CodeBuild](how-to-create-pipeline.md) + [Create a build project](create-project.md) + [Change a build project's settings](change-project.md) + [Run a build](run-build.md) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index f4997e6..2a287b2 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -7,6 +7,7 @@ This topic provides important reference information about build specification \( + [Buildspec syntax](#build-spec-ref-syntax) + [Buildspec example](#build-spec-ref-example) + [Buildspec versions](#build-spec-ref-versions) ++ [Batch build buildspec reference](batch-build-buildspec.md) ## Buildspec file name and storage location @@ -38,31 +39,38 @@ The buildspec has the following syntax: ``` version: 0.2 -run-as: Linux-user-name +run\-as: Linux-user-name env: shell: shell-tag variables: key: "value" key: "value" - parameter-store: + parameter\-store: key: "value" key: "value" - exported-variables: + exported\-variables: - variable - variable - secrets-manager: + secrets\-manager: key: secret-id:json-key:version-stage:version-id - git-credential-helper: no | yes + git\-credential\-helper: no | yes proxy: - upload-artifacts: no | yes + upload\-artifacts: no | yes logs: no | yes +batch: + fast-fail: false | true + # build-list: + # build-matrix: + # build-graph: + phases: install: - run-as: Linux-user-name - runtime-versions: + run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE + runtime\-versions: runtime: version runtime: version commands: @@ -71,8 +79,9 @@ phases: finally: - command - command - pre_build: - run-as: Linux-user-name + pre\_build: + run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE commands: - command - command @@ -80,15 +89,17 @@ phases: - command - command build: - run-as: Linux-user-name + run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE commands: - command - command finally: - command - command - post_build: - run-as: Linux-user-name + post\_build: + run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE commands: - command - command @@ -100,30 +111,33 @@ reports: files: - location - location - base-directory: location - discard-paths: no | yes - file-format: JunitXml | NunitXml | CucumberJson | VisualStudioTrx | TestNGXml + base\-directory: location + discard\-paths: no | yes + file\-format: report-format artifacts: files: - location - location name: artifact-name - discard-paths: no | yes - base-directory: location - secondary-artifacts: + discard\-paths: no | yes + base\-directory: location + exclude\-paths: excluded paths + enable\-symlinks: no | yes + s3\-prefix: prefix + secondary\-artifacts: artifactIdentifier: files: - location - location name: secondary-artifact-name - discard-paths: no | yes - base-directory: location + discard\-paths: no | yes + base\-directory: location artifactIdentifier: files: - location - location - discard-paths: no | yes - base-directory: location + discard\-paths: no | yes + base\-directory: location cache: paths: - path @@ -141,7 +155,7 @@ Although version 0\.1 is still supported, we recommend that you use version 0\.2 ### run\-as -Optional sequence\. Available to Linux users only\. Specifies a Linux user that runs commands in this buildspec file\. `run-as` grants the specified user read and execute permissions\. When you specify `run-as` at the top of the buildspec file, it applies globally to all commands\. If you don't want to specify a user for all buildspec file commands, you can specify one for commands in a phase by using `run-as` in one of the `phases` blocks\. If `run-as` is not specified, then all commands run as the root user\. +Optional sequence\. Available to Linux users only\. Specifies a Linux user that runs commands in this buildspec file\. `run-as` grants the specified user read and run permissions\. When you specify `run-as` at the top of the buildspec file, it applies globally to all commands\. If you don't want to specify a user for all buildspec file commands, you can specify one for commands in a phase by using `run-as` in one of the `phases` blocks\. If `run-as` is not specified, then all commands run as the root user\. ### env @@ -169,7 +183,7 @@ Any environment variables you set replace existing environment variables\. For e Do not set any environment variable with a name that starts with `CODEBUILD_`\. This prefix is reserved for internal use\. If an environment variable with the same name is defined in multiple places, the value is determined as follows: + The value in the start build operation call takes highest precedence\. You can add or override environment variables when you create a build\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. -+ The value in the build project definition takes next precedence\. You can add environment variables at the project level when you create or edit a project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md) and [Change a build project's settings in AWS CodeBuild ](change-project.md)\. ++ The value in the build project definition takes next precedence\. You can add environment variables at the project level when you create or edit a project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md) and [Change a build project's settings in AWS CodeBuild](change-project.md)\. + The value in the buildspec declaration takes lowest precedence\. env/**parameter\-store** @@ -179,21 +193,35 @@ Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Do not store any environment variable with a name that starts with `CODEBUILD_`\. This prefix is reserved for internal use\. If an environment variable with the same name is defined in multiple places, the value is determined as follows: + The value in the start build operation call takes highest precedence\. You can add or override environment variables when you create a build\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. -+ The value in the build project definition takes next precedence\. You can add environment variables at the project level when you create or edit a project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md) and [Change a build project's settings in AWS CodeBuild ](change-project.md)\. ++ The value in the build project definition takes next precedence\. You can add environment variables at the project level when you create or edit a project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md) and [Change a build project's settings in AWS CodeBuild](change-project.md)\. + The value in the buildspec declaration takes lowest precedence\. env/**secrets\-manager** -Required if `env` specified, and you want to retrieve custom environment variables stored in AWS Secrets Manager\. Specify a Secrets Manager `reference-key` using the following pattern: - `secret-id:json-key:version-stage:version-id` -+ `secret-id`: The name or Amazon Resource Name \(ARN\) that serves as a unique identifier for the secret\. To access a secret in your AWS account, simply specify the secret name\. To access a secret in a different AWS account, specify the secret ARN\. -+ `json-key`: Specifies the key name of the key\-value pair whose value you want to retrieve\. If you do not specify a `json-key`, CodeBuild retrieves the entire secret text\. -+ `version-stage`: Specifies the secret version that you want to retrieve by the staging label attached to the version\. Staging labels are used to keep track of different versions during the rotation process\. If you use `version-stage`, don't specify `version-id`\. If you don't specify a version stage or version ID, the default is to retrieve the version with the version stage value of `AWSCURRENT`\. -+ `version-id`: Specifies the unique identifier of the version of the secret that you want to use\. If you specify `version-id`, don't specify `version-stage`\. If you don't specify a version stage or version ID, the default is to retrieve the version with the version stage value of AWSCURRENT\. - For more information, see [What is AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*\. +Required if you want to retrieve custom environment variables stored in AWS Secrets Manager\. Specify a Secrets Manager `reference-key` using the following pattern: +``: `::|` +** +\(Required\) The local environment variable name\. Use this name to access the variable during the build\. +** +\(Required\) The name or Amazon Resource Name \(ARN\) that serves as a unique identifier for the secret\. To access a secret in your AWS account, simply specify the secret name\. To access a secret in a different AWS account, specify the secret ARN\. +** +\(Optional\) Specifies the key name of the Secrets Manager key\-value pair whose value you want to retrieve\. If you do not specify a `json-key`, CodeBuild retrieves the entire secret text\. +** +\(Optional\) Specifies the secret version that you want to retrieve by the staging label attached to the version\. Staging labels are used to keep track of different versions during the rotation process\. If you use `version-stage`, don't specify `version-id`\. If you don't specify a version stage or version ID, the default is to retrieve the version with the version stage value of `AWSCURRENT`\. +** +\(Optional\) Specifies the unique identifier of the version of the secret that you want to use\. If you specify `version-id`, don't specify `version-stage`\. If you don't specify a version stage or version ID, the default is to retrieve the version with the version stage value of `AWSCURRENT`\. +In the following example, `TestSecret` is the name of the key\-value pair stored in Secrets Manager\. The key for `TestSecret` is `MY_SECRET_VAR`\. You access the variable during the build using the `LOCAL_SECRET_VAR` name\. + +``` +env: + secrets-manager: + LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR" +``` +For more information, see [What is AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*\. env/**exported\-variables** Optional mapping\. Used to list environment variables you want to export\. Specify the name of each variable you want to export on a separate line under `exported-variables`\. The variable you want to export must be available in your container during the build\. The variable you export can be an environment variable\. - During a build, the value of a variable is available starting with the `install` phase\. It can be updated between the start of the `install` phase and the end of the `post_build` phase\. After the `post_build` phase ends, the value of exported variables cannot change\. +Exported environment variables are used in conjunction with AWS CodePipeline to export environment variables from the current build stage to subsequent stages in the pipeline\. For more information, see [Working with variables](https://docs.aws.amazon.com/codepipeline/latest/userguide/actions-variables.html) in the *AWS CodePipeline User Guide*\. +During a build, the value of a variable is available starting with the `install` phase\. It can be updated between the start of the `install` phase and the end of the `post_build` phase\. After the `post_build` phase ends, the value of exported variables cannot change\. The following cannot be exported: + Amazon EC2 Systems Manager Parameter Store secrets specified in the build project\. + Secrets Manager secrets specified in the build project @@ -223,6 +251,15 @@ In buildspec version 0\.1, CodeBuild runs each command in a separate instance of phases/\*/**run\-as** Optional sequence\. Use in a build phase to specify a Linux user that runs its commands\. If `run-as` is also specified globally for all commands at the top of the buildspec file, then the phase\-level user takes precedence\. For example, if globally `run-as` specifies User\-1, and for the `install` phase only a `run-as` statement specifies User\-2, then all commands in then buildspec file are run as User\-1 *except* commands in the `install` phase, which are run as User\-2\. +phases/\*/**on\-failure** +Optional sequence\. Specifies the action to take if a failure occurs during the phase\. This can be one of the following values: ++ `ABORT` \- Abort the build\. ++ `CONTINUE` \- Continue to the next phase\. +If this property is not specified, the failure process follows the transition phases as shown in [Build phase transitions](view-build-details.md#view-build-details-phases)\. + +phases/\*/**finally** +Optional block\. Commands specified in a `finally` block are run after commands in the `commands` block\. The commands in a `finally` block are run even if a command in the `commands` block fails\. For example, if the `commands` block contains three commands and the first fails, CodeBuild skips the remaining two commands and runs any commands in the `finally` block\. The phase is successful when all commands in the `commands` and the `finally` blocks run successfully\. If any command in a phase fails, the phase fails\. + The allowed build phase names are: phases/**install** @@ -238,40 +275,27 @@ phases: python: 3.x ruby: "$MY_RUBY_VAR" ``` - You can specify one or more runtimes in the `runtime-versions` section of your buildspec file\. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file\. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use\. If you specify one or more runtimes, CodeBuild uses only those runtimes\. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you\. +You can specify one or more runtimes in the `runtime-versions` section of your buildspec file\. If your runtime is dependent upon another runtime, you can also specify its dependent runtime in the buildspec file\. If you do not specify any runtimes in the buildspec file, CodeBuild chooses the default runtimes that are available in the image you use\. If you specify one or more runtimes, CodeBuild uses only those runtimes\. If a dependent runtime is not specified, CodeBuild attempts to choose the dependent runtime for you\. If two specified runtimes conflict, the build fails\. For example, `android: 29` and `java: openjdk11` conflict, so if both are specified, the build fails\. - The following supported runtimes can be specified\. -**Ubuntu 18\.04 and Amazon Linux 2 platforms runtimes** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) +For more information about the available runtimes, see [Available runtimes](available-runtimes.md)\. If you specify a `runtime-versions` section and use an image other than Ubuntu Standard Image 2\.0 or later, or the Amazon Linux 2 \(AL2\) standard image 1\.0 or later, the build issues the warning, "`Skipping install of runtimes. Runtime version selection is not supported by this build image`\." phases/install/**commands** -`commands`: Optional sequence\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs during installation\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. -phases/install/**finally** -Optional block\. Commands specified in a `finally` block are executed after commands in the `commands` block\. The commands in a `finally` block are executed even if a command in the `commands` block fails\. For example, if the `commands` block contains three commands and the first fails, CodeBuild skips the remaining two commands and runs any commands in the `finally` block\. The phase is successful when all commands in the `commands` and the `finally` blocks run successfully\. If any command in a phase fails, the phase fails\. +Optional sequence\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs during installation\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. phases/**pre\_build** Optional sequence\. Represents the commands, if any, that CodeBuild runs before the build\. For example, you might use this phase to sign in to Amazon ECR, or you might install npm dependencies\. phases/pre\_build/**commands** -Required sequence if `pre_build` is specified\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs before the build\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. -phases/pre\_build/**finally** -Optional block\. Commands specified in a `finally` block are executed after commands in the `commands` block\. The commands in a `finally` block are executed even if a command in the `commands` block fails\. For example, if the `commands` block contains three commands and the first fails, CodeBuild skips the remaining two commands and runs any commands in the `finally` block\. The phase is successful when all commands in the `commands` and the `finally` blocks run successfully\. If any command in a phase fails, the phase fails\. +Required sequence if `pre_build` is specified\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs before the build\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. phases/**build** Optional sequence\. Represents the commands, if any, that CodeBuild runs during the build\. For example, you might use this phase to run Mocha, RSpec, or sbt\. phases/build/**commands** -`commands`: Required if `build` is specified\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs during the build\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. -phases/build/**finally** -Optional block\. Commands specified in a `finally` block are executed after commands in the `commands` block\. The commands in a `finally` block are executed even if a command in the `commands` block fails\. For example, if the `commands` block contains three commands and the first fails, CodeBuild skips the remaining two commands and runs any commands in the `finally` block\. The phase is successful when all commands in the `commands` and the `finally` blocks run successfully\. If any command in a phase fails, the phase fails\. +Required if `build` is specified\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs during the build\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. phases/**post\_build** Optional sequence\. Represents the commands, if any, that CodeBuild runs after the build\. For example, you might use Maven to package the build artifacts into a JAR or WAR file, or you might push a Docker image into Amazon ECR\. Then you might send a build notification through Amazon SNS\. phases/post\_build/**commands** -`commands`: Required if `post_build` is specified\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs after the build\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. -phases/post\_build/**finally** -Optional block\. Commands specified in a `finally` block are executed after commands in the `commands` block\. The commands in a `finally` block are executed even if a command in the `commands` block fails\. For example, if the `commands` block contains three commands and the first fails, CodeBuild skips the remaining two commands and runs any commands in the `finally` block\. The phase is successful when all commands in the `commands` and the `finally` blocks run successfully\. If any command in a phase fails, the phase fails\. - -**Important** -Commands in some build phases might not be run if commands in earlier build phases fail\. For example, if a command fails during the `install` phase, none of the commands in the `pre_build`, `build`, and `post_build` phases are run for that build's lifecycle\. For more information, see [Build phase transitions](view-build-details.md#view-build-details-phases)\. +Required if `post_build` is specified\. Contains a sequence of scalars, where each scalar represents a single command that CodeBuild runs after the build\. CodeBuild runs each command, one at a time, in the order listed, from beginning to end\. ### reports @@ -287,12 +311,30 @@ Required sequence\. Represents the locations that contain the raw data of test r + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. reports//**file\-format** -Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: -+ `CucumberJson` -+ `JunitXml` -+ `NunitXml` -+ `TestNGXml` -+ `VisualStudioTrx` +Optional mapping\. Represents the report file format\. If not specified, `JUNITXML` is used\. This value is not case sensitive\. Possible values are: +**Test reports** + `CUCUMBERJSON` +Cucumber JSON + `JUNITXML` +JUnit XML + `NUNITXML` +NUnit XML + `NUNIT3XML` +NUnit 3 XML + `TESTNGXML` +TestNG XML + `VISUALSTUDIOTRX` +Visual Studio TRX +**Code coverage reports** + `CLOVERXML` +Clover XML + `COBERTURAXML` +Cobertura XML + `JACOCOXML` +JaCoCo XML + `SIMPLECOV` +SimpleCov JSON +CodeBuild accepts JSON code coverage reports generated by [simplecov](https://github.com/simplecov-ruby/simplecov), not [simplecov\-json](https://github.com/vicentllongo/simplecov-json)\. reports//**base\-directory** Optional mapping\. Represents one or more top\-level directories, relative to the original build location, that CodeBuild uses to determine where to find the raw test files\. @@ -304,6 +346,9 @@ Optional\. Specifies if the report file directories are flattened in the output\ Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the S3 output bucket\. This sequence is not required if, for example, you are building and pushing a Docker image to Amazon ECR, or you are running unit tests on your source code, but not building it\. +**Note** +Amazon S3 metadata has a CodeBuild header named `x-amz-meta-codebuild-buildarn` which contains the `buildArn` of the CodeBuild build that publishes artifacts to Amazon S3\. The `buildArn` is added to allow source tracking for notifications and to reference which build the artifact is generated from\. + artifacts/**files** Required sequence\. Represents the locations that contain the build output artifacts in the build environment\. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find build output artifacts, relative to the original build location or, if set, the base directory\. Locations can include the following: + A single file \(for example, `my-file.jar`\)\. @@ -315,36 +360,49 @@ When you specify build output artifact locations, CodeBuild can locate the origi artifacts/**name** Optional name\. Specifies a name for your build artifact\. This name is used when one of the following is true\. -+ You use the CodeBuild API to create your builds and the `overrideArtifactName` flag is set on the `ProjectArtifacts` object when a project is updated, a project is created, or a build is started\. -+ You use the CodeBuild console to create your builds, a name is specified in the buildspec file, and you select **Enable semantic versioning** when you create or update a project\. For more information, see [Create a build project \(console\)](create-project-console.md)\. ++ You use the CodeBuild API to create your builds and the `overrideArtifactName` flag is set on the `ProjectArtifacts` object when a project is updated, a project is created, or a build is started\. ++ You use the CodeBuild console to create your builds, a name is specified in the buildspec file, and you select **Enable semantic versioning** when you create or update a project\. For more information, see [Create a build project \(console\)](create-project-console.md)\. You can specify a name in the buildspec file that is calculated at build time\. The name specified in a buildspec file uses the Shell command language\. For example, you can append a date and time to your artifact name so that it is always unique\. Unique artifact names prevent artifacts from being overwritten\. For more information, see [Shell command language](http://pubs.opengroup.org/onlinepubs/9699919799/)\. -This is an example of an artifact name appended with the date the artifact is created\. - -``` -version: 0.2 -phases: - build: - commands: - - rspec HelloWorld_spec.rb -artifacts: - files: - - '**/*' - name: myname-$(date +%Y-%m-%d) -``` -This is an example of an artifact name that uses a CodeBuild environment variable\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. - -``` -version: 0.2 -phases: - build: - commands: - - rspec HelloWorld_spec.rb -artifacts: - files: - - '**/*' - name: myname-$AWS_REGION -``` -This is an example of an artifact name that uses a CodeBuild environment variable with the artifact's creation date appended to it\. ++ This is an example of an artifact name appended with the date the artifact is created\. + + ``` + version: 0.2 + phases: + build: + commands: + - rspec HelloWorld_spec.rb + artifacts: + files: + - '**/*' + name: myname-$(date +%Y-%m-%d) + ``` ++ This is an example of an artifact name that uses a CodeBuild environment variable\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. + + ``` + version: 0.2 + phases: + build: + commands: + - rspec HelloWorld_spec.rb + artifacts: + files: + - '**/*' + name: myname-$AWS_REGION + ``` ++ This is an example of an artifact name that uses a CodeBuild environment variable with the artifact's creation date appended to it\. + + ``` + version: 0.2 + phases: + build: + commands: + - rspec HelloWorld_spec.rb + artifacts: + files: + - '**/*' + name: $AWS_REGION-$(date +%Y-%m-%d) + ``` +You can add path information to the name so that the named artifacts are placed in directories based on the path in the name\. In this example, build artifacts are placed in the output under `builds//my-artifacts`\. ``` version: 0.2 @@ -355,7 +413,7 @@ phases: artifacts: files: - '**/*' - name: $AWS_REGION-$(date +%Y-%m-%d) + name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts ``` artifacts/**discard\-paths** @@ -369,26 +427,28 @@ Matching top\-level directories are not included in the build output artifact, o You can use `files` and `discard-paths` to further restrict which files and subdirectories are included\. For example, for the following directory structure: ``` -|-- my-build1 -| `-- my-file1.txt -`-- my-build2 - |-- my-file2.txt - `-- my-subdirectory - `-- my-file3.txt +. +├── my-build-1 +│ └── my-file-1.txt +└── my-build-2 + ├── my-file-2.txt + └── my-subdirectory + └── my-file-3.txt ``` And for the following `artifacts` sequence: ``` artifacts: files: - - '*/my-file3.txt' - base-directory: my-build2 + - '*/my-file-3.txt' + base-directory: my-build-2 ``` The following subdirectory and file would be included in the build output artifact: ``` -my-subdirectory - `-- my-file3.txt +. +└── my-subdirectory + └── my-file-3.txt ``` While for the following `artifacts` sequence: @@ -402,11 +462,21 @@ artifacts: The following files would be included in the build output artifact: ``` -|-- my-file1.txt -|-- my-file2.txt -`-- my-file3.txt +. +├── my-file-1.txt +├── my-file-2.txt +└── my-file-3.txt ``` +artifacts/**exclude\-paths** +Optional mapping\. Represents one or more paths, relative to `base-directory`, that CodeBuild will exclude from the build artifacts\. + +artifacts/**enable\-symlinks** +Optional\. If the output type is `ZIP`, specifies if internal symbolic links are preserved in the ZIP file\. If this contains `yes`, all internal symbolic links in the source will be preserved in the artifacts ZIP file\. + +artifacts/**s3\-prefix** +Optional\. Specifies a prefix used when the artifacts are output to an Amazon S3 bucket and the namespace type is `BUILD_ID`\. When used, the output path in the bucket is `//.zip`\. + artifacts/**secondary\-artifacts** Optional sequence\. Represents one or more artifact definitions as a mapping between an artifact identifier and an artifact definition\. Each artifact identifiers in this block must match an artifact defined in the `secondaryArtifacts` attribute of your project\. Each separate definition has the same syntax as the `artifacts` block above\. The [`artifacts/files`](#build-spec.artifacts.files) sequence is always required, even when there are only secondary artifacts defined\. @@ -496,7 +566,7 @@ phases: pre_build: commands: - echo Entered the pre_build phase... - - docker login –u User –p $LOGIN_PASSWORD + - docker login -u User -p $LOGIN_PASSWORD finally: - echo This always runs even if the login command fails build: @@ -521,7 +591,7 @@ reports: files: - 'cucumber/target/cucumber-tests.xml' discard-paths: yes - file-format: CucumberJson # default is JunitXml + file-format: CUCUMBERJSON # default is JUNITXML artifacts: files: - target/messageUtil-1.0.jar @@ -543,7 +613,7 @@ cache: Here is an example of the preceding buildspec, expressed as a single string, for use with the AWS CLI, or the AWS SDKs\. ``` -"version: 0.2\n\nenv:\n variables:\n JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n parameter-store:\n LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n phases:\n\n install:\n commands:\n - echo Entered the install phase...\n - apt-get update -y\n - apt-get install -y maven\n finally:\n - echo This always runs even if the update or install command fails \n pre_build:\n commands:\n - echo Entered the pre_build phase...\n - docker login –u User –p $LOGIN_PASSWORD\n finally:\n - echo This always runs even if the login command fails \n build:\n commands:\n - echo Entered the build phase...\n - echo Build started on `date`\n - mvn install\n finally:\n - echo This always runs even if the install command fails\n post_build:\n commands:\n - echo Entered the post_build phase...\n - echo Build completed on `date`\n\n reports:\n reportGroupJunitXml:\n files:\n - \"**/*\"\n base-directory: 'target/tests/reports'\n discard-paths: false\n reportGroupCucumberJson:\n files:\n - 'cucumber/target/cucumber-tests.xml'\n file-format: CucumberJson\n\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n secondary-artifacts:\n artifact1:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n artifact2:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n cache:\n paths:\n - '/root/.m2/**/*'" +"version: 0.2\n\nenv:\n variables:\n JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n parameter-store:\n LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n phases:\n\n install:\n commands:\n - echo Entered the install phase...\n - apt-get update -y\n - apt-get install -y maven\n finally:\n - echo This always runs even if the update or install command fails \n pre_build:\n commands:\n - echo Entered the pre_build phase...\n - docker login -u User -p $LOGIN_PASSWORD\n finally:\n - echo This always runs even if the login command fails \n build:\n commands:\n - echo Entered the build phase...\n - echo Build started on `date`\n - mvn install\n finally:\n - echo This always runs even if the install command fails\n post_build:\n commands:\n - echo Entered the post_build phase...\n - echo Build completed on `date`\n\n reports:\n reportGroupJunitXml:\n files:\n - \"**/*\"\n base-directory: 'target/tests/reports'\n discard-paths: false\n reportGroupCucumberJson:\n files:\n - 'cucumber/target/cucumber-tests.xml'\n file-format: CUCUMBERJSON\n\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n secondary-artifacts:\n artifact1:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n artifact2:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n cache:\n paths:\n - '/root/.m2/**/*'" ``` Here is an example of the commands in the `build` phase, for use with the CodeBuild or CodePipeline consoles\. @@ -569,4 +639,4 @@ The following table lists the buildspec versions and the changes between version | Version | Changes | | --- | --- | | 0\.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) | -| 0\.1 | This is the initial definition of the build specification format\. | +| 0\.1 | This is the initial definition of the build specification format\. | \ No newline at end of file diff --git a/doc_source/builds-projects-and-builds.md b/doc_source/builds-projects-and-builds.md index c74b519..1fe8386 100644 --- a/doc_source/builds-projects-and-builds.md +++ b/doc_source/builds-projects-and-builds.md @@ -1,6 +1,6 @@ # Working with build projects and builds in AWS CodeBuild - To get started, follow the steps in [Create a build project](create-project.md), and then follow the steps in [Run a build](run-build.md)\. For more information about build projects and builds, see the following topics\. + To get started, follow the steps in [Create a build project](create-project.md) , and then follow the steps in [Run a build](run-build.md) \. For more information about build projects and builds, see the following topics\. **Topics** + [Working with build projects](working-with-build-projects.md) diff --git a/doc_source/builds-working.md b/doc_source/builds-working.md index 9a5102b..a3d3545 100644 --- a/doc_source/builds-working.md +++ b/doc_source/builds-working.md @@ -3,10 +3,13 @@ A *build* represents a set of actions performed by AWS CodeBuild to create output artifacts \(for example, a JAR file\) based on a set of input artifacts \(for example, a collection of Java class files\)\. The following rules apply when you run multiple builds: -+ When possible, builds run concurrently\. The maximum number of concurrently running builds can vary\. For more information, see [Builds](limits.md#limits-builds)\. -+ Builds are queued if the number of concurrently running builds reaches its limit\. The maximum number of builds in a queue is five times the concurrent build limit\. For more information, see [Builds](limits.md#limits-builds)\. -+ A build in a queue that does not start after the number of minutes specified in its time out value is removed from the queue\. The default timeout value is eight hours\. You can override the build queue timeout with a value between five minutes and eight hours when you run your build\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. -+ It is not possible to predict the order in which queued builds start\. ++ When possible, builds run concurrently\. The maximum number of concurrently running builds can vary\. For more information, see [Quotas for AWS CodeBuild](limits.md)\. ++ If the build project has a concurrent build limit set, builds return an error if the number of running builds reaches the concurrent build limit for the project\. For more information, see [Enable concurrent build limit](create-project-console.md#enable-concurrent-build-limit.console)\. ++ If the build project does not have a concurrent build limit set, builds are queued if the number of running builds reaches the concurrent build limit for the platform and compute type\. The maximum number of builds in a queue is five times the concurrent build limit\. For more information, see [Quotas for AWS CodeBuild](limits.md)\. + + A build in a queue that does not start after the number of minutes specified in its time out value is removed from the queue\. The default timeout value is eight hours\. You can override the build queue timeout with a value between five minutes and eight hours when you run your build\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. + + It is not possible to predict the order in which queued builds start\. **Note** You can access the history of a build for one year\. @@ -19,5 +22,7 @@ You can perform these tasks when working with builds: + [View a list of build IDs in AWS CodeBuild](view-build-list.md) + [View a list of build IDs for a build project in AWS CodeBuild](view-builds-for-project.md) + [Stop a build in AWS CodeBuild](stop-build.md) ++ [Stop a batch build in AWS CodeBuild](stop-batch-build.md) ++ [Retry a build in AWS CodeBuild](retry-build.md) + [View a running build in Session Manager](session-manager.md) + [Delete builds in AWS CodeBuild](delete-builds.md) \ No newline at end of file diff --git a/doc_source/change-project-cli.md b/doc_source/change-project-cli.md new file mode 100644 index 0000000..580008f --- /dev/null +++ b/doc_source/change-project-cli.md @@ -0,0 +1,41 @@ +# Change a build project's settings \(AWS CLI\) + +For information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. + +To update a CodeBuild project with the AWS CLI, you create a JSON file with the updated properties and pass that file to the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/update-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/update-project.html) command\. Any properties not contained in the update file remain unchanged\. + +In the update JSON file, only the `name` property and the modified properties are required\. The `name` property identifies the project to modify\. For any modified structures, the required parameters for those structures must also be included\. For example, to modify the environment for the project, the `environment/type` and `environment/computeType` properties are required\. Here is an example that updates the environment image: + +``` +{ + "name": "", + "environment": { + "type": "LINUX_CONTAINER", + "computeType": "BUILD_GENERAL1_SMALL", + "image": "aws/codebuild/amazonlinux2-x86_64-standard:3.0" + } +} +``` + +If you need to obtain the current property values for a project, use the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/batch-get-projects.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/batch-get-projects.html) command to obtain the current properties of the project you are modifying, and write the output to a file\. + +``` +aws codebuild batch-get-projects --names "" > project-info.json +``` + +The *project\-info\.json* file contains an array of projects, so it cannot be used directly to update a project\. You can, however, copy the properties that you want to modify from the *project\-info\.json* file and paste them into your update file as a baseline for the properties you want to modify\. For more information, see [View a build project's details \(AWS CLI\)](view-project-details.md#view-project-details-cli)\. + +Modify the update JSON file as described in [Create a build project \(AWS CLI\)](create-project-cli.md), and save your results\. When you are finished modifying the update JSON file, run the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/update-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/update-project.html) command, passing the update JSON file\. + +``` +aws codebuild update-project --cli-input-json file:// +``` + +If successful, the updated project JSON appears in the output\. If any required parameters are missing, an error message is displayed in the output that identifies the missing parameters\. For example, this is the error message displayed if the `environment/type` parameter is missing: + +``` +aws codebuild update-project --cli-input-json file://update-project.json + +Parameter validation failed: +Missing required parameter in environment: "type" +``` \ No newline at end of file diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md new file mode 100644 index 0000000..67d6018 --- /dev/null +++ b/doc_source/change-project-console.md @@ -0,0 +1,364 @@ +# Change a build project's settings \(console\) + +To change the settings for a build project, perform the following procedure: + +1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. + +1. In the navigation pane, choose **Build projects**\. + +1. Do one of the following: + + Choose the link for the build project you want to change, and then choose **Build details**\. + + Choose the button next to the build project you want to change, choose **View details**, and then choose **Build details**\. + +You can modify the following sections: + +**Topics** ++ [Project configuration](#change-project-console-project-config) ++ [Source](#change-project-console-source) ++ [Environment](#change-project-console-environment) ++ [Buildspec](#change-project-console-buildspec) ++ [Batch configuration](#change-project-console-batch-config) ++ [Artifacts](#change-project-console-artifacts) ++ [Logs](#change-project-console-logs) + +## Project configuration + +In the **Project configuration** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. + +You can modify the following properties\. + +**Description** +Enter an optional description of the build project to help other users understand what this project is used for\. + +**Build badge** +Select **Enable build badge** to make your project's build status visible and embeddable\. For more information, see [Build badges sample](sample-build-badges.md)\. +Build badge does not apply if your source provider is Amazon S3\. + +**Enable concurrent build limit** +If you want to limit the number of concurrent builds for this project, perform the following steps: + +1. Select **Restrict number of concurrent builds this project can start**\. + +1. In **Concurrent build limit**, enter the maximum number of concurrent builds that are allowed for this project\. This limit cannot be greater than the concurrent build limit set for the account\. If you try to enter a number greater than the account limit, an error message is displayed\. +New builds are only started if the current number of builds is less than or equal to this limit\. If the current build count meets this limit, new builds are throttled and are not run\. + +**Enable public build access** +To make your project's build results available to the public, including users without access to an AWS account, select **Enable public build access** and confirm that you want to make the build results public\. The following properties are used for public build projects: +**Public build service role** +Select **New service role** if you want to have CodeBuild create a new service role for you, or **Existing service role** if you want to use an existing service role\. +The public build service role enables CodeBuild to read the CloudWatch Logs and download the Amazon S3 artifacts for the project's builds\. This is required to make the project's build logs and artifacts available to the public\. +**Service role** +Enter the name of the new service role or an existing service role\. +To make your project's build results private, clear **Enable public build access**\. +For more information, see [Public build projects in AWS CodeBuild](public-builds.md)\. +The following should be kept in mind when making your project's build results public: ++ All of a project's build results, logs, and artifacts, including builds that were run when the project was private, are available to the public\. ++ All build logs and artifacts are available to the public\. Environment variables, source code, and other sensitive information may have been output to the build logs and artifacts\. You must be careful about what information is output to the build logs\. Some best practices are: + + Do not store sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. We recommend that you use an Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager to store sensitive values\. + + Follow [Best practices for using webhooks](webhooks.md#webhook-best-practices) to limit which entities can trigger a build, and do not store the buildspec in the project itself, to ensure that your webhooks are as secure as possible\. ++ A malicious user can use public builds to distribute malicious artifacts\. We recommend that project administrators review all pull requests to verify that the pull request is a legitimate change\. We also recommend that you validate any artifacts with their checksums to make sure that the correct artifacts are being downloaded\. + +**Additional information** +For **Tags**, enter the name and value of any tags that you want supporting AWS services to use\. Use **Add row** to add a tag\. You can add up to 50 tags\. + +## Source + +In the **Source** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. + +You can modify the following properties: + +**Source provider** +Choose the source code provider type\. Use the following lists to make selections appropriate for your source provider: +CodeBuild does not support Bitbucket Server\. + +------ +#### [ Amazon S3 ] + + **Bucket** +Choose the name of the input bucket that contains the source code\. + + **S3 object key or S3 folder** +Enter the name of the ZIP file or the path to the folder that contains the source code\. Enter a forward slash \(/\) to download everything in the S3 bucket\. + + **Source version** +Enter the version ID of the object that represents the build of your input file\. For more information, see[Source version sample with AWS CodeBuild](sample-source-version.md)\. + +------ +#### [ CodeCommit ] + + **Repository** +Choose the repository you want to use\. + +**Reference type** +Choose **Branch**, **Git tag**, or **Commit ID** to specify the version of your source code\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md)\. + + **Git clone depth** +Choose to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. + +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. + +------ +#### [ Bitbucket ] + + **Repository** +Choose **Connect using OAuth** or **Connect with a Bitbucket app password ** and follow the instructions to connect \(or reconnect\) to Bitbucket\. +Choose a public repository or a repository in your account\. + + **Source version** +Enter a branch, commit ID, tag, or reference and a commit ID\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md) + + **Git clone depth** +Choose **Git clone depth** to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. + +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. + +**Build status** +Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. +For **Status context**, enter the value to be used for the `name` parameter in the Bitbucket commit status\. For more information, see [build](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build) in the Bitbucket API documentation\. +For **Target URL**, enter the value to be used for the `url` parameter in the Bitbucket commit status\. For more information, see [build](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build) in the Bitbucket API documentation\. +The status of a build triggered by a webhook is always reported to the source provider\. To have the status of a build that is started from the console or an API call reported to the source provider, you must select this setting\. +If your project's builds are triggered by a webhook, you must push a new commit to the repo for a change to this setting to take effect\. + +In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. For more information about webhooks and filter groups, see [Bitbucket webhook events](bitbucket-webhook.md)\. + +------ +#### [ GitHub ] + + **Repository** +Choose **Connect using OAuth** or **Connect with a GitHub personal access token ** and follow the instructions to connect \(or reconnect\) to GitHub and authorize access to AWS CodeBuild\. +Choose a public repository or a repository in your account\. + + **Source version** +Enter a branch, commit ID, tag, or reference and a commit ID\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md) + + **Git clone depth** +Choose **Git clone depth** to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. + +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. + +**Build status** +Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. +For **Status context**, enter the value to be used for the `context` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +For **Target URL**, enter the value to be used for the `target_url` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +The status of a build triggered by a webhook is always reported to the source provider\. To have the status of a build that is started from the console or an API call reported to the source provider, you must select this setting\. +If your project's builds are triggered by a webhook, you must push a new commit to the repo for a change to this setting to take effect\. + +In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. For more information about webhooks and filter groups, see [GitHub webhook events](github-webhook.md)\. + +------ +#### [ GitHub Enterprise Server ] + +**GitHub Enterprise personal access token** +See [GitHub Enterprise Server sample](sample-github-enterprise.md) for information about how to copy a personal access token to your clipboard\. Paste the token in the text field, and then choose **Save Token**\. +You only need to enter and save the personal access token once\. CodeBuild uses this token in all future projects\. + +**Source version** +Enter a pull request, branch, commit ID, tag, or reference and a commit ID\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md)\. + +**Git clone depth** +Choose **Git clone depth** to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. + +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. + +**Build status** +Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. +For **Status context**, enter the value to be used for the `context` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +For **Target URL**, enter the value to be used for the `target_url` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +The status of a build triggered by a webhook is always reported to the source provider\. To have the status of a build that is started from the console or an API call reported to the source provider, you must select this setting\. +If your project's builds are triggered by a webhook, you must push a new commit to the repo for a change to this setting to take effect\. + +**Insecure SSL** +Select **Enable insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. + +In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. For more information about webhooks and filter groups, see [GitHub webhook events](github-webhook.md)\. + +------ + +## Environment + +In the **Environment** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. + +You can modify the following properties: + +**Environment image** +To change the build image, choose **Override image** and do one of the following: ++ To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. ++ To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. ++ To use a private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. +CodeBuild overrides the `ENTRYPOINT` for custom Docker images\. + +**Privileged** +Select **Privileged** only if you plan to use this build project to build Docker images, and the build environment image you chose is not provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it\. One way to do this is to initialize the Docker daemon in the `install` phase of your build spec by running the following build commands\. Do not run these commands if you chose a build environment image provided by CodeBuild with Docker support\. +By default, Docker containers do not allow access to any devices\. Privileged mode grants a build project's Docker container access to all devices\. For more information, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. + +``` +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & +- timeout 15 sh -c "until docker info; do echo .; sleep 1; done" +``` + +**Service role** +Do one of the following: ++ If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. ++ If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. +When you use the console to create a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. + +**Additional configuration** +**Timeout** +Specify a value, between 5 minutes and 8 hours, after which CodeBuild stops the build if it is not complete\. If **hours** and **minutes** are left blank, the default value of 60 minutes is used\. +**VPC** +If you want CodeBuild to work with your VPC: ++ For **VPC**, choose the VPC ID that CodeBuild uses\. ++ For **VPC Subnets**, choose the subnets that include resources that CodeBuild uses\. ++ For **VPC Security groups**, choose the security groups that CodeBuild uses to allow access to resources in the VPCs\. +For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. +**Compute** +Choose one of the available options\. +**Environment variables** +Enter the name and value, and then choose the type of each environment variable for builds to use\. +CodeBuild sets the environment variable for your AWS Region automatically\. You must set the following environment variables if you haven't added them to your buildspec\.yml: ++ AWS\_ACCOUNT\_ID ++ IMAGE\_REPO\_NAME ++ IMAGE\_TAG +Console and AWS CLI users can see environment variables\. If you have no concerns about the visibility of your environment variable, set the **Name** and **Value** fields, and then set **Type** to **Plaintext**\. +We recommend that you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager\. +If you use Amazon EC2 Systems Manager Parameter Store, then for **Type**, choose **Parameter**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter the parameter's name as stored in Amazon EC2 Systems Manager Parameter Store\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, for **Type**, choose **Parameter**\. For **Name**, enter `LOGIN_PASSWORD`\. For **Value**, enter `/CodeBuild/dockerLoginPassword`\. +If you use Amazon EC2 Systems Manager Parameter Store, we recommend that you store parameters with parameter names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager\. Choose **Create parameter**, and then follow the instructions in the dialog box\. \(In that dialog box, for **KMS key**, you can specify the ARN of an AWS KMS key in your account\. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt it during retrieval\.\) If you use the CodeBuild console to create a parameter, the console starts the parameter name with `/CodeBuild/` as it is being stored\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store Console Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. +If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the `ssm:GetParameters` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. +If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update that service role to allow access to parameter names that do not start with `/CodeBuild/`\. This is because that service role allows access only to parameter names that start with `/CodeBuild/`\. +If you choose **New service role**, the service role includes permission to decrypt all parameters under the `/CodeBuild/` namespace in the Amazon EC2 Systems Manager Parameter Store\. +Environment variables you set replace existing environment variables\. For example, if the Docker image already contains an environment variable named `MY_VAR` with a value of `my_value`, and you set an environment variable named `MY_VAR` with a value of `other_value`, then `my_value` is replaced by `other_value`\. Similarly, if the Docker image already contains an environment variable named `PATH` with a value of `/usr/local/sbin:/usr/local/bin`, and you set an environment variable named `PATH` with a value of `$PATH:/usr/share/ant/bin`, then `/usr/local/sbin:/usr/local/bin` is replaced by the literal value `$PATH:/usr/share/ant/bin`\. +Do not set any environment variable with a name that begins with `CODEBUILD_`\. This prefix is reserved for internal use\. +If an environment variable with the same name is defined in multiple places, the value is determined as follows: ++ The value in the start build operation call takes highest precedence\. ++ The value in the build project definition takes next precedence\. ++ The value in the buildspec declaration takes lowest precedence\. +If you use Secrets Manager, for **Type**, choose **Secrets Manager**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter a `reference-key` using the pattern `secret-id:json-key:version-stage:version-id`\. For information, see [Secrets Manager reference-key in the buildspec file](build-spec-ref.md#secrets-manager-build-spec)\. +If you use Secrets Manager, we recommend that you store secrets with names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*\. +If your build project refers to secrets stored in Secrets Manager, the build project's service role must allow the `secretsmanager:GetSecretValue` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. +If your build project refers to secrets stored in Secrets Manager with secret names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update the service role to allow access to secret names that do not start with `/CodeBuild/`\. This is because the service role allows access only to secret names that start with `/CodeBuild/`\. +If you choose **New service role**, the service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. + +## Buildspec + +In the **Buildspec** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. + +You can modify the following properties: + +**Build specifications** +Do one of the following: ++ If your source code includes a buildspec file, choose **Use a buildspec file**\. By default, CodeBuild looks for a file named `buildspec.yml` in the source code root directory\. If your buildspec file uses a different name or location, enter its path from the source root in **Buildspec name** \(for example, `buildspec-two.yml` or `configuration/buildspec.yml`\. If the buildspec file is in an S3 bucket, it must be in the same AWS Region as your build project\. Specify the buildspec file using its ARN \(for example, `arn:aws:s3:::my-codebuild-sample2/buildspec.yml`\)\. ++ If your source code does not include a buildspec file, or if you want to run build commands different from the ones specified for the `build` phase in the `buildspec.yml` file in the source code's root directory, choose **Insert build commands**\. For **Build commands**, enter the commands you want to run in the `build` phase\. For multiple commands, separate each command by `&&` \(for example, `mvn test && mvn package`\)\. To run commands in other phases, or if you have a long list of commands for the `build` phase, add a `buildspec.yml` file to the source code root directory, add the commands to the file, and then choose **Use the buildspec\.yml in the source code root directory**\. +For more information, see the [Buildspec reference](build-spec-ref.md)\. + +## Batch configuration + +In the **Batch configuration** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. For more information, see [Batch builds in AWS CodeBuild](batch-build.md)\. + +You can modify the following properties: + +**Batch service role** +Provides the service role for batch builds\. +Choose one of the following: ++ If you do not have a batch service role, choose **New service role**\. In **Service role**, enter a name for the new role\. ++ If you have a batch service role, choose **Existing service role**\. In **Service role**, choose the service role\. +Batch builds introduce a new security role in the batch configuration\. This new role is required as CodeBuild must be able to call the `StartBuild`, `StopBuild`, and `RetryBuild` actions on your behalf to run builds as part of a batch\. Customers should use a new role, and not the same role they use in their build, for two reasons: ++ Giving the build role `StartBuild`, `StopBuild`, and `RetryBuild` permissions would allow a single build to start more builds via the buildspec\. ++ CodeBuild batch builds provide restrictions that restrict the number of builds and compute types that can be used for the builds in the batch\. If the build role has these permissions, it is possible the builds themselves could bypass these restrictions\. + +**Allowed compute type\(s\) for batch** +Select the compute types allowed for the batch\. Select all that apply\. + +**Maximum builds allowed in batch** +Enter the maximum number of builds allowed in the batch\. If a batch exceeds this limit, the batch will fail\. + +**Batch timeout** +Enter the maximum amount of time for the batch build to complete\. + +**Combine artifacts** +Select **Combine all artifacts from batch into a single location** to have all of the artifacts from the batch combined into a single location\. + + **Batch report mode** +Select the desired build status report mode for batch builds\. +This field is only available when the project source is Bitbucket, GitHub, or GitHub Enterprise, and **Report build statuses to source provider when your builds start and finish** is selected under **Source**\. + **Aggregated builds** +Select to have the statuses for all builds in the batch combined into a single status report\. + **Individual builds** +Select to have the build statuses for all builds in the batch reported separately\. + +## Artifacts + +In the **Artifacts** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. + +You can modify the following properties: + +**Type** +Do one of the following: ++ If you do not want to create any build output artifacts, choose **No artifacts**\. You might want to do this if you're only running build tests or you want to push a Docker image to an Amazon ECR repository\. ++ To store the build output in an S3 bucket, choose **Amazon S3**, and then do the following: + + If you want to use your project name for the build output ZIP file or folder, leave **Name** blank\. Otherwise, enter the name\. \(If you want to output a ZIP file, and you want the ZIP file to have a file extension, be sure to include it after the ZIP file name\.\) + + Select **Enable semantic versioning** if you want a name specified in the buildspec file to override any name that is specified in the console\. The name in a buildspec file is calculated at build time and uses the Shell command language\. For example, you can append a date and time to your artifact name so that it is always unique\. Unique artifact names prevent artifacts from being overwritten\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + For **Bucket name**, choose the name of the output bucket\. + + If you chose **Insert build commands** earlier in this procedure, then for **Output files**, enter the locations of the files from the build that you want to put into the build output ZIP file or folder\. For multiple locations, separate each location with a comma \(for example, `appspec.yml, target/my-app.jar`\)\. For more information, see the description of `files` in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + If you do not want your build artifacts encrypted, select **Remove artifacts encryption**\. +For each secondary set of artifacts you want: + +1. For **Artifact identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. + +1. Choose **Add artifact**\. + +1. Follow the previous steps to configure your secondary artifacts\. + +1. Choose **Save artifact**\. + +**Additional configuration** +**Encryption key** +Do one of the following: ++ To use the AWS managed key Amazon S3 in your account to encrypt the build output artifacts, leave **Encryption key** blank\. This is the default\. ++ To use a customer managed key to encrypt the build output artifacts, in **Encryption key**, enter the ARN of the customer managed key\. Use the format `arn:aws:kms:region-ID:account-ID:key/key-ID`\. +**Cache type** +For **Cache type**, choose one of the following: ++ If you do not want to use a cache, choose **No cache**\. ++ If you want to use an Amazon S3 cache, choose **Amazon S3**, and then do the following: + + For **Bucket**, choose the name of the S3 bucket where the cache is stored\. + + \(Optional\) For **Cache path prefix**, enter an Amazon S3 path prefix\. The **Cache path prefix** value is similar to a directory name\. It makes it possible for you to store the cache under the same directory in a bucket\. +**Important** +Do not append a trailing slash \(/\) to the end of the path prefix\. ++ If you want to use a local cache, choose **Local**, and then choose one or more local cache modes\. +**Note** +Docker layer cache mode is available for Linux only\. If you choose it, your project must run in privileged mode\. +Using a cache saves considerable build time because reusable pieces of the build environment are stored in the cache and used across builds\. For information about specifying a cache in the buildspec file, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build caching in AWS CodeBuild](build-caching.md)\. + +## Logs + +In the **Logs** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. + +You can modify the following properties: + +Choose the logs you want to create\. You can create Amazon CloudWatch Logs, Amazon S3 logs, or both\. + +**CloudWatch** +If you want Amazon CloudWatch Logs logs: +**CloudWatch logs** +Select **CloudWatch logs**\. +**Group name** +Enter the name of your Amazon CloudWatch Logs log group\. +**Stream name** +Enter your Amazon CloudWatch Logs log stream name\. + +**S3** +If you want Amazon S3 logs: +**S3 logs** +Select **S3 logs**\. +**Bucket** +Choose the name of the S3 bucket for your logs\. +**Path prefix** +Enter the prefix for your logs\. +**Disable S3 log encryption** +Select if you do not want your S3 logs encrypted\. \ No newline at end of file diff --git a/doc_source/change-project-sdks.md b/doc_source/change-project-sdks.md new file mode 100644 index 0000000..88d0cb4 --- /dev/null +++ b/doc_source/change-project-sdks.md @@ -0,0 +1,3 @@ +# Change a build project's settings \(AWS SDKs\) + +For information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file diff --git a/doc_source/change-project.md b/doc_source/change-project.md index b4352f5..a9fb3ec 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -5,144 +5,6 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to change a build pr If you add test reporting to a build project, make sure your IAM role has the permissions described in [Working with test report permissions](test-permissions.md)\. **Topics** -+ [Change a build project's settings \(console\)](#change-project-console) -+ [Change a build project's settings \(AWS CLI\)](#change-project-cli) -+ [Change a build project's settings \(AWS SDKs\)](#change-project-sdks) - -## Change a build project's settings \(console\) - -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. In the navigation pane, choose **Build projects**\. - -1. Do one of the following: - + Choose the link for the build project you want to change, and then choose **Build details**\. - + Choose the button next to the build project you want to change, choose **View details**, and then choose **Build details**\. - -1. To change the project's description, in **Project configuration**, choose **Edit**, and then enter a description\. - - Choose **Update configuration**\. - - For more information about settings referred to in this procedure, see [Create a build project \(console\)](create-project-console.md)\. - -1. To change information about the source code location, in **Source**, choose **Edit**\. Use the following table to make selections appropriate for your source provider, and then choose **Update source**\. -**Note** -CodeBuild does not support Bitbucket Server\. -**** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/change-project.html) - - To change whether CodeBuild can modify the service role you use for this project, select or clear **Allow AWS CodeBuild to modify this service role so it can be used with this build project**\. If you clear it, you must use a service role with CodeBuild permissions attached to it\. For more information, see [Add CodeBuild access permissions to an IAM group or IAM user](setting-up.md#setting-up-service-permissions-group) and [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. - -1. To change information about the build environment, in **Environment**, choose **Edit**\. Make changes appropriate for the build environment type \(for example, **Environment image**, **Operating system**, **Runtime**, **Runtime version**, **Custom image**, **Other location**, **Amazon ECR repository**, or **Amazon ECR image**\)\. - -1. If you plan to use this build project to build Docker images and the specified build environment is not provided by CodeBuild with Docker support, select **Privileged**\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it as needed\. You can do this by by running the following build commands to initialize the Docker daemon in the `install` phase of your buildspec file\. \(Do not run the following build commands if the specified build environment image is provided by CodeBuild with Docker support\.\) -**Note** -By default, Docker containers do not allow access to any devices\. Privileged mode grants a build project's Docker container access to all devices\. For more information, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. - - ``` - - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay& - - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" - ``` - -1. To change information about the CodeBuild service role, in **Service role**, change the values for **New service role**, **Existing service role**, or **Role name**\. -**Note** -When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. - -1. To change information about the build timeout, in **Additional configuration**, for **Timeout**, change the values for **hours** and **minutes**\. If **hours** and **minutes** are left blank, the default value is 60 minutes\. - -1. To change information about the VPC you created in Amazon VPC, in **Additional configuration**, change the values for **VPC**, **Subnets**, and **Security groups**\. - -1. To change information about a file system you created in Amazon EFS, in **Additional configuration**, change its values for **Identifier**, **ID**, **Directory path**, **Mount point**, and **Mount options**\. For more information, see [Amazon Elastic File System sample for AWS CodeBuild](sample-efs.md)\. - -1. To change the amount of memory and vCPUs that are used to run builds, in **Additional configuration**, change the value for **Compute**\. - -1. To change information about environment variables you want builds to use, in **Additional configuration**, for **Environment variables**, change the values for **Name**, **Value**, and **Type**\. Use **Add environment variable** to add an environment variable\. Choose **Remove** next to an environment variable you no longer want to use\. - - Others can see environment variables by using the CodeBuild console and the AWS CLI\. If you have no concerns about the visibility of your environment variable, set the **Name** and **Value** fields, and then set **Type** to **Plaintext**\. - - We recommend that you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager\. - - If you use Amazon EC2 Systems Manager Parameter Store, then for **Type**, choose **Parameter**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter the parameter's name as stored in Amazon EC2 Systems Manager Parameter Store\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, for **Type**, choose **Parameter**\. For **Name**, enter `LOGIN_PASSWORD`\. For **Value**, type `/CodeBuild/dockerLoginPassword`\. -**Important** -If you use Amazon EC2 Systems Manager Parameter Store, we recommend that you store parameters with parameter names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager\. Choose **Create parameter**, and then follow the instructions in the dialog box\. \(In that dialog box, for **KMS key**, you can specify the ARN of an AWS KMS key in your account\. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt it during retrieval\.\) If you use the CodeBuild console to create a parameter, the console starts the parameter name with `/CodeBuild/` as it is being stored\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store Console Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. -If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the `ssm:GetParameters` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. -If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update that service role to allow access to parameter names that do not start with `/CodeBuild/`\. This is because that service role allows access only to parameter names that start with `/CodeBuild/`\. -If you choose **New service role**, the service role includes permission to decrypt all parameters under the `/CodeBuild/` namespace in the Amazon EC2 Systems Manager Parameter Store\. -Environment variables you set replace existing environment variables\. For example, if the Docker image already contains an environment variable named `MY_VAR` with a value of `my_value`, and you set an environment variable named `MY_VAR` with a value of `other_value`, then `my_value` is replaced by `other_value`\. Similarly, if the Docker image already contains an environment variable named `PATH` with a value of `/usr/local/sbin:/usr/local/bin`, and you set an environment variable named `PATH` with a value of `$PATH:/usr/share/ant/bin`, then `/usr/local/sbin:/usr/local/bin` is replaced by the literal value `$PATH:/usr/share/ant/bin`\. -Do not set any environment variable with a name that begins with `CODEBUILD_`\. This prefix is reserved for internal use\. -If an environment variable with the same name is defined in multiple places, the value is determined as follows: -The value in the start build operation call takes highest precedence\. -The value in the build project definition takes next precedence\. -The value in the buildspec declaration takes lowest precedence\. - - If you use Secrets Manager, for **Type**, choose **Secrets Manager**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter a `reference-key` using the pattern `secret-id:json-key:version-stage:version-id`\. For information, see [Secrets Manager reference-key in the buildspec file](build-spec-ref.md#secrets-manager-build-spec)\. -**Important** -If you use Secrets Manager, we recommend that you store secrets with names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*\. -If your build project refers to secrets stored in Secrets Manager, the build project's service role must allow the `secretsmanager:GetSecretValue` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. -If your build project refers to secrets stored in Secrets Manager with secret names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update the service role to allow access to secret names that do not start with `/CodeBuild/`\. This is because the service role allows access only to secret names that start with `/CodeBuild/`\. -If you choose **New service role**, the service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. - -1. Choose **Update environment**\. - -1. To change the project's build specifications, in **Buildspec**, choose **Edit**\. By default, CodeBuild looks for a file named `buildspec.yml` in the source code root directory\. If your buildspec file uses a different name or location, enter its path from the source root in **Buildspec name** \(for example, **buildspec\-two\.yml** or **configuration/buildspec\.yml**\. If the buildspec file is in an S3 bucket, it must be in the same AWS Region as your build project\. Specify the buildspec file using its ARN \(for example, `arn:aws:s3:::my-codebuild-sample2/buildspec.yml`\)\. - + If your source code previously did not include a buildspec\.yml file but does now, choose **Use a buildspec file**\. - + If your source code previously included a buildspec\.yml file but does not now, choose **Insert build commands**, and in **Build commands**, enter the commands\. - -1. Choose **Update buildspec**\. - -1. To change information about the build output artifact location and name, in **Artifacts**, choose **Edit**, and then change the values for **Type**, **Name**, **Path**, **Namespace type**, or **Bucket name**\. - -1. To change information about the AWS KMS customer managed key \(CMK\), in **Additional configuration**, change the value for **Encryption key**\. -**Important** -If you leave **Encryption key** blank, CodeBuild uses the AWS\-managed CMK for Amazon S3 in your AWS account instead\. - -1. Using a cache saves build time because reusable pieces of the build environment are stored in the cache and used across builds\. For information about specifying a cache in the buildspec file, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. To change information about the cache, expand **Additional configuration**\. In **Cache type**, do one of the following: - + If you previously chose a cache, but do not want to use one now, choose **No cache**\. - + If you previously chose **No cache** but now want to use one, choose **Amazon S3**, and then do the following: - + For **Cache bucket**, choose the name of the S3 bucket where the cache is stored\. - + \(Optional\) For **Cache path prefix**, enter an Amazon S3 path prefix\. The cache path prefix value is similar to a directory name\. You use it to store the cache under the same directory in a bucket\. -**Important** -Do not append a forward slash \(/\) to the end of **Path prefix**\. - -1. To change your log settings, in **Logs**, select or clear **CloudWatch logs** and **S3 logs**\. - - If you select **CloudWatch logs**: - + In **Group name**, enter the name of your Amazon CloudWatch Logs group\. - + In **Stream name**, enter your Amazon CloudWatch Logs stream name\. - - If you select **S3 logs**: - + From **Bucket**, choose the name of the S3 bucket for your logs\. - + In **Path prefix**, enter the prefix for your logs\. - + Select **Remove S3 log encryption** if you do not want your S3 logs encrypted\. - -1. To change information about the way build output artifacts are stored, in **Additional configuration**, change the value of **Artifacts packaging**\. - -1. To change whether build artifacts are encrypted, use **Disable artifacts encryption**\. - -1. Choose **Update artifacts**\. - -## Change a build project's settings \(AWS CLI\) - -For information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. - -1. Run the `update-project` command as follows: - - ``` - aws codebuild update-project --generate-cli-skeleton - ``` - - JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `update-project.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Then modify the copied data as described in [Create a build project \(AWS CLI\)](create-project-cli.md), and save your results\. -**Note** -In the JSON\-formatted data, you must provide the name of the build project\. All other settings are optional\. You cannot change the build project's name, but you can change any of its other settings\. - -1. Switch to the directory that contains the file you just saved, and run the update\-project command again\. - - ``` - aws codebuild update-project --cli-input-json file://update-project.json - ``` - -1. If successful, data similar to that described in [Create a build project \(AWS CLI\)](create-project-cli.md) appears in the output\. - -## Change a build project's settings \(AWS SDKs\) - -For information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file ++ [Change a build project's settings \(console\)](change-project-console.md) ++ [Change a build project's settings \(AWS CLI\)](change-project-cli.md) ++ [Change a build project's settings \(AWS SDKs\)](change-project-sdks.md) \ No newline at end of file diff --git a/doc_source/cloudformation-vpc-template.md b/doc_source/cloudformation-vpc-template.md index 0ec2130..6ef2c44 100644 --- a/doc_source/cloudformation-vpc-template.md +++ b/doc_source/cloudformation-vpc-template.md @@ -2,7 +2,7 @@ AWS CloudFormation enables you to create and provision AWS infrastructure deployments predictably and repeatedly, by using template files to create and delete a collection of resources together as a single unit \(a *stack*\)\. For more information, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. -The following is an AWS CloudFormation YAML template for configuring a VPC to use AWS CodeBuild\. +The following is an AWS CloudFormation YAML template for configuring a VPC to use AWS CodeBuild\. This file is also available in [samples\.zip](./samples/samples.zip)\. ``` Description: This template deploys a VPC, with a pair of public and private subnets spread diff --git a/doc_source/cmd-ref.md b/doc_source/cmd-ref.md index 3980b4a..245df2f 100644 --- a/doc_source/cmd-ref.md +++ b/doc_source/cmd-ref.md @@ -32,4 +32,4 @@ CodeBuild commands include: + `list-projects`: Gets a list of build project names\. For more information, see [View a list of build project names \(AWS CLI\)](view-project-list.md#view-project-list-cli)\. + `start-build`: Starts running a build\. For more information, see [Run a build \(AWS CLI\)](run-build-cli.md)\. + `stop-build`: Attempts to stop the specified build from running\. For more information, see [Stop a build \(AWS CLI\)](stop-build.md#stop-build-cli)\. -+ `update-project`: Changes information about the specified build project\. For more information, see [Change a build project's settings \(AWS CLI\)](change-project.md#change-project-cli)\. \ No newline at end of file ++ `update-project`: Changes information about the specified build project\. For more information, see [Change a build project's settings \(AWS CLI\)](change-project-cli.md)\. \ No newline at end of file diff --git a/doc_source/code-coverage-report.md b/doc_source/code-coverage-report.md new file mode 100644 index 0000000..e304e18 --- /dev/null +++ b/doc_source/code-coverage-report.md @@ -0,0 +1,51 @@ +# Code coverage reports + +## + +CodeBuild allows you to generate code coverage reports for your tests\. The following code coverage reports are provided: + +Line coverage +Line coverage measures how many statements your tests cover\. A statement is a single instruction, not including comments or conditionals\. +`line coverage = (total lines covered)/(total number of lines)` + +Branch coverage +Branch coverage measures how many branches your tests cover out of every possible branch of a control structure, such as an `if` or `case` statement\. +`branch coverage = (total branches covered)/(total number of branches)` + +The following code coverage report file formats are supported: ++ JaCoCo XML ++ SimpleCov JSON¹ ++ Clover XML ++ Cobertura XML + +¹ CodeBuild accepts JSON code coverage reports generated by [simplecov](https://github.com/simplecov-ruby/simplecov), not [simplecov\-json](https://github.com/vicentllongo/simplecov-json)\. + +## Create a code coverage report + +To create a code coverage report, you run a build project that is configured with at least one code coverage report group in its buildspec file\. CodeBuild will interpret the code coverage results and provide a code coverage report for the run\. A new test report is generated for each subsequent build that uses the same buildspec file\. + +**To create a test report** + +1. Create a build project\. For information, see [Create a build project in AWS CodeBuild](create-project.md)\. + +1. Configure the buildspec file of your project with test report information: + + 1. Add a `reports:` section and specify the name for your report group\. CodeBuild creates a report group for you using your project name and the name you specified in the format `project-name`\-`report-group-name-in-buildspec`\. If you already have a report group you want to use, specify its ARN\. If you use the name instead of the ARN, CodeBuild creates a new report group\. For more information, see [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. + + 1. Under the report group, specify the location of the files that contain the code coverage results\. If you use more than one report group, specify result file locations for each report group\. A new code coverage report is created each time your build project runs\. For more information, see [Specify test files](report-group-test-cases.md)\. + + This is an example that generates a code coverage report for a JaCoCo XML results file located in test\-`results/jacoco-coverage-report.xml`\. + + ``` + reports: + jacoco-report: + files: + - 'test-results/jacoco-coverage-report.xml' + file-format: 'JACOCOXML' + ``` + + 1. In the `commands` section of the `build` or `post_build` sequence, specify the commands that run the code coverage analysis\. For more information, see [ Specify test commands ](report-group-test-case-commands.md)\. + +1. Run a build of the build project\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. + +1. When the build is complete, choose the new build run from **Build history** on your project page\. Choose **Reports** to view the code coverage report\. For more information, see [View test reports for a build](test-view-reports.md#test-view-project-reports)\. \ No newline at end of file diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index de4e9f1..aaa06ee 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -15,7 +15,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif 1. When token information is displayed, choose **Copy**\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-token.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) -1. Add the copied token as an environment variable named `CODECOV_TOKEN` to your build project\. For more information, see [Change a build project's settings \(console\)](change-project.md#change-project-console)\. +1. Add the copied token as an environment variable named `CODECOV_TOKEN` to your build project\. For more information, see [Change a build project's settings \(console\)](change-project-console.md)\. 1. Create a text file named `my_script.sh` in your repository\. Enter the following into the file: @@ -96,7 +96,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif \_____\___/ \__,_|\___|\___\___/ \_/ Bash-20200303-bc4d7e6 - ·[0;90m==>·[0m AWS Codebuild detected. + ·[0;90m==>·[0m AWS CodeBuild detected. ... The full list of Codecov log entries has been omitted for brevity ... · ·[0;32m->·[0m View reports at ·[0;36mhttps://codecov.io/github/user/test_py/commit/commit-id·[0m diff --git a/doc_source/concepts.md b/doc_source/concepts.md index 90d30ab..5596971 100644 --- a/doc_source/concepts.md +++ b/doc_source/concepts.md @@ -10,8 +10,12 @@ The following concepts are important for understanding how CodeBuild works\. The following diagram shows what happens when you run a build with CodeBuild: + + ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/arch.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + 1. As input, you must provide CodeBuild with a build project\. A *build project* includes information about how to run a build, including where to get the source code, which build environment to use, which build commands to run, and where to store the build output\. A *build environment* represents a combination of operating system, programming language runtime, and tools that CodeBuild uses to run a build\. For more information, see: + [Create a build project](create-project.md) + [Build environment reference](build-env-ref.md) diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 50c2853..3f0dec7 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -1,321 +1,361 @@ # Create a build project \(AWS CLI\) -For information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md)\. - -1. Run the create\-project command: - - ``` - aws codebuild create-project --generate-cli-skeleton - ``` - - JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `create-project.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Modify the copied data as follows, and save your results\. - - ``` - { - "name": "project-name", - "description": "description", - "source": { - "type": "source-type", - "location": "source-location", - "gitCloneDepth": "gitCloneDepth", - "buildspec": "buildspec", - "InsecureSsl": "InsecureSsl", - "reportBuildStatus": reportBuildStatus", - "buildStatusConfig": { - "context": context, - "targetUrl": target-url - }, - "gitSubmodulesConfig": { - "fetchSubmodules": "fetchSubmodules" - }, - "auth": { - "type": "auth-type", - "resource": "resource" - } - }, - "sourceVersion": "source-version", - "secondarySourceVersions": { - "sourceIdentifier": "secondary-source-identifier", - "sourceVersion": "secondary-source-version" - }, - "artifacts": { - "type": "artifacts-type", - "location": "artifacts-location", - "path": "path", - "namespaceType": "namespaceType", - "name": "artifacts-name", - "overrideArtifactName": "override-artifact-name", - "packaging": "packaging" - }, - "cache": { - "type": "cache-type", - "location": "cache-location", - "mode": [ - "cache-mode" - ] - }, - "logsConfig": { - "cloudWatchLogs": { - "status": "cloudwatch-logs-status", - "groupName": "group-name", - "streamName": "stream-name" - } - "s3Logs": { - "status": "s3-logs-status", - "location": "s3-logs-location", - "encryptionDisabled": "s3-logs-encryptionDisabled" - } - } - "secondaryArtifacts": [ - { - "type": "artifacts-type", - "location": "artifacts-location", - "path": "path", - "namespaceType": "namespaceType", - "name": "artifacts-name", - "packaging": "packaging", - "artifactIdentifier": "artifact-identifier" - } - ] - , - "secondarySources": [ - { - "type": "source-type", - "location": "source-location", - "gitCloneDepth": "gitCloneDepth", - "buildspec": "buildspec", - "InsecureSsl": "InsecureSsl", - "reportBuildStatus": "reportBuildStatus", - "auth": { - "type": "auth-type", - "resource": "resource" - }, - "sourceIdentifier": "source-identifier" - } - ], - "serviceRole": "serviceRole", - "vpcConfig": { - "securityGroupIds": [ - "security-group-id" - ], - "subnets": [ - "subnet-id" - ], - "vpcId": "vpc-id" - }, - "fileSystemLocations": [ - { - "type": "EFS", - "location": "EFS-DNS-name-1:/directory-path", - "mountPoint": "mount-point", - "identifier": "efs-identifier", - "mountOptions": "efs-mount-options" - }, - { - "type": "EFS", - "location": "EFS-DNS-name-2:/directory-path", - "mountPoint": "mount-point", - "identifier": "efs-identifier", - "mountOptions": "efs-mount-options" - } - ], - "timeoutInMinutes": timeoutInMinutes, - "encryptionKey": "encryptionKey", - "tags": [ - { - "key": "tag-key", - "value": "tag-value" - } - ], - "environment": { - "type": "environment-type", - "image": "image", - "computeType": "computeType", - "certificate": "certificate", - "environmentVariables": [ - { - "name": "environmentVariable-name", - "value": "environmentVariable-value", - "type": "environmentVariable-type" - } - ], - "registryCredential": [ - { - "credential": "credential-arn-or-name", - "credentialProvider": "credential-provider" - } - ], - "imagePullCredentialsType": "imagePullCredentialsType-value, - "privilegedMode": "privilegedMode" - }, - "badgeEnabled": "badgeEnabled" - } - ``` - - Replace the following: - + *project\-name*: Required\. The name for this build project\. This name must be unique across all of the build projects in your AWS account\. - + *description*: Optional\. The description for this build project\. - + For the required `source` object, information about this build project's source code settings\. After you add a `source` object, you can add up to 12 more sources using the [CodeBuild secondarySources object](#cli-secondary-sources)\. These settings include the following: - + *source\-type*: Required\. The type of repository that contains the source code to build\. Valid values include `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `GITHUB_ENTERPRISE`, `BITBUCKET`, `S3`, and `NO_SOURCE`\. If you use `NO_SOURCE`, the buildspec cannot be a file because the project does not have a source\. Instead, you must use the `buildspec` attribute to specify a YAML\-formatted string for your buildspec\. For more information, see [Project without a source sample](sample-multi-in-out.md#no-source)\. - + *source\-location*: Required unless you set *source\-type* to `CODEPIPELINE`\. The location of the source code for the specified repository type\. - + For CodeCommit, the HTTPS clone URL to the repository that contains the source code and the buildspec file \(for example, `https://git-codecommit.region-id.amazonaws.com/v1/repos/repo-name`\)\. - + For Amazon S3, the build input bucket name, followed by a forward slash \(`/`\), followed by the name of the ZIP file that contains the source code and the buildspec \(for example, `bucket-name/object-name.zip`\)\. This assumes that the ZIP file is in the root of the build input bucket\. \(If the ZIP file is in a folder inside of the bucket, use `bucket-name/path/to/object-name.zip` instead\.\) - + For GitHub, the HTTPS clone URL to the repository that contains the source code and the buildspec file\. The URL must contain github\.com\. You must connect your AWS account to your GitHub account\. To do this, use the CodeBuild console to create a build project\. - - 1. When you use the console to connect \(or reconnect\) with GitHub, on the GitHub **Authorize application** page, for **Organization access**, choose **Request access** next to each repository you want CodeBuild to be able to access\. - - 1. Choose **Authorize application**\. \(After you have connected to your GitHub account, you do not need to finish creating the build project\. You can close the CodeBuild console\.\) - + For GitHub Enterprise Server, the HTTP or HTTPS clone URL to the repository that contains the source code and the buildspec file\. You must also connect your AWS account to your GitHub Enterprise Server account\. To do this, use the CodeBuild console to create a build project\. - - 1. Create a personal access token in GitHub Enterprise Server\. - - 1. Copy this token to your clipboard so you can use it when you create your CodeBuild project\. For more information, see [Creating a personal access token for the command line](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) on the GitHub Help website\. - - 1. When you use the console to create your CodeBuild project, in **Source**, for **Source provider**, choose **GitHub Enterprise**\. - - 1. For **Personal Access Token**, paste the token that was copied to your clipboard\. Choose **Save Token**\. Your CodeBuild account is now connected to your GitHub Enterprise Server account\. - + For Bitbucket, the HTTPS clone URL to the repository that contains the source code and the buildspec file\. The URL must contain bitbucket\.org\. You must also connect your AWS account to your Bitbucket account\. To do this, use the CodeBuild console to create a build project\. - - 1. When you use the console to connect \(or reconnect\) with Bitbucket, on the Bitbucket **Confirm access to your account** page, choose **Grant access**\. \(After you have connected to your Bitbucket account, you do not need to finish creating the build project\. You can close the CodeBuild console\.\) - + For AWS CodePipeline, do not specify a `location` value for `source`\. CodePipeline ignores this value because when you create a pipeline in CodePipeline, you specify the source code location in the Source stage of the pipeline\. - + *gitCloneDepth*: Optional\. The depth of history to download\. Minimum value is 0\. If this value is 0, greater than 25, or not provided, then the full history is downloaded with each build project\. If your source type is Amazon S3, this value is not supported\. - + *buildspec*: Optional\. The build specification definition or file to use\. If this value is set, it can be either an inline buildspec definition, the path to an alternate buildspec file relative to the value of the built\-in `CODEBUILD_SRC_DIR` environment variable, or the path to an S3 bucket\. The bucket must be in the same AWS Region as the build project\. Specify the buildspec file using its ARN \(for example, `arn:aws:s3:::my-codebuild-sample2/buildspec.yml`\)\. If this value is not provided or is set to an empty string, the source code must contain a `buildspec.yml` file in its root directory\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. - + *auth*: This object is used by the CodeBuild console only\. Do not specify values for *auth\-type* \(unless *source\-type* is set to `GITHUB`\) or *resource*\. - + *reportBuildStatus*: Optional\. Specifies whether to send your source provider the status of a build's start and completion\. If you set this with a source provider other than GitHub, GitHub Enterprise Server, or Bitbucket, an `invalidInputException` is thrown\. - + *buildStatusConfig*: Optional\. Contains information that defines how the CodeBuild build project reports the build status to the source provider\. This option is only used when the source type is `GITHUB`, `GITHUB_ENTERPRISE`, or `BITBUCKET`\. - + *context*: For Bitbucket sources, this parameter is used for the `name` parameter in the Bitbucket commit status\. For GitHub sources, this parameter is used for the `context` parameter in the GitHub commit status\. - - For example, you can have the `context` contain the build number and the webhook trigger using the CodeBuild environment variables: - - ``` - AWS CodeBuild sample-project Build #$CODEBUILD_BUILD_NUMBER - $CODEBUILD_WEBHOOK_TRIGGER - ``` - - This results in the context appearing like this for build \#24 triggered by a webhook pull request event: - - ``` - AWS CodeBuild sample-project Build #24 - pr/8 - ``` - + *target\-url*: For Bitbucket sources, this parameter is used for the `url` parameter in the Bitbucket commit status\. For GitHub sources, this parameter is used for the `target_url` parameter in the GitHub commit status\. - - For example, you can set the `targetUrl` to `https://aws.amazon.com/codebuild/` and the commit status will link to this URL\. - + *gitSubmodulesConfig*: Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise Server, and Bitbucket only\. Set `fetchSubmodules` to `true` if you want to include the Git submodules in your repository\. Git submodules that are included must be configured as HTTPS\. - + *InsecureSsl*: Optional\. Used with GitHub Enterprise Server only\. Set this value to `true` to ignore TLS warnings while connecting to your GitHub Enterprise Server project repository\. The default value is `false`\. *InsecureSsl* should be used for testing purposes only\. It should not be used in a production environment\. - + *source\-version*: Optional\. A version of the build input to be built for this project\. If not specified, the latest version is used\. If specified, it must be one of: - + For CodeCommit, the commit ID to use\. - + For GitHub, the commit ID, pull request ID, branch name, or tag name that corresponds to the version of the source code you want to build\. If a pull request ID is specified, it must use the format `pr/pull-request-ID` \(for example `pr/25`\)\. If a branch name is specified, the branch's HEAD commit ID is used\. If not specified, the default branch's HEAD commit ID is used\. - + For Bitbucket, the commit ID, branch name, or tag name that corresponds to the version of the source code you want to build\. If a branch name is specified, the branch's HEAD commit ID is used\. If not specified, the default branch's HEAD commit ID is used\. - + For Amazon S3, the version ID of the object that represents the build input ZIP file to use\. - - If `sourceVersion` is specified at the build level, then that version takes precedence over this `sourceVersion` \(at the project level\)\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md)\. - + *secondarySourceVersions*: Optional\. An array of `projectSourceVersion` objects\. If `secondarySourceVersions` is specified at the build level, then they take precedence over this\. - + *secondary\-source\-identifier*: An identifier for a source in the build project\. - + *secondary\-source\-version*: A `sourceVersion` object\. - + For the required `artifacts` object, information about this build project's output artifact settings\. After you add an `artifacts` object, you can add up to 12 more artifacts using the [CodeBuild secondaryArtifacts object](#cli-secondary-artifacts)\. These settings include the following: - + *artifacts\-type*: Required\. The type of build output artifact\. Valid values include `CODEPIPELINE`, `NO_ARTIFACTS`, and `S3`\. - + *artifacts\-location*: Required unless you set *artifacts\-type* to `CODEPIPELINE` or `NO_ARTIFACTS`\. The location of the build output artifact: - + If you specified `CODEPIPELINE` for *artifacts\-type*, do not specify a `location` for `artifacts`\. - + If you specified `NO_ARTIFACTS` for *artifacts\-type*, do not specify a `location` for `artifacts`\. - + If you specified `S3` for *artifacts\-type*, this is the name of the output bucket you created or identified in the prerequisites\. - + *path*: Optional\. The path and name of the build output ZIP file or folder: - + If you specified `CODEPIPELINE` for *artifacts\-type*, do not specify a `path` for `artifacts`\. - + If you specified `NO_ARTIFACTS` for *artifacts\-type*, do not specify a `path` for `artifacts`\. - + If you specified `NO_ARTIFACTS` for *artifacts\-type*, do not specify a `path` for `artifacts`\. - + If you specified `S3` for *artifacts\-type*, this is the path inside of *artifacts\-location* to the build output ZIP file or folder\. If you do not specify a value for *path*, CodeBuild uses *namespaceType* \(if specified\) and *artifacts\-name* to determine the path and name of the build output ZIP file or folder\. For example, if you specify `MyPath` for *path* and `MyArtifact.zip` for *artifacts\-name*, the path and name would be `MyPath/MyArtifact.zip`\. - + *namespaceType*: Optional\. The path and name of the build output ZIP file or folder: - + If you specified `CODEPIPELINE` for *artifacts\-type*, do not specify a `namespaceType` for `artifacts`\. - + If you specified `NO_ARTIFACTS` for *artifacts\-type*, do not specify a `namespaceType` for `artifacts`\. - + If you specified `S3` for *artifacts\-type*, valid values include `BUILD_ID` and `NONE`\. Use `BUILD_ID` to insert the build ID into the path of the build output ZIP file or folder\. Otherwise, use `NONE`\. If you do not specify a value for *namespaceType*, CodeBuild uses *path* \(if specified\) and *artifacts\-name* to determine the path and name of the build output ZIP file or folder\. For example, if you specify `MyPath` for *path*, `BUILD_ID` for *namespaceType*, and `MyArtifact.zip` for *artifacts\-name*, the path and name would be `MyPath/build-ID/MyArtifact.zip`\. - + *artifacts\-name*: Required unless you set *artifacts\-type* to `CODEPIPELINE` or `NO_ARTIFACTS`\. The path and name of the build output ZIP file or folder: - + If you specified `CODEPIPELINE` for *artifacts\-type*, do not specify a `name` for `artifacts`\. - + If you specified `NO_ARTIFACTS` for *artifacts\-type*, do not specify a `name` for `artifacts`\. - + If you specified `S3` for *artifacts\-type*, this is the name of the build output ZIP file or folder inside of *artifacts\-location*\. For example, if you specify `MyPath` for *path* and `MyArtifact.zip` for *artifacts\-name*, the path and name would be `MyPath/MyArtifact.zip`\. - + *override\-artifact\-name*: Optional boolean\. If set to `true`, the name specified in the `artifacts` block of the buildspec file overrides *artifacts\-name*\. For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. - + *packaging*: Optional\. The type of build output artifact to create: - + If you specified `CODEPIPELINE` for *artifacts\-type*, do not specify a `packaging` for `artifacts`\. - + If you specified `NO_ARTIFACTS` for *artifacts\-type*, do not specify a `packaging` for `artifacts`\. - + If you specified `S3` for *artifacts\-type*, valid values include `ZIP` and `NONE`\. To create a ZIP file that contains the build output, use `ZIP`\. To create a folder that contains the build output, use `NONE`\. The default value is `NONE`\. - + For the required `cache` object, information about this build project's cache settings\. For information, see [Build caching](build-caching.md)\. These settings include the following\. - + *cache\-type*: Required\. Valid values are `S3`, `NO_CACHE`, or `LOCAL_CACHE`\. - + *cache\-location*: Required only if you set *CacheType* to `S3`\. If you specified Amazon S3 for *CacheType*, this is the ARN of the S3 bucket and the path prefix\. For example, if your S3 bucket name is `my-bucket`, and your path prefix is `build-cache`, then acceptable formats for your *CacheLocation* are `my-bucket/build-cache` or `arn:aws:s3:::my-bucket/build-cache`\. - + *cache\-mode*: Required if you set *CacheType* to `LOCAL`\. You can specify one or more of the following local cache modes: `LOCAL_SOURCE_CACHE`, `LOCAL_DOCKER_LAYER_CACHE`, `LOCAL_CUSTOM_CACHE`\. -**Note** -Docker layer cache mode is available for Linux only\. If you choose it, your project must run in privileged mode\. The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_GENERAL1_2XLARGE` compute type do not support the use of a local cache\. - + For the `logsConfig` object, information about where this build's logs are located: - + *cloudwatch\-logs\-status*: Required\. Valid values are `ENABLED` or `DISABLED`\. If its value is `ENABLED`, the following values are required\. For more information, see [Working with log groups and log streams](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html) in the *Amazon CloudWatch Logs User Guide*\. - + *group\-name*: The name of the CloudWatch Logs group\. - + *stream\-name*: The name of the CloudWatch Logs stream\. - + *s3\-logs\-status*: Required\. Valid values are `ENABLED` or `DISABLED`\. - + *s3\-logs\-location*: Required if *s3\-logs\-status* is `ENABLED`\. This is the ARN of an S3 bucket and the path prefix\. For example, if your S3 bucket name is `my-bucket`, and your path prefix is `build-log`, then acceptable formats for your *s3\-logs\-location* are `my-bucket/build-log` or `arn:aws:s3:::my-bucket/build-log`\. - + *s3\-logs\-encryptionDisabled*: Optional boolean\. If set to `true`, your S3 build log output is not encrypted\. By default, S3 build logs are encrypted\. - + For the optional `secondaryArtifacts` object, information about the settings of a secondary artifact for a build project\. You can add up to 12 secondary artifacts\. The `secondaryArtifacts` uses many of the same settings used by the [CodeBuild artifacts object](#cli-artifacts) object\. The settings are: - + *artifacts\-type*: Required\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's type property](#cli-artifacts-type)\. - + *artifacts\-location*: Required\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's location property](#cli-artifacts-location)\. - + *path*: Optional\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's path property](#cli-artifacts-path)\. - + *namespaceType*: Optional\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's namespaceType property](#cli-artifacts-namespacetype)\. - + *artifacts\-name*: Required\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's name property](#cli-artifacts-name)\. - + *packaging*: Optional\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's packaging property](#cli-artifacts-packaging)\. - + *artifact\-identifier*: Required\. A unique string identifier for a secondary artifact\. - + For the optional `secondarySources` object, information about the settings of a secondary source for a build project\. You can add up to 12 `secondarySources`\. The `secondarySources` object uses many of the same settings used by the [CodeBuild source object](#cli-sources)\. They include the following: - + *source\-type*: Required\. This setting is also used by the `sources` object\. See [CodeBuild source object's type property](#cli-sources-type)\. - + *source\-location*: Required\. This setting is also used by the `sources` object\. See [CodeBuild source object's location property](#cli-sources-location)\. - + *gitCloneDepth*: Optional\. This setting is also used by the `sources` object\. See [CodeBuild source object's location property](#cli-sources-location)\. - + *buildspec*: Optional\. This setting is also used by the `sources` object\. See [CodeBuild source object's buildspec property](#cli-sources-buildspec)\. - + *auth*: This setting is also used by the `sources` object\. See [CodeBuild source object's auth property](#cli-sources-auth)\. - + *reportBuildStatus*: Optional\. This setting is also used by the `sources` object\. See [CodeBuild source object's reportBuildStatus property](#cli-sources-reportbuildstatus)\. - + *InsecureSsl*: Optional\. This setting is also used by the `sources` object\. See [CodeBuild source object's insecureSsl property](#cli-sources-insecuressl)\. - + *source\-identifier*: Required\. A unique string identifier for a secondary source\. - + *serviceRole*: Required\. The ARN of the service role CodeBuild uses to interact with services on behalf of the IAM user \(for example, `arn:aws:iam::account-id:role/role-name`\)\. - + For the optional *vpcConfig* object, information about your VPC configuration\. These settings include: - + *vpcId*: Required\. The VPC ID that CodeBuild uses\. Run this command to get a list of all VPC IDs in your Region: - - ``` - aws ec2 describe-vpcs - ``` - + *subnets*: Required\. The subnet IDs that include resources used by CodeBuild\. Run this command to get these IDs: - - ``` - aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region us-east-1 - ``` - - If you are using a Region other than `us-east-1`, be sure to use it when you run the command\. - + *securityGroupIds*: Required\. The security group IDs used by CodeBuild to allow access to resources in the VPCs\. Run this command to get these IDs: - - ``` - aws ec2 describe-security-groups --filters "Name=vpc-id,Values=" --region us-east-1 - ``` - - If you are using a Region other than `us-east-1`, be sure to use it when you run the command\. - + For the optional *fileSystemLocations* object, information about your Amazon EFS configuration\. These settings include: - + `type`: Required\. This value must be `EFS`\. - + *location*: Required\. The location specified in the format *EFS\-DNS\-name*:/*directory\-path*\. - + *mountPoint*: Required\. The absolute path to the directory in your build container where the file system is mounted\. If this directory does not exist, CodeBuild creates it during the build\. - + *identifier*: Required\. A unique file system identifier\. CodeBuild uses this to create an environment variable that identifies the file system\. The environment variable format is `CODEBUILD_file-system-identifier` in capital letters\. For example, if you enter **efs\-1**, the resulting environment variable is `CODEBUILD_EFS-1`\. - + *mountOptions*: Optional\. If you leave this blank, CodeBuild uses its default mount options \(`nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2`\)\. For more information, see [Recommended NFS mount options](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs-nfs-mount-settings.html) in the *Amazon Elastic File System User Guide*\. - + For the required `environment` object, information about this project's build environment settings\. These settings include: - + *environment\-type*: Required\. The type of build environment\. Valid values are: - + `ARM_CONTAINER` - + `LINUX_CONTAINER` - + `LINUX_GPU_CONTAINER` - + `WINDOWS_CONTAINER` - + `WINDOWS_SERVER_2019_CONTAINER` - + *image*: Required\. The Docker image identifier used by this build environment\. Typically, this identifier is expressed as *image\-name*:*tag*\. For example, in the Docker repository that CodeBuild uses to manage its Docker images, this could be `aws/codebuild/standard:4.0`\. In Docker Hub, `maven:3.3.9-jdk-8`\. In Amazon ECR, `account-id.dkr.ecr.region-id.amazonaws.com/your-Amazon-ECR-repo-name:tag`\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - + *computeType*: Required\. A category that corresponds to the number of CPU cores and memory used by this build environment\. Allowed values include: - + `BUILD_GENERAL1_SMALL` - + `BUILD_GENERAL1_MEDIUM` - + `BUILD_GENERAL1_LARGE` - + `BUILD_GENERAL1_2XLARGE` - - `BUILD_GENERAL1_2XLARGE` is only supported with the `LINUX_CONTAINER` environment type\. - + *certificate*: Optional\. The ARN of the S3 bucket, path prefix and object key that contains the PEM\-encoded certificate\. The object key can be either just the \.pem file or a \.zip file containing the PEM\-encoded certificate\. For example, if your S3 bucket name is `my-bucket`, your path prefix is `cert`, and your object key name is `certificate.pem`, then acceptable formats for your *certificate* are `my-bucket/cert/certificate.pem` or `arn:aws:s3:::my-bucket/cert/certificate.pem`\. - + For the optional `environmentVariables` array, information about any environment variables you want to specify for this build environment\. Each environment variable is expressed as an object that contains a `name`, `value`, and `type` of *environmentVariable\-name*, *environmentVariable\-value*, and *environmentVariable\-type*\. - - Console and AWS CLI users can see an environment variable\. If you have no concerns about the visibility of your environment variable, set *environmentVariable\-name* and *environmentVariable\-value*, and then set *environmentVariable\-type* to `PLAINTEXT`\. - - We recommend you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager\. For *environmentVariable\-name*, for that stored parameter, set an identifier for CodeBuild to reference\. - - If you use Amazon EC2 Systems Manager Parameter Store, for *environmentVariable\-value*, set the parameter's name as stored in the Parameter Store\. Set *environmentVariable\-type* to `PARAMETER_STORE`\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, set *environmentVariable\-name* to `LOGIN_PASSWORD`\. Set *environmentVariable\-value* to `/CodeBuild/dockerLoginPassword`\. Set *environmentVariable\-type* to `PARAMETER_STORE`\. -**Important** +For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md)\. + +To create a CodeBuild build project using the AWS CLI, you create a JSON\-formatted [Project](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Project.html) structure, fill in the structure, and call the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html) command to create the project\. + +## Create the JSON file + +Create a skeleton JSON file with the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html) command, using the `--generate-cli-skeleton` option: + +``` +aws codebuild create-project --generate-cli-skeleton > +``` + +This creates a JSON file with the path and file name specified by **\. + +## Fill in the JSON file + +Modify the JSON data as follows and save your results\. + +``` +{ + "name": "", + "description": "", + "source": { + "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "BITBUCKET" | "S3" | "NO_SOURCE", + "location": "", + "gitCloneDepth": "", + "buildspec": "", + "InsecureSsl": "", + "reportBuildStatus": "", + "buildStatusConfig": { + "context": "", + "targetUrl": "" + }, + "gitSubmodulesConfig": { + "fetchSubmodules": "" + }, + "auth": { + "type": "", + "resource": "" + }, + "sourceIdentifier": "" + }, + "secondarySources": [ + { + "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "BITBUCKET" | "S3" | "NO_SOURCE", + "location": "", + "gitCloneDepth": "", + "buildspec": "", + "InsecureSsl": "", + "reportBuildStatus": "", + "auth": { + "type": "", + "resource": "" + }, + "sourceIdentifier": "" + } + ], + "secondarySourceVersions": [ + { + "sourceIdentifier": "", + "sourceVersion": "" + } + ], + "sourceVersion": "", + "artifacts": { + "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS", + "location": "", + "path": "", + "namespaceType": "", + "name": "", + "overrideArtifactName": "", + "packaging": "" + }, + "secondaryArtifacts": [ + { + "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS", + "location": "", + "path": "", + "namespaceType": "", + "name": "", + "packaging": "", + "artifactIdentifier": "" + } + ], + "cache": { + "type": "", + "location": "", + "mode": [ + "" + ] + }, + "environment": { + "type": "LINUX_CONTAINER" | "LINUX_GPU_CONTAINER" | "ARM_CONTAINER" | "WINDOWS_SERVER_2019_CONTAINER", + "image": "", + "computeType": "BUILD_GENERAL1_SMALL" | "BUILD_GENERAL1_MEDIUM" | "BUILD_GENERAL1_LARGE" | "BUILD_GENERAL1_2XLARGE", + "certificate": "", + "environmentVariables": [ + { + "name": "", + "value": "", + "type": "" + } + ], + "registryCredential": [ + { + "credential": "", + "credentialProvider": "" + } + ], + "imagePullCredentialsType": "CODEBUILD" | "SERVICE_ROLE", + "privilegedMode": "" + }, + "serviceRole": "", + "timeoutInMinutes": , + "queuedTimeoutInMinutes": , + "encryptionKey": "", + "tags": [ + { + "key": "", + "value": "" + } + ], + "vpcConfig": { + "securityGroupIds": [ + "" + ], + "subnets": [ + "" + ], + "vpcId": "" + }, + "badgeEnabled": "", + "logsConfig": { + "cloudWatchLogs": { + "status": "", + "groupName": "", + "streamName": "" + }, + "s3Logs": { + "status": "", + "location": "", + "encryptionDisabled": "" + } + }, + "fileSystemLocations": [ + { + "type": "EFS", + "location": ":/", + "mountPoint": "", + "identifier": "", + "mountOptions": "" + } + ], + "buildBatchConfig": { + "serviceRole": "", + "combineArtifacts": , + "restrictions": { + "maximumBuildsAllowed": , + "computeTypesAllowed": [ + "" + ] + }, + "timeoutInMins": , + "batchReportMode": "REPORT_AGGREGATED_BATCH" | "REPORT_INDIVIDUAL_BUILDS" + }, + "concurrentBuildLimit": +} +``` + +Replace the following: + +### **name** + +Required\. The name for this build project\. This name must be unique across all of the build projects in your AWS account\. + +### **description** + +Optional\. The description for this build project\. + +### **source** + +Required\. A [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html) object that contains information about this build project's source code settings\. After you add a `source` object, you can add up to 12 more sources using the [**secondarySources**](#cli.secondarysources)\. These settings include the following: + +source/**type** +Required\. The type of repository that contains the source code to build\. Valid values include: ++ `CODECOMMIT` ++ `CODEPIPELINE` ++ `GITHUB` ++ `GITHUB_ENTERPRISE` ++ `BITBUCKET` ++ `S3` ++ `NO_SOURCE` +If you use `NO_SOURCE`, the buildspec cannot be a file because the project does not have a source\. Instead, you must use the `buildspec` attribute to specify a YAML\-formatted string for your buildspec\. For more information, see [Project without a source sample](sample-multi-in-out.md#no-source)\. + +source/**location** +Required unless you set ** to `CODEPIPELINE`\. The location of the source code for the specified repository type\. ++ For CodeCommit, the HTTPS clone URL to the repository that contains the source code and the buildspec file \(for example, `https://git-codecommit..amazonaws.com/v1/repos/`\)\. ++ For Amazon S3, the build input bucket name, followed by the path and name of the ZIP file that contains the source code and the buildspec\. For example: + + For a ZIP file located at the root of the input bucket: `/.zip`\. + + For a ZIP file located in a subfolder in the input bucket: `//.zip`\. ++ For GitHub, the HTTPS clone URL to the repository that contains the source code and the buildspec file\. The URL must contain github\.com\. You must connect your AWS account to your GitHub account\. To do this, use the CodeBuild console to create a build project\. + + 1. On the GitHub **Authorize application** page, in the **Organization access** section, choose **Request access** next to each repository you want CodeBuild to be able to access in the \. + + 1. Choose **Authorize application**\. \(After you have connected to your GitHub account, you do not need to finish creating the build project\. You can close the CodeBuild console\.\) ++ For GitHub Enterprise Server, the HTTP or HTTPS clone URL to the repository that contains the source code and the buildspec file\. You must also connect your AWS account to your GitHub Enterprise Server account\. To do this, use the CodeBuild console to create a build project\. + + 1. Create a personal access token in GitHub Enterprise Server\. + + 1. Copy this token to your clipboard so you can use it when you create your CodeBuild project\. For more information, see [Creating a personal access token for the command line](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) on the GitHub Help website\. + + 1. When you use the console to create your CodeBuild project, in **Source**, for **Source provider**, choose **GitHub Enterprise**\. + + 1. For **Personal Access Token**, paste the token that was copied to your clipboard\. Choose **Save Token**\. Your CodeBuild account is now connected to your GitHub Enterprise Server account\. ++ For Bitbucket, the HTTPS clone URL to the repository that contains the source code and the buildspec file\. The URL must contain bitbucket\.org\. You must also connect your AWS account to your Bitbucket account\. To do this, use the CodeBuild console to create a build project\. + + 1. When you use the console to connect \(or reconnect\) with Bitbucket, on the Bitbucket **Confirm access to your account** page, choose **Grant access**\. \(After you have connected to your Bitbucket account, you do not need to finish creating the build project\. You can close the CodeBuild console\.\) ++ For AWS CodePipeline, do not specify a `location` value for `source`\. CodePipeline ignores this value because when you create a pipeline in CodePipeline, you specify the source code location in the Source stage of the pipeline\. + +source/**gitCloneDepth** +Optional\. The depth of history to download\. Minimum value is 0\. If this value is 0, greater than 25, or not provided, then the full history is downloaded with each build project\. If your source type is Amazon S3, this value is not supported\. + +source/**buildspec** +Optional\. The build specification definition or file to use\. If this value is not provided or is set to an empty string, the source code must contain a `buildspec.yml` file in its root directory\. If this value is set, it can be either an inline buildspec definition, the path to an alternate buildspec file relative to the root directory of your primary source, or the path to an S3 bucket\. The bucket must be in the same AWS Region as the build project\. Specify the buildspec file using its ARN \(for example, `arn:aws:s3:::my-codebuild-sample2/buildspec.yml`\)\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. + +source/**auth** +Do not use\. This object is used by the CodeBuild console only\. + +source/**reportBuildStatus** +Specifies whether to send your source provider the status of a build's start and completion\. If you set this with a source provider other than GitHub, GitHub Enterprise Server, or Bitbucket, an `invalidInputException` is thrown\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. + +source/**buildStatusConfig** +Contains information that defines how the CodeBuild build project reports the build status to the source provider\. This option is only used when the source type is `GITHUB`, `GITHUB_ENTERPRISE`, or `BITBUCKET`\. +source/buildStatusConfig/**context** +For Bitbucket sources, this parameter is used for the `name` parameter in the Bitbucket commit status\. For GitHub sources, this parameter is used for the `context` parameter in the GitHub commit status\. +For example, you can have the `context` contain the build number and the webhook trigger using the CodeBuild environment variables: + +``` +AWS CodeBuild sample-project Build #$CODEBUILD_BUILD_NUMBER - $CODEBUILD_WEBHOOK_TRIGGER +``` +This results in the context appearing like this for build \#24 triggered by a webhook pull request event: + +``` +AWS CodeBuild sample-project Build #24 - pr/8 +``` +source/buildStatusConfig/**targetUrl** +For Bitbucket sources, this parameter is used for the `url` parameter in the Bitbucket commit status\. For GitHub sources, this parameter is used for the `target_url` parameter in the GitHub commit status\. +For example, you can set the `targetUrl` to `https://aws.amazon.com/codebuild/` and the commit status will link to this URL\. +You can also include CodeBuild environment variables in the `targetUrl` to add additional information to the URL\. For example, to add the build region to the URL, set the `targetUrl` to: + +``` +"targetUrl": "https://aws.amazon.com/codebuild/?region=$AWS_REGION" +``` +If the build region is `us-east-2`, this will expand to: + +``` +https://aws.amazon.com/codebuild/?region=us-east-2 +``` + +source/**gitSubmodulesConfig** +Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise Server, and Bitbucket only\. +source/gitSubmodulesConfig/**fetchSubmodules** +Set `fetchSubmodules` to `true` if you want to include the Git submodules in your repository\. Git submodules that are included must be configured as HTTPS\. + +source/**InsecureSsl** +Optional\. Used with GitHub Enterprise Server only\. Set this value to `true` to ignore TLS warnings while connecting to your GitHub Enterprise Server project repository\. The default value is `false`\. `InsecureSsl` should be used for testing purposes only\. It should not be used in a production environment\. + +source/**sourceIdentifier** +A user\-defined identifier for the project source\. Optional for the primary source\. Required for secondary sources\. + +### **secondarySources** + +Optional\. An array of [ProjectSource](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html) objects that contain information about the secondary sources for a build project\. You can add up to 12 secondary sources\. The `secondarySources` objects use the same properties used by the [**source**](#cli.source) object\. In a secondary source object, the `sourceIdentifier` is required\. + +### **secondarySourceVersions** + +Optional\. An array of [ProjectSourceVersion](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSourceVersion.html) objects\. If `secondarySourceVersions` is specified at the build level, then they take precedence over this\. + +### **sourceVersion** + +Optional\. The version of the build input to be built for this project\. If not specified, the latest version is used\. If specified, it must be one of: ++ For CodeCommit, the commit ID, branch, or Git tag to use\. ++ For GitHub, the commit ID, pull request ID, branch name, or tag name that corresponds to the version of the source code you want to build\. If a pull request ID is specified, it must use the format `pr/pull-request-ID` \(for example `pr/25`\)\. If a branch name is specified, the branch's HEAD commit ID is used\. If not specified, the default branch's HEAD commit ID is used\. ++ For Bitbucket, the commit ID, branch name, or tag name that corresponds to the version of the source code you want to build\. If a branch name is specified, the branch's HEAD commit ID is used\. If not specified, the default branch's HEAD commit ID is used\. ++ For Amazon S3, the version ID of the object that represents the build input ZIP file to use\. + +If `sourceVersion` is specified at the build level, then that version takes precedence over this `sourceVersion` \(at the project level\)\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md)\. + +### **artifacts** + +Required\. A [ProjectArtifacts](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectArtifacts.html) object that contains information about this build project's output artifact settings\. After you add an `artifacts` object, you can add up to 12 more artifacts using the [secondaryArtifacts](#cli.secondaryartifacts)\. These settings include the following: + +artifacts/**type** +Required\. The type of build output artifact\. Valid values are: ++ `CODEPIPELINE` ++ `NO_ARTIFACTS` ++ `S3` + +artifacts/**location** +Only used with the `S3` artifact type\. Not used for other artifact types\. +The name of the output bucket you created or identified in the prerequisites\. + +artifacts/**path** +Only used with the `S3` artifact type\. Not used for other artifact types\. +The path in of the output bucket to place ZIP file or folder\. If you do not specify a value for `path`, CodeBuild uses `namespaceType` \(if specified\) and `name` to determine the path and name of the build output ZIP file or folder\. For example, if you specify `MyPath` for `path` and `MyArtifact.zip` for `name`, the path and name would be `MyPath/MyArtifact.zip`\. + +artifacts/**namespaceType** +Only used with the `S3` artifact type\. Not used for other artifact types\. +The namespace of the build output ZIP file or folder\. Valid values include `BUILD_ID` and `NONE`\. Use `BUILD_ID` to insert the build ID into the path of the build output ZIP file or folder\. Otherwise, use `NONE`\. If you do not specify a value for `namespaceType`, CodeBuild uses `path` \(if specified\) and `name` to determine the path and name of the build output ZIP file or folder\. For example, if you specify `MyPath` for `path`, `BUILD_ID` for `namespaceType`, and `MyArtifact.zip` for `name`, the path and name would be `MyPath/build-ID/MyArtifact.zip`\. + +artifacts/**name** +Only used with the `S3` artifact type\. Not used for other artifact types\. +The name of the build output ZIP file or folder inside of `location`\. For example, if you specify `MyPath` for `path` and `MyArtifact.zip` for `name`, the path and name would be `MyPath/MyArtifact.zip`\. + +artifacts/**overrideArtifactName** +Only used with the S3 artifact type\. Not used for other artifact types\. +Optional\. If set to `true`, the name specified in the `artifacts` block of the buildspec file overrides `name`\. For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. + +artifacts/**packaging** +Only used with the `S3` artifact type\. Not used for other artifact types\. +Optional\. Specifies how to package the artifacts\. Allowed values are: +NONE +Create a folder that contains the build artifacts\. This is the default value\. +ZIP +Create a ZIP file that contains the build artifacts\. + +### secondaryArtifacts + +Optional\. An array of [ProjectArtifacts](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectArtifacts.html) objects that contain information about the secondary artifacts settings for a build project\. You can add up to 12 secondary artifacts\. The `secondaryArtifacts` uses many of the same settings used by the [**artifacts**](#cli.artifacts) object\. + +### cache + +Required\. A [ProjectCache](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectCache.html) object that contains information about this build project's cache settings\. For more information, see [Build caching](build-caching.md)\. + +### environment + +Required\. A [ProjectEnvironment](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html) object that contains information about this project's build environment settings\. These settings include: + +environment/**type** +Required\. The type of build environment\. For more information, see [type](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html#CodeBuild-Type-ProjectEnvironment-type) in the *CodeBuild API Reference*\. + +environment/**image** +Required\. The Docker image identifier used by this build environment\. Typically, this identifier is expressed as *image\-name*:*tag*\. For example, in the Docker repository that CodeBuild uses to manage its Docker images, this could be `aws/codebuild/standard:4.0`\. In Docker Hub, `maven:3.3.9-jdk-8`\. In Amazon ECR, `account-id.dkr.ecr.region-id.amazonaws.com/your-Amazon-ECR-repo-name:tag`\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. + +environment/**computeType** +Required\. Specifies the compute resources used by this build environment\. For more information, see [computeType](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectEnvironment.html#CodeBuild-Type-ProjectEnvironment-computeType) in the *CodeBuild API Reference*\. + +environment/**certificate** +Optional\. The ARN of the Amazon S3 bucket, path prefix, and object key that contains the PEM\-encoded certificate\. The object key can be either just the \.pem file or a \.zip file containing the PEM\-encoded certificate\. For example, if your Amazon S3 bucket name is `my-bucket`, your path prefix is `cert`, and your object key name is `certificate.pem`, then acceptable formats for `certificate` are `my-bucket/cert/certificate.pem` or `arn:aws:s3:::my-bucket/cert/certificate.pem`\. + +environment/**environmentVariables** +Optional\. An array of [EnvironmentVariable](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_EnvironmentVariable.html) objects that contains the environment variables you want to specify for this build environment\. Each environment variable is expressed as an object that contains a `name`, `value`, and `type` of `name`, `value`, and `type`\. +Console and AWS CLI users can see all environment variables\. If you have no concerns about the visibility of your environment variable, set `name` and `value`, and set `type` to `PLAINTEXT`\. +We recommend you store environment variables with sensitive values, such as an AWS access key ID, an AWS secret access key, or a password, as a parameter in Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager\. For `name`, for that stored parameter, set an identifier for CodeBuild to reference\. +If you use Amazon EC2 Systems Manager Parameter Store, for `value`, set the parameter's name as stored in the Parameter Store\. Set `type` to `PARAMETER_STORE`\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, set `name` to `LOGIN_PASSWORD`\. Set `value` to `/CodeBuild/dockerLoginPassword`\. Set `type` to `PARAMETER_STORE`\. If you use Amazon EC2 Systems Manager Parameter Store, we recommend that you store parameters with parameter names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager\. Choose **Create parameter**, and then follow the instructions in the dialog box\. \(In that dialog box, for **KMS key**, you can specify the ARN of an AWS KMS key in your account\. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt it during retrieval\.\) If you use the CodeBuild console to create a parameter, the console starts the parameter name with `/CodeBuild/` as it is being stored\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store Console Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the `ssm:GetParameters` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update that service role to allow access to parameter names that do not start with `/CodeBuild/`\. This is because that service role allows access only to parameter names that start with `/CodeBuild/`\. @@ -323,105 +363,150 @@ If you choose **New service role**, the service role includes permission to decr Environment variables you set replace existing environment variables\. For example, if the Docker image already contains an environment variable named `MY_VAR` with a value of `my_value`, and you set an environment variable named `MY_VAR` with a value of `other_value`, then `my_value` is replaced by `other_value`\. Similarly, if the Docker image already contains an environment variable named `PATH` with a value of `/usr/local/sbin:/usr/local/bin`, and you set an environment variable named `PATH` with a value of `$PATH:/usr/share/ant/bin`, then `/usr/local/sbin:/usr/local/bin` is replaced by the literal value `$PATH:/usr/share/ant/bin`\. Do not set any environment variable with a name that begins with `CODEBUILD_`\. This prefix is reserved for internal use\. If an environment variable with the same name is defined in multiple places, the value is determined as follows: -The value in the start build operation call takes highest precedence\. -The value in the build project definition takes next precedence\. -The value in the buildspec declaration takes lowest precedence\. - - If you use Secrets Manager, for *environmentVariable\-value*, set the parameter's name as stored in Secrets Manager\. Set *environmentVariable\-type* to `SECRETS_MANAGER`\. Using a secret named `/CodeBuild/dockerLoginPassword` as an example, set *environmentVariable\-name* to `LOGIN_PASSWORD`\. Set *environmentVariable\-value* to `/CodeBuild/dockerLoginPassword`\. Set *environmentVariable\-type* to `SECRETS_MANAGER`\. -**Important** ++ The value in the start build operation call takes highest precedence\. ++ The value in the build project definition takes next precedence\. ++ The value in the buildspec declaration takes lowest precedence\. +If you use Secrets Manager, for `value`, set the parameter's name as stored in Secrets Manager\. Set `type` to `SECRETS_MANAGER`\. Using a secret named `/CodeBuild/dockerLoginPassword` as an example, set `name` to `LOGIN_PASSWORD`\. Set `value` to `/CodeBuild/dockerLoginPassword`\. Set `type` to `SECRETS_MANAGER`\. If you use Secrets Manager, we recommend that you store secrets with names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*\. If your build project refers to secrets stored in Secrets Manager, the build project's service role must allow the `secretsmanager:GetSecretValue` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. If your build project refers to secrets stored in Secrets Manager with secret names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update the service role to allow access to secret names that do not start with `/CodeBuild/`\. This is because the service role allows access only to secret names that start with `/CodeBuild/`\. If you choose **New service role**, the service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. - + Use the optional `registryCredential` to specify information about credentials that provide access to a private Docker registry\. - + *credential\-arn\-or\-name*: Specifies the ARN or name of credentials created using AWS Managed Services \. You can use the name of the credentials only if they exist in your current Region\. - + *credential\-provider*: The only valid value is `SECRETS_MANAGER`\. - - When this is set: - + `imagePullCredentials` must be set to `SERVICE_ROLE`\. - + Images cannot be curated or an Amazon ECR image\. - + *imagePullCredentialsType\-value*: Optional\. The type of credentials CodeBuild uses to pull images in your build\. There are two valid values: - + `CODEBUILD` specifies that CodeBuild uses its own credentials\. You must edit your Amazon ECR repository policy to trust the CodeBuild service principal\. - + `SERVICE_ROLE` specifies that CodeBuild uses your build project's service role\. - - When you use a cross\-account or private registry image, you must use `SERVICE_ROLE` credentials\. When you use a CodeBuild curated image, you must use `CODEBUILD` credentials\. - + You must specify *privilegedMode* with a value of `true` only if you plan to use this build project to build Docker images, and the build environment image you specified is not provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it\. One way to do this is to initialize the Docker daemon in the `install` phase of your buildspec file by running the following build commands\. Do not run these commands if you specified a build environment image provided by CodeBuild with Docker support\. -**Note** + +environment/**registryCredential** +Optional\. A [RegistryCredential](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_RegistryCredential.html) object that specifies the credentials that provide access to a private Docker registry\. +environment/registryCredential/**credential** +Specifies the ARN or name of credentials created using AWS Managed Services\. You can use the name of the credentials only if they exist in your current Region\. +environment/registryCredential/**credentialProvider** +The only valid value is `SECRETS_MANAGER`\. +When this is set: ++ `imagePullCredentials` must be set to `SERVICE_ROLE`\. ++ The image cannot be a curated image or an Amazon ECR image\. + +environment/**imagePullCredentialsType** +Optional\. The type of credentials CodeBuild uses to pull images in your build\. There are two valid values: +CODEBUILD +`CODEBUILD` specifies that CodeBuild uses its own credentials\. You must edit your Amazon ECR repository policy to trust the CodeBuild service principal\. +SERVICE\_ROLE +Specifies that CodeBuild uses your build project's service role\. +When you use a cross\-account or private registry image, you must use `SERVICE_ROLE` credentials\. When you use a CodeBuild curated image, you must use `CODEBUILD` credentials\. + +environment/**privilegedMode** +Set to `true` only if you plan to use this build project to build Docker images, and the build environment image you specified is not provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it\. One way to do this is to initialize the Docker daemon in the `install` phase of your buildspec file by running the following build commands\. Do not run these commands if you specified a build environment image provided by CodeBuild with Docker support\. By default, Docker containers do not allow access to any devices\. Privileged mode grants a build project's Docker container access to all devices\. For more information, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. - ``` - - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay& - - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" - ``` - + *badgeEnabled*: Optional\. To include build badges with your CodeBuild project, you must specify *badgeEnabled* with a value of `true`\. For more information, see [Build badges sample with CodeBuild](sample-build-badges.md)\. - + *timeoutInMinutes*: Optional\. The number of minutes, between 5 to 480 \(8 hours\), after which CodeBuild stops the build if it is not complete\. If not specified, the default of 60 is used\. To determine if and when CodeBuild stopped a build due to a timeout, run the `batch-get-builds` command\. To determine if the build has stopped, look in the output for a `buildStatus` value of `FAILED`\. To determine when the build timed out, look in the output for the `endTime` value associated with a `phaseStatus` value of `TIMED_OUT`\. - + *encryptionKey*: Optional\. The alias or ARN of the AWS KMS customer managed key \(CMK\) used by CodeBuild to encrypt the build output\. If you specify an alias, use the format `arn:aws:kms:region-ID:account-ID:key/key-ID` or, if an alias exists, use the format `alias/key-alias`\. If not specified, the AWS\-managed CMK for Amazon S3 is used\. - + For the optional *tags* array, information about any tags you want to associate with this build project\. You can specify up to 50 tags\. These tags can be used by any AWS service that supports CodeBuild build project tags\. Each tag is expressed as an object with a `key` and `value` value of *tag\-key* and *tag\-value*\. - -1. Switch to the directory that contains the file you just saved, and run the create\-project command again: - - ``` - aws codebuild create-project --cli-input-json file://create-project.json - ``` - -1. If successful, data similar to the following appears in the output: - - ``` - { - "project": { - "name": "project-name", - "description": "description", - "serviceRole": "serviceRole", - "tags": [ - { - "key": "tags-key", - "value": "tags-value" - } - ], - "artifacts": { - "namespaceType": "namespaceType", - "packaging": "packaging", - "path": "path", - "type": "artifacts-type", - "location": "artifacts-location", - "name": "artifacts-name" - }, - "lastModified": lastModified, - "timeoutInMinutes": timeoutInMinutes, - "created": created, - "environment": { - "computeType": "computeType", - "image": "image", - "type": "environment-type", - "environmentVariables": [ - { - "name": "environmentVariable-name", - "value": "environmentVariable-value", - "type": "environmentVariable-type" - } - ] - }, - "source": { - "type": "source-type", - "location": "source-location", - "buildspec": "buildspec", - "auth": { - "type": "auth-type", - "resource": "resource" - } - }, - "encryptionKey": "encryptionKey", - "arn": "arn" - } - } - ``` - + The `project` object contains information about the new build project: - + The `lastModified` value represents the time, in Unix time format, when information about the build project was last changed\. - + The `created` value represents the time, in Unix time format, when the build project was created\. - + The `arn` value is the ARN of the build project\. - -**Note** -Except for the build project name, you can change any of the build project's settings later\. For more information, see [Change a build project's settings \(AWS CLI\)](change-project.md#change-project-cli)\. +``` +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & +- timeout 15 sh -c "until docker info; do echo .; sleep 1; done" +``` + +### serviceRole + +Required\. The ARN of the service role CodeBuild uses to interact with services on behalf of the IAM user \(for example, `arn:aws:iam::account-id:role/role-name`\)\. + +### timeoutInMinutes + +Optional\. The number of minutes, between 5 to 480 \(8 hours\), after which CodeBuild stops the build if it is not complete\. If not specified, the default of 60 is used\. To determine if and when CodeBuild stopped a build due to a timeout, run the `batch-get-builds` command\. To determine if the build has stopped, look in the output for a `buildStatus` value of `FAILED`\. To determine when the build timed out, look in the output for the `endTime` value associated with a `phaseStatus` value of `TIMED_OUT`\. + +### queuedTimeoutInMinutes + +Optional\. The number of minutes, between 5 to 480 \(8 hours\), after which CodeBuild stops the build if it is is still queued\. If not specified, the default of 60 is used\. + +### encryptionKey + +Optional\. The alias or ARN of the AWS KMS key used by CodeBuild to encrypt the build output\. If you specify an alias, use the format `arn:aws:kms:region-ID:account-ID:key/key-ID` or, if an alias exists, use the format `alias/key-alias`\. If not specified, the AWS\-managed KMS key for Amazon S3 is used\. + +### tags + +Optional\. An array of [Tag](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Tag.html) objects that provide the tags you want to associate with this build project\. You can specify up to 50 tags\. These tags can be used by any AWS service that supports CodeBuild build project tags\. Each tag is expressed as an object with a `key` and a `value`\. + +### vpcConfig + +Optional\. A [VpcConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_VpcConfig.html) object that contains information information about the VPC configuration for your project\. For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. + +These properties include: + +vpcId +Required\. The VPC ID that CodeBuild uses\. Run this command to get a list of all VPC IDs in your Region: + +``` +aws ec2 describe-vpcs --region +``` + +subnets +Required\. An array of subnet IDs that include resources used by CodeBuild\. Run this command to get these IDs: + +``` +aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region +``` + +securityGroupIds +Required\. An array of security group IDs used by CodeBuild to allow access to resources in the VPC\. Run this command to get these IDs: + +``` +aws ec2 describe-security-groups --filters "Name=vpc-id,Values=" -- +``` + +### badgeEnabled + +Optional\. Specifies whether to include build badges with your CodeBuild project\. Set to `true` to enable build badges, or `false` otherwise\. For more information, see [Build badges sample with CodeBuild](sample-build-badges.md)\. + +### logsConfig + +A [LogsConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_LogsConfig.html) object that contains information about where this build's logs are located\. + +logsConfig/**cloudWatchLogs** +A [CloudWatchLogsConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CloudWatchLogsConfig.html) object that contains information about pushing logs to CloudWatch Logs\. + +logsConfig/**s3Logs** +An [S3LogsConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_S3LogsConfig.html) object that contains information about pushing logs to Amazon S3\. + +### fileSystemLocations + +Optional\. An array of [ProjectFileSystemsLocation](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectFileSystemLocation.html) objects that contains informationabout your Amazon EFS configuration\. + +### buildBatchConfig + +Optional\. The `buildBatchConfig` object is a [ProjectBuildBatchConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectBuildBatchConfig.html) structure that contains the batch build configuration information for the project\. + +buildBatchConfig/**serviceRole** +The service role ARN for the batch build project\. + +buildBatchConfig/**combineArtifacts** +A Boolean value that specifies whether to combine the build artifacts for the batch build into a single artifact location\. + +buildBatchConfig/restrictions/**maximumBuildsAllowed** +The maximum number of builds allowed\. + +buildBatchConfig/restrictions/**computeTypesAllowed** +An array of strings that specify the compute types that are allowed for the batch build\. See [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html) for these values\. + +buildBatchConfig/**timeoutInMinutes** +The maximum amount of time, in minutes, that the batch build must be completed in\. + +buildBatchConfig/**batchReportMode** +Specifies how build status reports are sent to the source provider for the batch build\. Valid values include: +`REPORT_AGGREGATED_BATCH` +\(Default\) Aggregate all of the build statuses into a single status report\. +`REPORT_INDIVIDUAL_BUILDS` +Send a separate status report for each individual build\. + +### concurrentBuildLimit + +The maximum number of concurrent builds that are allowed for this project\. + +New builds are only started if the current number of builds is less than or equal to this limit\. If the current build count meets this limit, new builds are throttled and are not run\. + +## Create the project + +To create the project, run the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/create-project.html) command again, passing your JSON file: + +``` +aws codebuild create-project --cli-input-json file:// +``` + +If successful, the JSON representation of a [Project](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_Project.html) object appears in the console output\. See the [CreateProject Response Syntax](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CreateProject.html#API_CreateProject_ResponseSyntax) for an example of this data\. + +Except for the build project name, you can change any of the build project's settings later\. For more information, see [Change a build project's settings \(AWS CLI\)](change-project-cli.md)\. To start running a build, see [Run a build \(AWS CLI\)](run-build-cli.md)\. diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 99ade27..65c48e2 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -1,29 +1,49 @@ # Create a build project \(console\) -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. +Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. -1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. + If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. -1. Choose **Create build project**\. +Choose **Create build project**\. -1. In **Project configuration**: +Fill in the following sections\. Once complete, choose **Create build project** at the bottom of the page\. - On the **Create build project** page, in **Project configuration**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. +**Topics** ++ [Project configuration](#create-project-console-project-config) ++ [Source](#create-project-console-source) ++ [Environment](#create-project-console-environment) ++ [Buildspec](#create-project-console-buildspec) ++ [Batch configuration](#create-project-console-batch-config) ++ [Artifacts](#create-project-console-artifacts) ++ [Logs](#create-project-console-logs) - In **Description**, enter an optional description for your project\. +## Project configuration - Select **Build badge** to make your project's build status visible and embeddable\. For more information, see [Build badges sample](sample-build-badges.md)\. -**Note** - Build badge does not apply if your source provider is Amazon S3\. +**Project name** +Enter a name for this build project\. Build project names must be unique across each AWS account\. - Expand **Additional configuration**\. +**Description** +Enter an optional description of the build project to help other users understand what this project is used for\. - \(Optional\) For **Tags**, enter the name and value of any tags that you want supporting AWS services to use\. Use **Add row** to add a tag\. You can add up to 50 tags\. +**Build badge** +\(Optional\) Select **Enable build badge** to make your project's build status visible and embeddable\. For more information, see [Build badges sample](sample-build-badges.md)\. +Build badge does not apply if your source provider is Amazon S3\. -1. In **Source**: +**Enable concurrent build limit** +\(Optional\) If you want to limit the number of concurrent builds for this project, perform the following steps: - For **Source provider**, choose the source code provider type\. Use the following lists to make selections appropriate for your source provider: -**Note** +1. Select **Restrict number of concurrent builds this project can start**\. + +1. In **Concurrent build limit**, enter the maximum number of concurrent builds that are allowed for this project\. This limit cannot be greater than the concurrent build limit set for the account\. If you try to enter a number greater than the account limit, an error message is displayed\. +New builds are only started if the current number of builds is less than or equal to this limit\. If the current build count meets this limit, new builds are throttled and are not run\. + +**Additional information** +\(Optional\) For **Tags**, enter the name and value of any tags that you want supporting AWS services to use\. Use **Add row** to add a tag\. You can add up to 50 tags\. + +## Source + +**Source provider** +Choose the source code provider type\. Use the following lists to make selections appropriate for your source provider: CodeBuild does not support Bitbucket Server\. ------ @@ -50,8 +70,8 @@ Choose **Branch**, **Git tag**, or **Commit ID** to specify the version of your **Git clone depth** Choose to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - **Use Git submodules** -Select if you want to include Git submodules in your repository\. +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. ------ #### [ Bitbucket ] @@ -66,21 +86,18 @@ Enter a branch, commit ID, tag, or reference and a commit ID\. For more informat **Git clone depth** Choose **Git clone depth** to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - **Use Git submodules** -Select if you want to include Git submodules in your repository\. - - Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. - -**Note** -The status of a build triggered by a webhook is always reported to your source provider\. - - Select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. Webhooks are allowed only with your own Bitbucket, GitHub, or GitHub Enterprise repository\. +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. - For **Status context**, enter the value to be used for the `name` parameter in the Bitbucket commit status\. For more information, see [build](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build) in the Bitbucket API documentation\. - - For **Target URL**, enter the value to be used for the `url` parameter in the Bitbucket commit status\. For more information, see [build](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build) in the Bitbucket API documentation\. +**Build status** +Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. +For **Status context**, enter the value to be used for the `name` parameter in the Bitbucket commit status\. For more information, see [build](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build) in the Bitbucket API documentation\. +For **Target URL**, enter the value to be used for the `url` parameter in the Bitbucket commit status\. For more information, see [build](https://developer.atlassian.com/bitbucket/api/2/reference/resource/repositories/%7Bworkspace%7D/%7Brepo_slug%7D/commit/%7Bnode%7D/statuses/build) in the Bitbucket API documentation\. +The status of a build triggered by a webhook is always reported to the source provider\. To have the status of a build that is started from the console or an API call reported to the source provider, you must select this setting\. +If your project's builds are triggered by a webhook, you must push a new commit to the repo for a change to this setting to take effect\. - If you chose **Rebuild every time a code change is pushed to this repository**, in **Event type**, choose an event that you want to trigger a build\. You use regular expressions to create a filter\. If no filter is specified, all update and create pull requests, and all push events, trigger a build\. For more information, see [ Filter GitHub webhook events](sample-github-pull-request.md#sample-github-pull-request-filter-webhook-events) and [ Filter Bitbucket webhook events](sample-bitbucket-pull-request.md#sample-bitbucket-pull-request-filter-webhook-events)\. +In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. For more information about webhooks and filter groups, see [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub ] @@ -95,118 +112,94 @@ Enter a branch, commit ID, tag, or reference and a commit ID\. For more informat **Git clone depth** Choose **Git clone depth** to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - **Use Git submodules** -Select if you want to include Git submodules in your repository\. - - Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. - -**Note** -The status of a build triggered by a webhook is always reported to your source provider\. - - Select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. Webhooks are allowed only with your own Bitbucket, GitHub, or GitHub Enterprise repository\. +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. - For **Status context**, enter the value to be used for the `context` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. - - For **Target URL**, enter the value to be used for the `target_url` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +**Build status** +Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. +For **Status context**, enter the value to be used for the `context` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +For **Target URL**, enter the value to be used for the `target_url` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +The status of a build triggered by a webhook is always reported to the source provider\. To have the status of a build that is started from the console or an API call reported to the source provider, you must select this setting\. +If your project's builds are triggered by a webhook, you must push a new commit to the repo for a change to this setting to take effect\. - If you chose **Rebuild every time a code change is pushed to this repository**, in **Event type**, choose an event that you want to trigger a build\. You use regular expressions to create a filter\. If no filter is specified, all update and create pull requests, and all push events, trigger a build\. For more information, see [ Filter GitHub webhook events](sample-github-pull-request.md#sample-github-pull-request-filter-webhook-events) and [ Filter Bitbucket webhook events](sample-bitbucket-pull-request.md#sample-bitbucket-pull-request-filter-webhook-events)\. +In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. For more information about webhooks and filter groups, see [GitHub webhook events](github-webhook.md)\. ------ #### [ GitHub Enterprise Server ] - **GitHub Enterprise personal access token** +**GitHub Enterprise personal access token** See [GitHub Enterprise Server sample](sample-github-enterprise.md) for information about how to copy a personal access token to your clipboard\. Paste the token in the text field, and then choose **Save Token**\. You only need to enter and save the personal access token once\. CodeBuild uses this token in all future projects\. - **Source version** +**Source version** Enter a pull request, branch, commit ID, tag, or reference and a commit ID\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md)\. - **Git clone depth** +**Git clone depth** Choose **Git clone depth** to create a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - **Use Git submodules** -Select if you want to include Git submodules in your repository\. +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. - **Build status** +**Build status** Select **Report build statuses to source provider when your builds start and finish ** if you want the status of your build's start and completion reported to your source provider\. -The status of a build triggered by a webhook is always reported to your source provider\. +To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. +For **Status context**, enter the value to be used for the `context` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +For **Target URL**, enter the value to be used for the `target_url` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. +The status of a build triggered by a webhook is always reported to the source provider\. To have the status of a build that is started from the console or an API call reported to the source provider, you must select this setting\. +If your project's builds are triggered by a webhook, you must push a new commit to the repo for a change to this setting to take effect\. - **Insecure SSL** -Choose to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. +**Insecure SSL** +Select **Enable insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. - Select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. Webhooks are allowed only with your own Bitbucket, GitHub, or GitHub Enterprise repository\. - - For **Status context**, enter the value to be used for the `context` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. - - For **Target URL**, enter the value to be used for the `target_url` parameter in the GitHub commit status\. For more information, see [Create a commit status](https://developer.github.com/v3/repos/statuses/#create-a-commit-status) in the GitHub developer guide\. - - If you chose **Rebuild every time a code change is pushed to this repository**, in **Event type**, choose an event that you want to trigger a build\. You use regular expressions to create a filter\. If no filter is specified, all update and create pull requests, and all push events, trigger a build\. For more information, see [ Filter GitHub webhook events](sample-github-pull-request.md#sample-github-pull-request-filter-webhook-events) and [ Filter Bitbucket webhook events](sample-bitbucket-pull-request.md#sample-bitbucket-pull-request-filter-webhook-events)\. +In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository ** if you want CodeBuild to build the source code every time a code change is pushed to this repository\. For more information about webhooks and filter groups, see [GitHub webhook events](github-webhook.md)\. ------ - For each secondary source you want: - - 1. Choose **Add source**\. +## Environment - 1. For **Source identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. +**Environment image** +Do one of the following: ++ To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. ++ To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. ++ To use a private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. +CodeBuild overrides the `ENTRYPOINT` for custom Docker images\. - 1. For **Source provider**, choose the source code provider type\. Use the table earlier in this step to make selections appropriate for your secondary source provider\. - -1. In **Environment**: - - For **Environment image**, do one of the following: - + To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. - + To use private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. - - \(Optional\) Select **Privileged** only if you plan to use this build project to build Docker images, and the build environment image you chose is not provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it\. One way to do this is to initialize the Docker daemon in the `install` phase of your build spec by running the following build commands\. Do not run these commands if you chose a build environment image provided by CodeBuild with Docker support\. -**Note** +**Privileged** +\(Optional\) Select **Privileged** only if you plan to use this build project to build Docker images, and the build environment image you chose is not provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it\. One way to do this is to initialize the Docker daemon in the `install` phase of your build spec by running the following build commands\. Do not run these commands if you chose a build environment image provided by CodeBuild with Docker support\. By default, Docker containers do not allow access to any devices\. Privileged mode grants a build project's Docker container access to all devices\. For more information, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. - ``` - - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay& - - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" - ``` - - In **Service role**, do one of the following: - + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. -**Note** -When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. - - Expand **Additional configuration**\. - - \(Optional\) For **Timeout**, specify a value between 5 minutes and 480 minutes \(8 hours\) after which CodeBuild stops the build if it is not complete\. If **hours** and **minutes** are left blank, the default value of 60 minutes is used\. - - If you want CodeBuild to work with your VPC: - + For **VPC**, choose the VPC ID that CodeBuild uses\. - + For **VPC Subnets**, choose the subnets that include resources that CodeBuild uses\. - + For **VPC Security groups**, choose the security groups that CodeBuild uses to allow access to resources in the VPCs\. - - For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. - - If you want to use one or more elastic file systems: - + For **Identifier**, enter a unique file system identifier\. It must be fewer than 129 characters and contain only alphanumeric characters and underscores\. CodeBuild uses this identifier to create an environment variable that identifies the elastic file system\. The environment variable format is `CODEBUILD_file-system-identifier` in capital letters\. For example, if you enter **efs\-1**, the environment variable is `CODEBUILD_EFS-1`\. - + For **ID**, choose the file system ID\. - + \(Optional\) Enter a directory in the file system\. CodeBuild mounts this directory\. If you leave **Directory path** blank, CodeBuild mounts the entire file system\. The path is relative to the root of the file system\. - + For **Mount point**, enter the absolute path of the directory in your build container where the file system is mounted\. If this directory does not exist, CodeBuild creates it during the build\. - + \(Optional\) Enter mount options\. If you leave **Mount options** blank, CodeBuild uses its default mount options \(`nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2`\)\. For more information, see [Recommended NFS Mount Options](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs-nfs-mount-settings.html) in the *Amazon Elastic File System User Guide*\. - - For **Compute**, choose one of the available options\. - - For **Environment variables**, enter the name and value, and then choose the type of each environment variable for builds to use\. -**Note** +``` +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & +- timeout 15 sh -c "until docker info; do echo .; sleep 1; done" +``` + +**Service role** +Do one of the following: ++ If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. ++ If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. +When you use the console to create a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. + +**Additional configuration** +**Timeout** +Specify a value, between 5 minutes and 8 hours, after which CodeBuild stops the build if it is not complete\. If **hours** and **minutes** are left blank, the default value of 60 minutes is used\. +**VPC** +If you want CodeBuild to work with your VPC: ++ For **VPC**, choose the VPC ID that CodeBuild uses\. ++ For **VPC Subnets**, choose the subnets that include resources that CodeBuild uses\. ++ For **VPC Security groups**, choose the security groups that CodeBuild uses to allow access to resources in the VPCs\. +For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. +**Compute** +Choose one of the available options\. +**Environment variables** +Enter the name and value, and then choose the type of each environment variable for builds to use\. CodeBuild sets the environment variable for your AWS Region automatically\. You must set the following environment variables if you haven't added them to your buildspec\.yml: -AWS\_ACCOUNT\_ID -IMAGE\_REPO\_NAME -IMAGE\_TAG - - Console and AWS CLI users can see environment variables\. If you have no concerns about the visibility of your environment variable, set the **Name** and **Value** fields, and then set **Type** to **Plaintext**\. - - We recommend that you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager\. - - If you use Amazon EC2 Systems Manager Parameter Store, then for **Type**, choose **Parameter**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter the parameter's name as stored in Amazon EC2 Systems Manager Parameter Store\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, for **Type**, choose **Parameter**\. For **Name**, enter `LOGIN_PASSWORD`\. For **Value**, enter `/CodeBuild/dockerLoginPassword`\. -**Important** ++ AWS\_ACCOUNT\_ID ++ IMAGE\_REPO\_NAME ++ IMAGE\_TAG +Console and AWS CLI users can see environment variables\. If you have no concerns about the visibility of your environment variable, set the **Name** and **Value** fields, and then set **Type** to **Plaintext**\. +We recommend that you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager\. +If you use Amazon EC2 Systems Manager Parameter Store, then for **Type**, choose **Parameter**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter the parameter's name as stored in Amazon EC2 Systems Manager Parameter Store\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, for **Type**, choose **Parameter**\. For **Name**, enter `LOGIN_PASSWORD`\. For **Value**, enter `/CodeBuild/dockerLoginPassword`\. If you use Amazon EC2 Systems Manager Parameter Store, we recommend that you store parameters with parameter names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager\. Choose **Create parameter**, and then follow the instructions in the dialog box\. \(In that dialog box, for **KMS key**, you can specify the ARN of an AWS KMS key in your account\. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt it during retrieval\.\) If you use the CodeBuild console to create a parameter, the console starts the parameter name with `/CodeBuild/` as it is being stored\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store Console Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the `ssm:GetParameters` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update that service role to allow access to parameter names that do not start with `/CodeBuild/`\. This is because that service role allows access only to parameter names that start with `/CodeBuild/`\. @@ -214,82 +207,118 @@ If you choose **New service role**, the service role includes permission to decr Environment variables you set replace existing environment variables\. For example, if the Docker image already contains an environment variable named `MY_VAR` with a value of `my_value`, and you set an environment variable named `MY_VAR` with a value of `other_value`, then `my_value` is replaced by `other_value`\. Similarly, if the Docker image already contains an environment variable named `PATH` with a value of `/usr/local/sbin:/usr/local/bin`, and you set an environment variable named `PATH` with a value of `$PATH:/usr/share/ant/bin`, then `/usr/local/sbin:/usr/local/bin` is replaced by the literal value `$PATH:/usr/share/ant/bin`\. Do not set any environment variable with a name that begins with `CODEBUILD_`\. This prefix is reserved for internal use\. If an environment variable with the same name is defined in multiple places, the value is determined as follows: -The value in the start build operation call takes highest precedence\. -The value in the build project definition takes next precedence\. -The value in the buildspec declaration takes lowest precedence\. - - If you use Secrets Manager, for **Type**, choose **Secrets Manager**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter a `reference-key` using the pattern `secret-id:json-key:version-stage:version-id`\. For information, see [Secrets Manager reference-key in the buildspec file](build-spec-ref.md#secrets-manager-build-spec)\. -**Important** ++ The value in the start build operation call takes highest precedence\. ++ The value in the build project definition takes next precedence\. ++ The value in the buildspec declaration takes lowest precedence\. +If you use Secrets Manager, for **Type**, choose **Secrets Manager**\. For **Name**, enter an identifier for CodeBuild to reference\. For **Value**, enter a `reference-key` using the pattern `secret-id:json-key:version-stage:version-id`\. For information, see [Secrets Manager reference-key in the buildspec file](build-spec-ref.md#secrets-manager-build-spec)\. If you use Secrets Manager, we recommend that you store secrets with names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*\. If your build project refers to secrets stored in Secrets Manager, the build project's service role must allow the `secretsmanager:GetSecretValue` action\. If you chose **New service role** earlier, CodeBuild includes this action in the default service role for your build project\. However, if you chose **Existing service role**, you must include this action to your service role separately\. If your build project refers to secrets stored in Secrets Manager with secret names that do not start with `/CodeBuild/`, and you chose **New service role**, you must update the service role to allow access to secret names that do not start with `/CodeBuild/`\. This is because the service role allows access only to secret names that start with `/CodeBuild/`\. If you choose **New service role**, the service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. -1. In **Buildspec**: - - For **Build specifications**, do one of the following: - + If your source code includes a buildspec file, choose **Use a buildspec file**\. By default, CodeBuild looks for a file named `buildspec.yml` in the source code root directory\. If your buildspec file uses a different name or location, enter its path from the source root in **Buildspec name** \(for example, `buildspec-two.yml` or `configuration/buildspec.yml`\. If the buildspec file is in an S3 bucket, it must be in the same AWS Region as your build project\. Specify the buildspec file using its ARN \(for example, `arn:aws:s3:::my-codebuild-sample2/buildspec.yml`\)\. - + If your source code does not include a buildspec file, or if you want to run build commands different from the ones specified for the `build` phase in the `buildspec.yml` file in the source code's root directory, choose **Insert build commands**\. For **Build commands**, enter the commands you want to run in the `build` phase\. For multiple commands, separate each command by `&&` \(for example, `mvn test && mvn package`\)\. To run commands in other phases, or if you have a long list of commands for the `build` phase, add a `buildspec.yml` file to the source code root directory, add the commands to the file, and then choose **Use the buildspec\.yml in the source code root directory**\. - - For more information, see the [Buildspec reference](build-spec-ref.md)\. - -1. In **Artifacts**: - - For **Type**, do one of the following: - + If you do not want to create any build output artifacts, choose **No artifacts**\. You might want to do this if you're only running build tests or you want to push a Docker image to an Amazon ECR repository\. - + To store the build output in an S3 bucket, choose **Amazon S3**, and then do the following: - + If you want to use your project name for the build output ZIP file or folder, leave **Name** blank\. Otherwise, enter the name\. \(If you want to output a ZIP file, and you want the ZIP file to have a file extension, be sure to include it after the ZIP file name\.\) - + Select **Enable semantic versioning** if you want a name specified in the buildspec file to override any name that is specified in the console\. The name in a buildspec file is calculated at build time and uses the Shell command language\. For example, you can append a date and time to your artifact name so that it is always unique\. Unique artifact names prevent artifacts from being overwritten\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - + For **Bucket name**, choose the name of the output bucket\. - + If you chose **Insert build commands** earlier in this procedure, then for **Output files**, enter the locations of the files from the build that you want to put into the build output ZIP file or folder\. For multiple locations, separate each location with a comma \(for example, `appspec.yml, target/my-app.jar`\)\. For more information, see the description of `files` in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - + If you do not want your build artifacts encrypted, select **Remove artifacts encryption**\. - - For each secondary set of artifacts you want: - - 1. For **Artifact identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. - - 1. Choose **Add artifact**\. - - 1. Follow the previous steps to configure your secondary artifacts\. - - 1. Choose **Save artifact**\. - - Expand **Additional configuration**\. - - \(Optional\) For **Encryption key**, do one of the following: - + To use the AWS\-managed customer managed key \(CMK\) for Amazon S3 in your account to encrypt the build output artifacts, leave **Encryption key** blank\. This is the default\. - + To use a customer\-managed CMK to encrypt the build output artifacts, in **Encryption key**, enter the ARN of the CMK\. Use the format `arn:aws:kms:region-ID:account-ID:key/key-ID`\. - - For **Cache type**, choose one of the following: - + If you do not want to use a cache, choose **No cache**\. - + If you want to use an Amazon S3 cache, choose **Amazon S3**, and then do the following: - + For **Bucket**, choose the name of the S3 bucket where the cache is stored\. - + \(Optional\) For **Cache path prefix**, enter an Amazon S3 path prefix\. The **Cache path prefix** value is similar to a directory name\. It makes it possible for you to store the cache under the same directory in a bucket\. +## Buildspec + +**Build specifications** +Do one of the following: ++ If your source code includes a buildspec file, choose **Use a buildspec file**\. By default, CodeBuild looks for a file named `buildspec.yml` in the source code root directory\. If your buildspec file uses a different name or location, enter its path from the source root in **Buildspec name** \(for example, `buildspec-two.yml` or `configuration/buildspec.yml`\. If the buildspec file is in an S3 bucket, it must be in the same AWS Region as your build project\. Specify the buildspec file using its ARN \(for example, `arn:aws:s3:::my-codebuild-sample2/buildspec.yml`\)\. ++ If your source code does not include a buildspec file, or if you want to run build commands different from the ones specified for the `build` phase in the `buildspec.yml` file in the source code's root directory, choose **Insert build commands**\. For **Build commands**, enter the commands you want to run in the `build` phase\. For multiple commands, separate each command by `&&` \(for example, `mvn test && mvn package`\)\. To run commands in other phases, or if you have a long list of commands for the `build` phase, add a `buildspec.yml` file to the source code root directory, add the commands to the file, and then choose **Use the buildspec\.yml in the source code root directory**\. +For more information, see the [Buildspec reference](build-spec-ref.md)\. + +## Batch configuration + +You can run a group of builds as a single operation\. For more information, see [Batch builds in AWS CodeBuild](batch-build.md)\. + +**Define batch configuration** +Select to allow batch builds in this project\. + +**Batch service role** +Provides the service role for batch builds\. +Choose one of the following: ++ If you do not have a batch service role, choose **New service role**\. In **Service role**, enter a name for the new role\. ++ If you have a batch service role, choose **Existing service role**\. In **Service role**, choose the service role\. +Batch builds introduce a new security role in the batch configuration\. This new role is required as CodeBuild must be able to call the `StartBuild`, `StopBuild`, and `RetryBuild` actions on your behalf to run builds as part of a batch\. Customers should use a new role, and not the same role they use in their build, for two reasons: ++ Giving the build role `StartBuild`, `StopBuild`, and `RetryBuild` permissions would allow a single build to start more builds via the buildspec\. ++ CodeBuild batch builds provide restrictions that restrict the number of builds and compute types that can be used for the builds in the batch\. If the build role has these permissions, it is possible the builds themselves could bypass these restrictions\. + +**Allowed compute type\(s\) for batch** +Select the compute types allowed for the batch\. Select all that apply\. + +**Maximum builds allowed in batch** +Enter the maximum number of builds allowed in the batch\. If a batch exceeds this limit, the batch will fail\. + +**Batch timeout** +Enter the maximum amount of time for the batch build to complete\. + +**Combine artifacts** +Select **Combine all artifacts from batch into a single location** to have all of the artifacts from the batch combined into a single location\. + + **Batch report mode** +Select the desired build status report mode for batch builds\. +This field is only available when the project source is Bitbucket, GitHub, or GitHub Enterprise, and **Report build statuses to source provider when your builds start and finish** is selected under **Source**\. + **Aggregated builds** +Select to have the statuses for all builds in the batch combined into a single status report\. + **Individual builds** +Select to have the build statuses for all builds in the batch reported separately\. + +## Artifacts + +**Type** +Do one of the following: ++ If you do not want to create any build output artifacts, choose **No artifacts**\. You might want to do this if you're only running build tests or you want to push a Docker image to an Amazon ECR repository\. ++ To store the build output in an S3 bucket, choose **Amazon S3**, and then do the following: + + If you want to use your project name for the build output ZIP file or folder, leave **Name** blank\. Otherwise, enter the name\. \(If you want to output a ZIP file, and you want the ZIP file to have a file extension, be sure to include it after the ZIP file name\.\) + + Select **Enable semantic versioning** if you want a name specified in the buildspec file to override any name that is specified in the console\. The name in a buildspec file is calculated at build time and uses the Shell command language\. For example, you can append a date and time to your artifact name so that it is always unique\. Unique artifact names prevent artifacts from being overwritten\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + For **Bucket name**, choose the name of the output bucket\. + + If you chose **Insert build commands** earlier in this procedure, then for **Output files**, enter the locations of the files from the build that you want to put into the build output ZIP file or folder\. For multiple locations, separate each location with a comma \(for example, `appspec.yml, target/my-app.jar`\)\. For more information, see the description of `files` in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + If you do not want your build artifacts encrypted, select **Remove artifacts encryption**\. +For each secondary set of artifacts you want: + +1. For **Artifact identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. + +1. Choose **Add artifact**\. + +1. Follow the previous steps to configure your secondary artifacts\. + +1. Choose **Save artifact**\. + +**Additional configuration** +**Encryption key** +\(Optional\) Do one of the following: ++ To use the AWS managed key for Amazon S3 in your account to encrypt the build output artifacts, leave **Encryption key** blank\. This is the default\. ++ To use a customer managed key to encrypt the build output artifacts, in **Encryption key**, enter the ARN of the KMS key\. Use the format `arn:aws:kms:region-ID:account-ID:key/key-ID`\. +**Cache type** +For **Cache type**, choose one of the following: ++ If you do not want to use a cache, choose **No cache**\. ++ If you want to use an Amazon S3 cache, choose **Amazon S3**, and then do the following: + + For **Bucket**, choose the name of the S3 bucket where the cache is stored\. + + \(Optional\) For **Cache path prefix**, enter an Amazon S3 path prefix\. The **Cache path prefix** value is similar to a directory name\. It makes it possible for you to store the cache under the same directory in a bucket\. **Important** Do not append a trailing slash \(/\) to the end of the path prefix\. - + If you want to use a local cache, choose **Local**, and then choose one or more local cache modes\. ++ If you want to use a local cache, choose **Local**, and then choose one or more local cache modes\. **Note** -Docker layer cache mode is available for Linux only\. If you choose it, your project must run in privileged mode\. The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_GENERAL1_2XLARGE` compute type do not support the use of a local cache\. - - Using a cache saves considerable build time because reusable pieces of the build environment are stored in the cache and used across builds\. For information about specifying a cache in the buildspec file, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build caching in AWS CodeBuild](build-caching.md)\. - -1. In **Logs**, choose the logs you want to create\. You can create Amazon CloudWatch Logs, Amazon S3 logs, or both\. - - If you want Amazon CloudWatch Logs logs: - + Select **CloudWatch logs**\. - + In **Group name**, enter the name of your Amazon CloudWatch Logs log group\. - + In **Stream name**, enter your Amazon CloudWatch Logs log stream name\. - - If you want Amazon S3 logs: - + Select **S3 logs**\. - + From **Bucket**, choose the name of the S3 bucket for your logs\. - + In **Path prefix**, enter the prefix for your logs\. - - \(Optional\) If you chose **Amazon S3** for **Type** in **Artifacts** earlier in this procedure, then for **Artifacts packaging**, do one of the following: - + To have CodeBuild create a ZIP file that contains the build output, choose **Zip**\. - + To have CodeBuild create a folder that contains the build output, choose **None**\. \(This is the default\.\) - + Select **Remove S3 log encryption** if you do not want your S3 logs encrypted\. - -1. Choose **Create build project**\. - -1. On the **Review** page, choose **Start build**\. \ No newline at end of file +Docker layer cache mode is available for Linux only\. If you choose it, your project must run in privileged mode\. +Using a cache saves considerable build time because reusable pieces of the build environment are stored in the cache and used across builds\. For information about specifying a cache in the buildspec file, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build caching in AWS CodeBuild](build-caching.md)\. + +## Logs + +Choose the logs you want to create\. You can create Amazon CloudWatch Logs, Amazon S3 logs, or both\. + +**CloudWatch** +If you want Amazon CloudWatch Logs logs: +**CloudWatch logs** +Select **CloudWatch logs**\. +**Group name** +Enter the name of your Amazon CloudWatch Logs log group\. +**Stream name** +Enter your Amazon CloudWatch Logs log stream name\. + +**S3** +If you want Amazon S3 logs: +**S3 logs** +Select **S3 logs**\. +**Bucket** +Choose the name of the S3 bucket for your logs\. +**Path prefix** +Enter the prefix for your logs\. +**Disable S3 log encryption** +Select if you do not want your S3 logs encrypted\. \ No newline at end of file diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 946c843..c5195a1 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -2,13 +2,13 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to create a build project\. +## Prerequisites + +Before creating a build project, answer the questions in [Plan a build](planning.md)\. + **Topics** + [Prerequisites](#create-project-prerequisites) + [Create a build project \(console\)](create-project-console.md) + [Create a build project \(AWS CLI\)](create-project-cli.md) + [Create a build project \(AWS SDKs\)](create-project-sdks.md) -+ [Create a build project \(AWS CloudFormation\)](create-project-cloud-formation.md) - -## Prerequisites - -Answer the questions in [Plan a build](planning.md)\. \ No newline at end of file ++ [Create a build project \(AWS CloudFormation\)](create-project-cloud-formation.md) \ No newline at end of file diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 6d58469..836f7b5 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -1,20 +1,21 @@ # Data protection in AWS CodeBuild - AWS CodeBuild conforms to the AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/), which includes regulations and guidelines for data protection\. AWS is responsible for protecting the global infrastructure that runs all the AWS services\. AWS maintains control over data hosted on this infrastructure, including the security configuration controls for handling customer content and personal data\. AWS customers and APN partners, acting either as data controllers or data processors, are responsible for any personal data that they put in the AWS Cloud\. +The AWS [shared responsibility model](http://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in AWS CodeBuild\. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud\. You are responsible for maintaining control over your content that is hosted on this infrastructure\. This content includes the security configuration and management tasks for the AWS services that you use\. For more information about data privacy, see the [Data Privacy FAQ](http://aws.amazon.com/compliance/data-privacy-faq)\. For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](http://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*\. - For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management \(IAM\), so that each user is given only the permissions necessary to fulfill their job duties\. We also recommend that you secure your data in the following ways: +For data protection purposes, we recommend that you protect AWS account credentials and set up individual user accounts with AWS Identity and Access Management \(IAM\)\. That way each user is given only the permissions necessary to fulfill their job duties\. We also recommend that you secure your data in the following ways: + Use multi\-factor authentication \(MFA\) with each account\. -+ Use TLS to communicate with AWS resources\. ++ Use SSL/TLS to communicate with AWS resources\. We recommend TLS 1\.2 or later\. + Set up API and user activity logging with AWS CloudTrail\. -+ Use AWS encryption solutions, along with all default security controls in AWS services\. ++ Use AWS encryption solutions, along with all default security controls within AWS services\. + Use advanced managed security services such as Amazon Macie, which assists in discovering and securing personal data that is stored in Amazon S3\. ++ If you require FIPS 140\-2 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint\. For more information about the available FIPS endpoints, see [Federal Information Processing Standard \(FIPS\) 140\-2](http://aws.amazon.com/compliance/fips/)\. -We strongly recommend that you never put sensitive identifying information, such as your customers' account numbers, into free\-form fields such as a **Name** field\. This includes when you work with CodeBuild or other AWS services using the console, API, AWS CLI, or AWS SDKs\. Any data that you enter into CodeBuild or other services might get picked up for inclusion in diagnostic logs\. When you provide a URL to an external server, don't include credentials information in the URL to validate your request to that server\. +We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free\-form fields such as a **Name** field\. This includes when you work with CodeBuild or other AWS services using the console, API, AWS CLI, or AWS SDKs\. Any data that you enter into tags or free\-form fields used for names may be used for billing or diagnostic logs\. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server\. To protect sensitive information, the following are hidden in CodeBuild logs: -+ AWS access key IDs\. For more information, see [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in in the *AWS Identity and Access Management User Guide*\. -+ Strings specified using the Parameter Store\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store console walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. -+ Strings specified using AWS Secrets Manager\. For more information, see [Key management](security-key-management.md)\. ++ AWS access key IDs\. For more information, see [Managing access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) in the *AWS Identity and Access Management User Guide*\. ++ Strings specified using the Parameter Store in CodeBuild project environment variables or the buildspec `env/parameter-store` section\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store console walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. ++ Strings specified using AWS Secrets Manager in CodeBuild project environment variables or the buildspec `env/secrets-manager` section\. For more information, see [Key management](security-key-management.md)\. For more information about data protection, see the [AWS shared responsibility model and GDPR](http://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*\. diff --git a/doc_source/endpoint-specify.md b/doc_source/endpoint-specify.md index 38cdea4..227d36b 100644 --- a/doc_source/endpoint-specify.md +++ b/doc_source/endpoint-specify.md @@ -38,9 +38,9 @@ AWSCodeBuild awsCodeBuild = AWSCodeBuildClientBuilder.standard(). build(); ``` - For information about `AWSCodeBuildClientBuilder`, see [Class AWSCodeBuildClientBuilder](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/codebuild/AWSCodeBuildClientBuilder.html)\. + For information about `AWSCodeBuildClientBuilder`, see [Class AWSCodeBuildClientBuilder](https://docs.aws.amazon.com/sdk-for-java/latest/reference/com/amazonaws/services/codebuild/AWSCodeBuildClientBuilder.html)\. - The credentials used in `withCredentials` must be of type `AWSCredentialsProvider`\. For more information, see [Working with AWS credentials](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)\. + The credentials used in `withCredentials` must be of type `AWSCredentialsProvider`\. For more information, see [Working with AWS credentials](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html)\. Do not include `https://` at the begining of the endpoint\. diff --git a/doc_source/getting-started-clean-up-console.md b/doc_source/getting-started-clean-up-console.md index b3d3db5..673bc6e 100644 --- a/doc_source/getting-started-clean-up-console.md +++ b/doc_source/getting-started-clean-up-console.md @@ -1,10 +1,10 @@ -# Step 10: Delete the S3 input bucket +# Step 10: Delete the S3 buckets \(Previous step: [Step 9: Get the build output artifact](getting-started-output-console.md)\) -To prevent ongoing charges to your AWS account, you can delete the input bucket used in this tutorial\. For instructions, see [Deleting or Emptying a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/delete-or-empty-bucket.html) in the *Amazon Simple Storage Service Developer Guide*\. +To prevent ongoing charges to your AWS account, you can delete the input and output buckets used in this tutorial\. For instructions, see [Deleting or Emptying a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/delete-or-empty-bucket.html) in the *Amazon Simple Storage Service User Guide*\. -If you are using the IAM user or an administrator IAM user to delete this bucket, the user must have more access permissions\. Add the following statement between the markers \(*\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to an existing access policy for the user\. +If you are using the IAM user or an administrator IAM user to delete these buckets, the user must have more access permissions\. Add the following statement between the markers \(*\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to an existing access policy for the user\. The ellipses \(\.\.\.\) in this statement are used for brevity\. Do not remove any statements in the existing access policy\. Do not enter these ellipses into the policy\. diff --git a/doc_source/getting-started-cli-clean-up.md b/doc_source/getting-started-cli-clean-up.md index 2239494..58fb3a6 100644 --- a/doc_source/getting-started-cli-clean-up.md +++ b/doc_source/getting-started-cli-clean-up.md @@ -1,10 +1,10 @@ -# Step 10: Delete the S3 input bucket +# Step 10: Delete the S3 buckets \(Previous step: [Step 9: Get the build output artifact](getting-started-cli-output.md)\) -To prevent ongoing charges to your AWS account, you can delete the input bucket used in this tutorial\. For instructions, see [Deleting or Emptying a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/delete-or-empty-bucket.html) in the *Amazon Simple Storage Service Developer Guide*\. +To prevent ongoing charges to your AWS account, you can delete the input and output buckets used in this tutorial\. For instructions, see [Deleting or Emptying a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/delete-or-empty-bucket.html) in the *Amazon Simple Storage Service User Guide*\. -If you are using the IAM user or an administrator IAM user to delete this bucket, the user must have more access permissions\. Add the following statement between the markers \(*\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to an existing access policy for the user\. +If you are using the IAM user or an administrator IAM user to delete these buckets, the user must have more access permissions\. Add the following statement between the markers \(*\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to an existing access policy for the user\. The ellipses \(\.\.\.\) in this statement are used for brevity\. Do not remove any statements in the existing access policy\. Do not enter these ellipses into the policy\. diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index b988cd7..43a6ab1 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -31,7 +31,7 @@ For this build environment, you instruct CodeBuild to use a Docker image that co }, "environment": { "type": "LINUX_CONTAINER", - "image": "aws/codebuild/amazonlinux2-x86_64-standard:3.0", + "image": "aws/codebuild/standard:4.0", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "serviceIAMRole" @@ -46,8 +46,8 @@ For this build environment, you instruct CodeBuild to use a Docker image that co + For `source`, `location` represents the path to the source code \(in this example, the input bucket name followed by the ZIP file name\)\. + For `artifacts`, `type` is a required value that represents the build output artifact's repository type \(in this example, `S3` for an Amazon S3 bucket\)\. + For `artifacts`, `location` represents the name of the output bucket you created or identified earlier \(in this example, `codebuild-region-ID-account-ID-output-bucket`\)\. - + For `environment`, `type` is a required value that represents the type of build environment \(`LINUX_CONTAINER` is currently the only allowed value\)\. - + For `environment`, `image` is a required value that represents the Docker image name and tag combination this build project uses, as specified by the Docker image repository type \(in this example, `aws/codebuild/standard:4.0` for a Docker image in the CodeBuild Docker images repository\)\. `aws/codebuild/standard` is the name of the Docker image\. `1.0` is the tag of the Docker image\. + + For `environment`, `type` is a required value that represents the type of build environment \(in this example, `LINUX_CONTAINER`\)\. + + For `environment`, `image` is a required value that represents the Docker image name and tag combination this build project uses, as specified by the Docker image repository type \(in this example, `aws/codebuild/standard:4.0` for a Docker image in the CodeBuild Docker images repository\)\. `aws/codebuild/standard` is the name of the Docker image\. `4.0` is the tag of the Docker image\. To find more Docker images you can use in your scenarios, see the [Build environment reference](build-env-ref.md)\. + For `environment`, `computeType` is a required value that represents the computing resources CodeBuild uses \(in this example, `BUILD_GENERAL1_SMALL`\)\. @@ -99,7 +99,7 @@ Other available values in the original JSON\-formatted data, such as `descriptio + `timeoutInMinutes` represents the number of minutes after which CodeBuild stops the build if the build has not been completed\. \(The default is 60 minutes\.\) + `created` represents the time, in Unix time format, when the build project was created\. + `environmentVariables` represents any environment variables that were declared and are available for CodeBuild to use during the build\. - + `encryptionKey` represents the ARN of the AWS KMS customer master key \(CMK\) that CodeBuild used to encrypt the build output artifact\. + + `encryptionKey` represents the ARN of the customer managed key that CodeBuild used to encrypt the build output artifact\. + `arn` represents the ARN of the build project\. **Note** diff --git a/doc_source/getting-started-cli-create-build-spec.md b/doc_source/getting-started-cli-create-build-spec.md index b291c2e..1260cc3 100644 --- a/doc_source/getting-started-cli-create-build-spec.md +++ b/doc_source/getting-started-cli-create-build-spec.md @@ -1,6 +1,6 @@ -# Step 3: Create the buildspec file +# Step 2: Create the buildspec file -\(Previous step: [Step 2: Create the source code](getting-started-cli-create-source-code.md)\) +\(Previous step: [Step 1: Create the source code](getting-started-cli-create-source-code.md)\) In this step, you create a build specification \(build spec\) file\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. Without a build spec, CodeBuild cannot successfully convert your build input into build output or locate the build output artifact in the build environment to upload to your output bucket\. @@ -60,4 +60,4 @@ At this point, your directory structure should look like this\. ## Next step -[Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md) \ No newline at end of file +[Step 3: Create two S3 buckets](getting-started-cli-input-bucket.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-source-code.md b/doc_source/getting-started-cli-create-source-code.md index f03efde..23e9d08 100644 --- a/doc_source/getting-started-cli-create-source-code.md +++ b/doc_source/getting-started-cli-create-source-code.md @@ -1,6 +1,6 @@ -# Step 2: Create the source code +# Step 1: Create the source code -\(Previous step: [Step 1: Create two S3 buckets](getting-started-cli-input-bucket.md)\) +\(Part of: [Getting started with AWS CodeBuild using the AWS CLI](getting-started-cli.md)\) In this step, you create the source code that you want CodeBuild to build to the output bucket\. This source code consists of two Java class files and an Apache Maven Project Object Model \(POM\) file\. @@ -119,4 +119,4 @@ At this point, your directory structure should look like this\. ## Next step -[Step 3: Create the buildspec file](getting-started-cli-create-build-spec.md) \ No newline at end of file +[Step 2: Create the buildspec file](getting-started-cli-create-build-spec.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-input-bucket.md b/doc_source/getting-started-cli-input-bucket.md index 148539c..dc57f3d 100644 --- a/doc_source/getting-started-cli-input-bucket.md +++ b/doc_source/getting-started-cli-input-bucket.md @@ -1,6 +1,6 @@ -# Step 1: Create two S3 buckets +# Step 3: Create two S3 buckets -\(Part of: [Getting started with AWS CodeBuild using the AWS CLI](getting-started-cli.md)\) +\(Previous step: [Step 2: Create the buildspec file](getting-started-cli-create-build-spec.md)\) Although you can use a single bucket for this tutorial, two buckets makes it easier to see where the build input is coming from and where the build output is going\. + One of these buckets \(the *input bucket*\) stores the build input\. In this tutorial, the name of this input bucket is `codebuild-region-ID-account-ID-input-bucket`, where *region\-ID* is the AWS Region of the bucket and *account\-ID* is your AWS account ID\. @@ -17,4 +17,4 @@ Although CodeBuild also supports build input stored in CodeCommit, GitHub, and B ## Next step -[Step 2: Create the source code](getting-started-cli-create-source-code.md) \ No newline at end of file +[Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-monitor-build.md b/doc_source/getting-started-cli-monitor-build.md index c204591..bf3c6ee 100644 --- a/doc_source/getting-started-cli-monitor-build.md +++ b/doc_source/getting-started-cli-monitor-build.md @@ -79,6 +79,9 @@ You can also use the Amazon S3 console to view these hashes\. Select the box nex If you use the AWS SDKs to get these hashes, the values are named `codebuild-content-md5` and `codebuild-content-sha256`\. + `endTime` represents the time, in Unix time format, when the build process ended\. +**Note** +Amazon S3 metadata has a CodeBuild header named `x-amz-meta-codebuild-buildarn` which contains the `buildArn` of the CodeBuild build that publishes artifacts to Amazon S3\. The `buildArn` is added to allow source tracking for notifications and to reference which build the artifact is generated from\. + ## Next step [Step 8: View detailed build information](getting-started-cli-build-log.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-next-steps.md b/doc_source/getting-started-cli-next-steps.md index 355849a..e8f4161 100644 --- a/doc_source/getting-started-cli-next-steps.md +++ b/doc_source/getting-started-cli-next-steps.md @@ -1,5 +1,7 @@ # Wrapping up + + In this tutorial, you used AWS CodeBuild to build a set of Java class files into a JAR file\. You then viewed the build's results\. You can now try using CodeBuild in your own scenarios\. Follow the instructions in [Plan a build](planning.md)\. If you don't feel ready yet, you might want to try building some of the samples\. For more information, see [Samples](samples.md)\. \ No newline at end of file diff --git a/doc_source/getting-started-cli-output.md b/doc_source/getting-started-cli-output.md index ff26f2d..edc86d9 100644 --- a/doc_source/getting-started-cli-output.md +++ b/doc_source/getting-started-cli-output.md @@ -6,6 +6,8 @@ In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and up You can use the CodeBuild console or the Amazon S3 console to complete this step\. + + **To get the build output artifact \(AWS CodeBuild console\)** 1. With the CodeBuild console still open and the build details page still displayed from the previous step, choose the **Build details** tab and scroll down to the **Artifacts** section\. @@ -26,4 +28,4 @@ If the build details page is not displayed, in the navigation bar, choose **Buil ## Next step -[Step 10: Delete the S3 input bucket](getting-started-cli-clean-up.md) \ No newline at end of file +[Step 10: Delete the S3 buckets](getting-started-cli-clean-up.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-upload-source-code.md b/doc_source/getting-started-cli-upload-source-code.md index 0bf1190..adfc66f 100644 --- a/doc_source/getting-started-cli-upload-source-code.md +++ b/doc_source/getting-started-cli-upload-source-code.md @@ -1,6 +1,6 @@ # Step 4: Upload the source code and the buildspec file -\(Previous step: [Step 3: Create the buildspec file](getting-started-cli-create-build-spec.md)\) +\(Previous step: [Step 3: Create two S3 buckets](getting-started-cli-input-bucket.md)\) In this step, you add the source code and build spec file to the input bucket\. diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md index c54b118..81e613e 100644 --- a/doc_source/getting-started-cli.md +++ b/doc_source/getting-started-cli.md @@ -2,20 +2,20 @@ In this tutorial, you use AWS CodeBuild to build a collection of sample source code input files \(called *build input artifacts* or *build input*\) into a deployable version of the source code \(called *build output artifact* or *build output*\)\. Specifically, you instruct CodeBuild to use Apache Maven, a common build tool, to build a set of Java class files into a Java Archive \(JAR\) file\. You do not need to be familiar with Apache Maven or Java to complete this tutorial\. -You can work with CodeBuild through the CodeBuild console, AWS CodePipeline, the AWS CLI, or the AWS SDKs\. This tutorial demonstrates how to use CodeBuild with the AWS CLI\. For information about using CodePipeline, see [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. For information about using the AWS SDKs, see [Run AWS CodeBuild directly](how-to-run.md)\. +You can work with CodeBuild through the CodeBuild console, AWS CodePipeline, the AWS CLI, or the AWS SDKs\. This tutorial demonstrates how to use CodeBuild with the AWS CLI\. For information about using CodePipeline, see [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. For information about using the AWS SDKs, see [Run CodeBuild directly](how-to-run.md)\. **Important** The steps in this tutorial require you to create resources \(for example, an S3 bucket\) that might result in charges to your AWS account\. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, and CloudWatch Logs\. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), and [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing)\. ## Steps -+ [Step 1: Create two S3 buckets](getting-started-cli-input-bucket.md) -+ [Step 2: Create the source code](getting-started-cli-create-source-code.md) -+ [Step 3: Create the buildspec file](getting-started-cli-create-build-spec.md) ++ [Step 1: Create the source code](getting-started-cli-create-source-code.md) ++ [Step 2: Create the buildspec file](getting-started-cli-create-build-spec.md) ++ [Step 3: Create two S3 buckets](getting-started-cli-input-bucket.md) + [Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md) + [Step 5: Create the build project](getting-started-cli-create-build-project.md) + [Step 6: Run the build](getting-started-cli-run-build.md) + [Step 7: View summarized build information](getting-started-cli-monitor-build.md) + [Step 8: View detailed build information](getting-started-cli-build-log.md) + [Step 9: Get the build output artifact](getting-started-cli-output.md) -+ [Step 10: Delete the S3 input bucket](getting-started-cli-clean-up.md) ++ [Step 10: Delete the S3 buckets](getting-started-cli-clean-up.md) + [Wrapping up](getting-started-cli-next-steps.md) \ No newline at end of file diff --git a/doc_source/getting-started-create-build-spec-console.md b/doc_source/getting-started-create-build-spec-console.md index 2015f64..6480b38 100644 --- a/doc_source/getting-started-create-build-spec-console.md +++ b/doc_source/getting-started-create-build-spec-console.md @@ -1,6 +1,6 @@ -# Step 3: Create the buildspec file +# Step 2: Create the buildspec file -\(Previous step: [Step 2: Create the source code](getting-started-create-source-code-console.md)\) +\(Previous step: [Step 1: Create the source code](getting-started-create-source-code-console.md)\) In this step, you create a build specification \(build spec\) file\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. Without a build spec, CodeBuild cannot successfully convert your build input into build output or locate the build output artifact in the build environment to upload to your output bucket\. @@ -60,4 +60,4 @@ At this point, your directory structure should look like this\. ## Next step -[Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md) \ No newline at end of file +[Step 3: Create two S3 buckets](getting-started-input-bucket-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-create-source-code-console.md b/doc_source/getting-started-create-source-code-console.md index d1b4b32..ef4a02d 100644 --- a/doc_source/getting-started-create-source-code-console.md +++ b/doc_source/getting-started-create-source-code-console.md @@ -1,6 +1,6 @@ -# Step 2: Create the source code +# Step 1: Create the source code -\(Previous step: [Step 1: Create two S3 buckets](getting-started-input-bucket-console.md)\) +\(Part of: [Getting started with AWS CodeBuild using the console](getting-started.md)\) In this step, you create the source code that you want CodeBuild to build to the output bucket\. This source code consists of two Java class files and an Apache Maven Project Object Model \(POM\) file\. @@ -119,4 +119,4 @@ At this point, your directory structure should look like this\. ## Next step -[Step 3: Create the buildspec file](getting-started-create-build-spec-console.md) \ No newline at end of file +[Step 2: Create the buildspec file](getting-started-create-build-spec-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-input-bucket-console.md b/doc_source/getting-started-input-bucket-console.md index 7cbe469..64b9f1c 100644 --- a/doc_source/getting-started-input-bucket-console.md +++ b/doc_source/getting-started-input-bucket-console.md @@ -1,6 +1,6 @@ -# Step 1: Create two S3 buckets +# Step 3: Create two S3 buckets -\(Part of: [Getting started with AWS CodeBuild using the console](getting-started.md)\) +\(Previous step: [Step 2: Create the buildspec file](getting-started-create-build-spec-console.md)\) Although you can use a single bucket for this tutorial, two buckets makes it easier to see where the build input is coming from and where the build output is going\. + One of these buckets \(the *input bucket*\) stores the build input\. In this tutorial, the name of this input bucket is `codebuild-region-ID-account-ID-input-bucket`, where *region\-ID* is the AWS Region of the bucket and *account\-ID* is your AWS account ID\. @@ -17,4 +17,4 @@ Although CodeBuild also supports build input stored in CodeCommit, GitHub, and B ## Next step -[Step 2: Create the source code](getting-started-create-source-code-console.md) \ No newline at end of file +[Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-monitor-build-console.md b/doc_source/getting-started-monitor-build-console.md index fea62ff..b97aa70 100644 --- a/doc_source/getting-started-monitor-build-console.md +++ b/doc_source/getting-started-monitor-build-console.md @@ -6,9 +6,9 @@ In this step, you view summarized information about the status of your build\. ## To view summarized build information -1. If the **codebuild\-demo\-project:*build\-ID*** page is not displayed, in the navigation bar, choose **Build history**\. Next, in the list of build projects, for **Project**, choose the **Build run** link for **codebuild\-demo\-project**\. There should be only one matching link\. \(If you have completed this tutorial before, choose the link with the most recent value in the **Completed** column\.\) +1. If the **codebuild\-demo\-project:**** page is not displayed, in the navigation bar, choose **Build history**\. Next, in the list of build projects, for **Project**, choose the **Build run** link for **codebuild\-demo\-project**\. There should be only one matching link\. \(If you have completed this tutorial before, choose the link with the most recent value in the **Completed** column\.\) -1. On the build details page, in **Phase details**, the following build phases should be displayed, with **Succeeded** in the **Status** column: +1. On the **Build status** page, in **Phase details**, the following build phases should be displayed, with **Succeeded** in the **Status** column: + **SUBMITTED** + **QUEUED** + **PROVISIONING** diff --git a/doc_source/getting-started-next-steps-console.md b/doc_source/getting-started-next-steps-console.md index 7d63d3c..192314b 100644 --- a/doc_source/getting-started-next-steps-console.md +++ b/doc_source/getting-started-next-steps-console.md @@ -1,5 +1,7 @@ # Wrapping up + + In this tutorial, you used AWS CodeBuild to build a set of Java class files into a JAR file\. You then viewed the build's results\. You can now try using CodeBuild in your own scenarios\. Follow the instructions in [Plan a build](planning.md)\. If you don't feel ready yet, you might want to try building some of the samples\. For more information, see [Samples](samples.md)\. \ No newline at end of file diff --git a/doc_source/getting-started-output-console.md b/doc_source/getting-started-output-console.md index ceba64d..b92c297 100644 --- a/doc_source/getting-started-output-console.md +++ b/doc_source/getting-started-output-console.md @@ -6,6 +6,8 @@ In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and up You can use the CodeBuild console or the Amazon S3 console to complete this step\. + + **To get the build output artifact \(AWS CodeBuild console\)** 1. With the CodeBuild console still open and the build details page still displayed from the previous step, choose the **Build details** tab and scroll down to the **Artifacts** section\. @@ -26,4 +28,4 @@ If the build details page is not displayed, in the navigation bar, choose **Buil ## Next step -[Step 10: Delete the S3 input bucket](getting-started-clean-up-console.md) \ No newline at end of file +[Step 10: Delete the S3 buckets](getting-started-clean-up-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-run-build-console.md b/doc_source/getting-started-run-build-console.md index f0bdf65..acd11ef 100644 --- a/doc_source/getting-started-run-build-console.md +++ b/doc_source/getting-started-run-build-console.md @@ -10,9 +10,7 @@ In this step, you instruct AWS CodeBuild to run the build with the settings in t 1. In the navigation pane, choose **Build projects**\. -1. In the list of build projects, choose **codebuild\-demo\-project**, and then choose **Start build**\. - -1. On the **Start build** page, choose **Start build**\. +1. In the list of build projects, choose **codebuild\-demo\-project**, and then choose **Start build**\. The build starts immediately\. ## Next step diff --git a/doc_source/getting-started-upload-source-code-console.md b/doc_source/getting-started-upload-source-code-console.md index 31adc7e..e17b19a 100644 --- a/doc_source/getting-started-upload-source-code-console.md +++ b/doc_source/getting-started-upload-source-code-console.md @@ -1,6 +1,6 @@ # Step 4: Upload the source code and the buildspec file -\(Previous step: [Step 3: Create the buildspec file](getting-started-create-build-spec-console.md)\) +\(Previous step: [Step 3: Create two S3 buckets](getting-started-input-bucket-console.md)\) In this step, you add the source code and build spec file to the input bucket\. diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index e87fe5c..8292576 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -2,20 +2,20 @@ In this tutorial, you use AWS CodeBuild to build a collection of sample source code input files \(*build input artifacts* or *build input*\) into a deployable version of the source code \(*build output artifact* or *build output*\)\. Specifically, you instruct CodeBuild to use Apache Maven, a common build tool, to build a set of Java class files into a Java Archive \(JAR\) file\. You do not need to be familiar with Apache Maven or Java to complete this tutorial\. -You can work with CodeBuild through the CodeBuild console, AWS CodePipeline, the AWS CLI, or the AWS SDKs\. This tutorial demonstrates how to use the CodeBuild console\. For information about using CodePipeline, see [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. For information about using the AWS SDKs, see [Run AWS CodeBuild directly](how-to-run.md)\. +You can work with CodeBuild through the CodeBuild console, AWS CodePipeline, the AWS CLI, or the AWS SDKs\. This tutorial demonstrates how to use the CodeBuild console\. For information about using CodePipeline, see [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. For information about using the AWS SDKs, see [Run CodeBuild directly](how-to-run.md)\. **Important** The steps in this tutorial require you to create resources \(for example, an S3 bucket\) that might result in charges to your AWS account\. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, and CloudWatch Logs\. For more information, see [AWS CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), and [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing)\. ## Steps -+ [Step 1: Create two S3 buckets](getting-started-input-bucket-console.md) -+ [Step 2: Create the source code](getting-started-create-source-code-console.md) -+ [Step 3: Create the buildspec file](getting-started-create-build-spec-console.md) ++ [Step 1: Create the source code](getting-started-create-source-code-console.md) ++ [Step 2: Create the buildspec file](getting-started-create-build-spec-console.md) ++ [Step 3: Create two S3 buckets](getting-started-input-bucket-console.md) + [Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md) + [Step 5: Create the build project](getting-started-create-build-project-console.md) + [Step 6: Run the build](getting-started-run-build-console.md) + [Step 7: View summarized build information](getting-started-monitor-build-console.md) + [Step 8: View detailed build information](getting-started-build-log-console.md) + [Step 9: Get the build output artifact](getting-started-output-console.md) -+ [Step 10: Delete the S3 input bucket](getting-started-clean-up-console.md) ++ [Step 10: Delete the S3 buckets](getting-started-clean-up-console.md) + [Wrapping up](getting-started-next-steps-console.md) \ No newline at end of file diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md new file mode 100644 index 0000000..0b47374 --- /dev/null +++ b/doc_source/github-webhook.md @@ -0,0 +1,246 @@ +# GitHub webhook events + +You can use webhook filter groups to specify which GitHub webhook events trigger a build\. For example, you can specify that a build is only triggered for changes to specific branches\. + +You can create one or more webhook filter groups to specify which webhook events trigger a build\. A build is triggered if all the filters on one or more filter groups evaluate to true\. When you create a filter group, you specify: + +**An event** +For GitHub, you can choose one or more of the following events: `PUSH`, `PULL_REQUEST_CREATED`, `PULL_REQUEST_UPDATED`, `PULL_REQUEST_REOPENED`, and `PULL_REQUEST_MERGED`\. The webhook event type is in the `X-GitHub-Event` header in the webhook payload\. In the `X-GitHub-Event` header, you might see `pull_request` or `push`\. For a pull request event, the type is in the `action` field of the webhook event payload\. The following table shows how `X-GitHub-Event` header values and webhook pull request payload `action` field values map to the available event types\. +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/github-webhook.html) + The `PULL_REQUEST_REOPENED` event type can be used with GitHub and GitHub Enterprise Server only\. + +**One or more optional filters** +Use a regular expression to specify a filter\. For an event to trigger a build, every filter associated with it must evaluate to true\. +`ACTOR_ACCOUNT_ID` \(`ACTOR_ID` in the console\) +A webhook event triggers a build when a GitHub or GitHub Enterprise Server account ID matches the regular expression pattern\. This value is found in the `id` property of the `sender` object in the webhook payload\. +`HEAD_REF` +A webhook event triggers a build when the head reference matches the regular expression pattern \(for example, `refs/heads/branch-name` or `refs/tags/tag-name`\)\. For a push event, the reference name is found in the `ref` property in the webhook payload\. For pull requests events, the branch name is found in the `ref` property of the `head` object in the webhook payload\. +`BASE_REF` +A webhook event triggers a build when the base reference matches the regular expression pattern \(for example, `refs/heads/branch-name`\)\. A `BASE_REF` filter can be used with pull request events only\. The branch name is found in the `ref` property of the `base` object in the webhook payload\. +`FILE_PATH` +A webhook triggers a build when the path of a changed file matches the regular expressions pattern\. A `FILE_PATH` filter can be used with GitHub push and pull request events and GitHub Enterprise Server push events\. It cannot be used with GitHub Enterprise Server pull request events\. +`COMMIT_MESSAGE` +A webhook triggers a build when the head commit message matches the regular expression pattern\. A `COMMIT_MESSAGE` filter can be used with GitHub push and pull request events and GitHub Enterprise Server push events\. It cannot be used with GitHub Enterprise Server pull request events\. + +**Note** +You can find the webhook payload in the webhook settings of your GitHub repository\. + +**Topics** ++ [Filter GitHub webhook events \(console\)](#github-webhook-events-console) ++ [Filter GitHub webhook events \(SDK\)](#github-webhook-events-sdk) ++ [Filter GitHub webhook events \(AWS CloudFormation\)](#github-webhook-events-cfn) + +## Filter GitHub webhook events \(console\) + + + +In **Primary source webhook events**, select the following\. This section is only available when you chose **Repository in my GitHub account** for the source repository\. + +1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. + +1. From **Event type**, choose one or more events\. + +1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters\. + +1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters\. + +1. Choose **Add filter group** to add another filter group, if needed\. + + For more information, see [Create a build project \(console\)](create-project-console.md) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. + +In this example, a webhook filter group triggers a build for pull requests only: + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +Using an example of two webhook filter groups, a build is triggered when one or both evaluate to true: ++ The first filter group specifies pull requests that are created, updated, or reopened on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/branch1$`\. ++ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build for all requests except tag events\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build only when a change is made by a specified GitHub or GitHub Enterprise Server user with an account ID that matches the regular expression `actor-account-id`\. + +**Note** + For information about how to find your GitHub account ID, see https://api\.github\.com/users/*user\-name*, where *user\-name* is your GitHub user name\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`\. + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +## Filter GitHub webhook events \(SDK\) + +To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods\. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*\. + + To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" + } + ] +] +``` + + To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names\. Using an example of two filter groups, a build is triggered when one or both evaluate to true: ++ The first filter group specifies pull requests that are created, updated, or reopened on branches with Git reference names that match the regular expression `^refs/heads/main$` and head references that match `^refs/heads/myBranch$`\. ++ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/heads/myBranch$" + }, + { + "type": "BASE_REF", + "pattern": "^refs/heads/main$" + } + ], + [ + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/heads/myBranch$" + } + ] +] +``` + + You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build\. For example, in this example a build is triggered for all requests except tag events\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/tags/.*", + "excludeMatchedPattern": true + } + ] +] +``` + +You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change\. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "FILE_PATH", + "pattern": "^buildspec.*" + } + ] +] +``` + +You can create a filter that triggers a build only when a change is made by a specified GitHub or GitHub Enterprise Server user with account ID `actor-account-id`\. + +**Note** + For information about how to find your GitHub account ID, see https://api\.github\.com/users/*user\-name*, where *user\-name* is your GitHub user name\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" + }, + { + "type": "ACTOR_ACCOUNT_ID", + "pattern": "actor-account-id" + } + ] +] +``` + +You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument\. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`\. + +``` +"filterGroups": [ + [ + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "COMMIT_MESSAGE", + "pattern": "\[CodeBuild\]" + } + ] +] +``` + +## Filter GitHub webhook events \(AWS CloudFormation\) + + To use an AWS CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property\. The following YAML\-formatted portion of an AWS CloudFormation template creates two filter groups\. Together, they trigger a build when one or both evaluate to true: ++ The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/main$` by a GitHub user who does not have account ID `12345`\. ++ The second filter group specifies push requests are created on files with names that match the regular expression `READ_ME` in branches with Git reference names that match the regular expression `^refs/heads/.*`\. ++ The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`\. + +``` +CodeBuildProject: + Type: AWS::CodeBuild::Project + Properties: + Name: MyProject + ServiceRole: service-role + Artifacts: + Type: NO_ARTIFACTS + Environment: + Type: LINUX_CONTAINER + ComputeType: BUILD_GENERAL1_SMALL + Image: aws/codebuild/standard:4.0 + Source: + Type: GITHUB + Location: source-location + Triggers: + Webhook: true + FilterGroups: + - - Type: EVENT + Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED + - Type: BASE_REF + Pattern: ^refs/heads/main$ + ExcludeMatchedPattern: false + - Type: ACTOR_ACCOUNT_ID + Pattern: 12345 + ExcludeMatchedPattern: true + - - Type: EVENT + Pattern: PUSH + - Type: HEAD_REF + Pattern: ^refs/heads/.* + - Type: FILE_PATH + Pattern: READ_ME + ExcludeMatchedPattern: true + - - Type: EVENT + Pattern: PUSH + - Type: COMMIT_MESSAGE + Pattern: \[CodeBuild\] +``` \ No newline at end of file diff --git a/doc_source/history.md b/doc_source/history.md index e0706e2..a402310 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -1,28 +1,43 @@ # AWS CodeBuild User Guide document history The following table describes the important changes to the documentation since the last release of AWS CodeBuild\. For notification about updates to this documentation, you can subscribe to an RSS feed\. -+ **Latest API version:** 2016\-10\-06 -+ **Latest documentation update: **July 20, 2020 ++ **Latest API version:** 2016\-10\-06 ++ **Latest documentation update:** October 4th, 2021 | Change | Description | Date | | --- |--- |--- | +| [Amazon ECR Sample: Restrict image access](#history) | When CodeBuild credentials are used to pull an Amazon ECR image, you can restrict image access to a specific CodeBuild project\. For more information, see [Amazon ECR sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-ecr.html#sample-ecr-running)\. | March 10, 2022 | +| [Added region support](build-env-ref-compute-types.md) | The `ARM_CONTAINER` compute type is now supported in the following additional regions: Asia Pacific \(Seoul\), Canada \(Central\), Europe \(London\), and Europe \(Paris\)\. For more information, see [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html)\. | March 10, 2022 | +| [New VPC limitation](vpc-support.md) | If you configure CodeBuild to work with a VPC, local caching is not supported\. Starting 02/28/22, your VPC build will take longer since a new Amazon EC2 instance will be used for each build\. | February 25, 2022 | +| [Batch report mode](batch-build.md#batch-report-mode) | CodeBuild now allows you to select how batch build statuses are sent to the source provider for a project\. For more information, see [Batch report mode](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html#batch-report-mode)\. | October 4, 2021 | +| [New compute type](build-env-ref-compute-types.md) | CodeBuild now supports a small ARM compute type\. For more information, see [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html)\. | September 13, 2021 | +| [Public build projects](public-builds.md) | CodeBuild now allows you to make the build results for your build projects available to the public without requiring access to an AWS account\. For more information, see [Public build projects](https://docs.aws.amazon.com/codebuild/latest/userguide/public-builds.html)\. | August 11, 2021 | +| [Session debugging for batch builds](#history) | CodeBuild now supports session debugging for batch builds\. For more information, see [build\-graph](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build-buildspec.html#build-spec.batch.build-graph) and [build\-list](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build-buildspec.html#build-spec.batch.build-list)\. | March 3, 2021 | +| [Project level concurrent build limit](#history) | CodeBuild now allows you to limit the number of concurrent builds for a build project\. For more information, see [Project configuration](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project-console.html#create-project-console-project-config) and [concurrentBuildLimit](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project-cli.html#cli.concurrentbuildlimit)\. | February 16, 2021 | +| [New buildspec property: s3‑prefix](#history) | CodeBuild now provides the `s3-prefix` buildspec property for artifacts that allows you to specify a path prefix for artifacts that are uploaded to Amazon S3\. For more information, see [s3\-prefix](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.artifacts.s3-prefix)\. | February 9, 2021 | +| [New buildspec property: on‑failure](#history) | CodeBuild now provides the `on-failure` buildspec property for build phases that allows you to determine what happens when a build phase fails\. For more information, see [on\-failure](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.phases.on-failure)\. | February 9, 2021 | +| [New buildspec property: exclude‑paths](#history) | CodeBuild now provides the `exclude-paths` buildspec property for artifacts that allows you to exclude paths from your build artifacts\. For more information, see [exclude\-paths](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.artifacts.exclude-paths)\. | February 9, 2021 | +| [New buildspec property: enable‑symlinks](#history) | CodeBuild now provides the `enable-symlinks` buildspec property for artifacts that allows you to preserve symbolic links in a ZIP artifact\. For more information, see [enable\-symlinks](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.artifacts.enable-symlinks)\. | February 9, 2021 | +| [Buildspec artifact name enhancement](#history) | CodeBuild now allows the `artifacts/name` property to contain path information\. For more information, see [name](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.artifacts.name)\. | February 9, 2021 | +| [Code coverage reporting](#history) | CodeBuild now provides code coverage reports\. For more information, see [Code coverage reports](https://docs.aws.amazon.com/codebuild/latest/userguide/code-coverage-report.html)\. | July 30, 2020 | +| [Batch builds](#history) | CodeBuild now supports running concurrent and coordinated builds of a project\. For more information, see [Batch builds in CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/batch-build.html)\. | July 30, 2020 | | [Windows Server 2019 image](#history) | CodeBuild now provides a Windows Server Core 2019 build image\. For more information, see [Docker images provided by CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html)\. | July 20, 2020 | -| [Session Manager](#history) | CodeBuild now allows you to pause a running build and then use AWS Systems Manager Session Manager to connect to the build container and view the state of the container\. For more information, see [Session Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/session-manager.html)\. | July 20, 2020 | +| [Session Manager](#history) | CodeBuild now allows you to pause a running build and then use AWS Systems Manager Session Manager to connect to the build container and view the state of the container\. For more information, see [Session Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/session-manager.html)\. | July 20, 2020 | | [Updated topic](#history) | CodeBuild now supports specifying a shell to use in their build environments in the buildspec file\. For more information, see [Build specification reference](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html)\. | June 25, 2020 | -| [Test reporting with test frameworks](#history) | Added several topics the describe how to generate CodeBuild test reports with several test frameworks\. For more information, see [Test reporting with test frameworks](https://docs.aws.amazon.com/codebuild/latest/userguide/test-framework-reporting.html)\. | May 29, 2020 | -| [Updated topics](#history) | CodeBuild now supports adding tags to report groups\. For more information, see [ReportGroup](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ReportGroup.html)\. | May 21, 2020 | +| [Test reporting with test frameworks](#history) | Added several topics the describe how to generate CodeBuild test reports with several test frameworks\. For more information, see [Test reporting with test frameworks](https://docs.aws.amazon.com/codebuild/latest/userguide/test-framework-reporting.html)\. | May 29, 2020 | +| [Updated topics](#history) | CodeBuild now supports adding tags to report groups\. For more information, see [ReportGroup](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ReportGroup.html)\. | May 21, 2020 | | [Support for test reporting](#history) | CodeBuild support for test reporting is now generally available\. | May 21, 2020 | -| [Updated topics](#history) | CodeBuild now supports creating create webhook filters for Github and Bitbucket that trigger builds only when the head commit message matches the specified expression\. For more information, see [GitHub pull request and webhook filter sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-github-pull-request.html) and [Bitbucket pull request and webhook filter sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html)\. | May 6, 2020 | -| [New topics](#history) | CodeBuild now supports sharing build project and report group resources\. For more information, see [Working with shared projects](https://docs.aws.amazon.com/codebuild/latest/userguide/project-sharing.html) and [Working with shared report groups](https://docs.aws.amazon.com/codebuild/latest/userguide/report-groups-sharing.html)\. | December 13, 2019 | -| [New and updated topics](#history) | CodeBuild now supports test reporting during the run of a build project\. For more information, see [Working with test reporting](https://docs.aws.amazon.com/codebuild/latest/userguide/test-reporting.html), [Create a test report](https://docs.aws.amazon.com/codebuild/latest/userguide/report-create.html), and [Create a test report using the AWS CLI sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-test-report-cli.html)\. | November 25, 2019 | -| [Updated topic](#history) | CodeBuild now supports Linux GPU and Arm environment types, and the `2xlarge` compute type\. For more information, see [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html)\. | November 19, 2019 | -| [Updated topics](#history) | CodeBuild now supports build numbers on all builds, exporting environment variables, and AWS Secrets Manager integration\. For more information, see [Exported variables](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#exported-variables-build-spec) and [Secrets Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#secrets-manager-build-spec) in [Buildspec syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | November 6, 2019 | -| [New topic](#history) | CodeBuild now supports notification rules\. You can use notification rules to notify users of important changes in build projects\. For more information, see [Create a notification rule](https://docs.aws.amazon.com/codebuild/latest/userguide/notification-rule-create.html)\. | November 5, 2019 | -| [Updated topics](#history) | CodeBuild now supports the Android version 29 and Go version 1\.13 runtimes\. For more information, see [Docker images provided by CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) and [Buildspec syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | September 10, 2019 | +| [Updated topics](#history) | CodeBuild now supports creating create webhook filters for Github and Bitbucket that trigger builds only when the head commit message matches the specified expression\. For more information, see [GitHub pull request and webhook filter sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-github-pull-request.html) and [Bitbucket pull request and webhook filter sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html)\. | May 6, 2020 | +| [New topics](#history) | CodeBuild now supports sharing build project and report group resources\. For more information, see [Working with shared projects](https://docs.aws.amazon.com/codebuild/latest/userguide/project-sharing.html) and [Working with shared report groups](https://docs.aws.amazon.com/codebuild/latest/userguide/report-groups-sharing.html)\. | December 13, 2019 | +| [New and updated topics](#history) | CodeBuild now supports test reporting during the run of a build project\. For more information, see [Working with test reporting](https://docs.aws.amazon.com/codebuild/latest/userguide/test-reporting.html), [Create a test report](https://docs.aws.amazon.com/codebuild/latest/userguide/report-create.html), and [Create a test report using the AWS CLI sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-test-report-cli.html)\. | November 25, 2019 | +| [Updated topic](#history) | CodeBuild now supports Linux GPU and Arm environment types, and the `2xlarge` compute type\. For more information, see [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html)\. | November 19, 2019 | +| [Updated topics](#history) | CodeBuild now supports build numbers on all builds, exporting environment variables, and AWS Secrets Manager integration\. For more information, see [Exported variables](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#exported-variables-build-spec) and [Secrets Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#secrets-manager-build-spec) in [Buildspec syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | November 6, 2019 | +| [New topic](#history) | CodeBuild now supports notification rules\. You can use notification rules to notify users of important changes in build projects\. For more information, see [Create a notification rule](https://docs.aws.amazon.com/codebuild/latest/userguide/notification-rule-create.html)\. | November 5, 2019 | +| [Updated topics](#history) | CodeBuild now supports the Android version 29 and Go version 1\.13 runtimes\. For more information, see [Docker images provided by CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) and [Buildspec syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | September 10, 2019 | | [Updated topics](#history) | When you create a project, you can now choose the Amazon Linux 2 \(AL2\) managed image\. For more information, see [Docker images provided by CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) and [Runtime versions in buildspec file sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-runtime-versions.html)\. | August 16, 2019 | | [Updated topic](#history) | When you create a project, you can now choose to disable encryption of S3 logs and, if you use a Git\-based source repository, include Git submodules\. For more information, see [Create a build project in CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html)\. | March 8, 2019 | | [New topic](#history) | CodeBuild now supports local caching\. You can specify local caching in one or more of four modes when you create a build\. For more information, see [Build caching in CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/build-caching.html)\. | February 21, 2019 | -| [New topics](#history) | CodeBuild now supports webhook filter groups to specify events that trigger a build\. For more information, see [ Filter GitHub webhook events](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-github-pull-request.html#sample-github-pull-request-filter-webhook-events) and [ Filter Bitbucket webhook events](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html#sample-bitbucket-pull-request-filter-webhook-events)\. | February 8, 2019 | +| [New topics](#history) | CodeBuild now supports webhook filter groups to specify events that trigger a build\. For more information, see [ Filter GitHub webhook events](https://docs.aws.amazon.com/codebuild/latest/userguide/github-webhook.html) and [ Filter Bitbucket webhook events](https://docs.aws.amazon.com/codebuild/latest/userguide/bitbucket-webhook.html)\. | February 8, 2019 | | [New topic](#history) | The CodeBuild User Guide now shows how to use CodeBuild with a proxy server\. For more information, see [Use CodeBuild with a proxy server](https://docs.aws.amazon.com/codebuild/latest/userguide/use-proxy-server.html)\. | February 4, 2019 | | [Updated topics](#history) | CodeBuild now supports using an Amazon ECR image that is in another AWS account\. Several topics have been updated to reflect this change, including [Amazon ECR sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-ecr.html), [Create a build project](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html), and [Create a CodeBuild service role](https://docs.aws.amazon.com/codebuild/latest/userguide/setting-up.html#setting-up-service-role)\. | January 24, 2019 | | [Support for private Docker registries](#history) | CodeBuild now supports using a Docker image that is stored in a private registry as your runtime environment\. For more information, see [Private registry with AWS Secrets Manager sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-private-registry.html)\. | January 24, 2019 | @@ -41,7 +56,7 @@ The following table describes the important changes to the documentation since t | [Support for Amazon CloudWatch metrics and alarms](#history) | CodeBuild now provides integration with CloudWatch metrics and alarms\. You can use the CodeBuild or CloudWatch console to monitor builds at the project and account level\. For more information, see [Monitoring builds](https://docs.aws.amazon.com/codebuild/latest/userguide/monitoring-builds.html)\. | July 19, 2018 | | [Support for reporting a build's status](#history) | CodeBuild can now report the status of a build's start and completion to your source provider\. For more information, see [ Create a build project in CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html)\. | July 10, 2018 | | [Environment variables added to CodeBuild documentation](#history) | The [Environment variables in build environments](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html) page was updated with the CODEBUILD\_BUILD\_ID, CODEBUILD\_LOG\_PATH, and CODEBUILD\_START\_TIME environment variables\. | July 9, 2018 | -| [Support for a finally block in the buildspec file](#history) | The CodeBuild documentation was updated with details about the optional `finally` block in a buildspec file\. Commands in the finally block always execute after the commands in its corresponding commands block\. For more information, see [Buildspec syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | June 20, 2018 | +| [Support for a `finally` block in the buildspec file](#history) | The CodeBuild documentation was updated with details about the optional `finally` block in a buildspec file\. Commands in the finally block always run after the commands in its corresponding commands block\. For more information, see [Buildspec syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | June 20, 2018 | | [CodeBuild agent update notifications](#history) | The CodeBuild documentation was updated with details about how you can use Amazon SNS to be notified when new versions of the CodeBuild agent are released\. For more information, see [Receive notifications for new AWS CodeBuild agent versions](https://docs.aws.amazon.com/codebuild/latest/userguide/use-codebuild-agent.html#receive-codebuild-agent-notifications)\. | June 15, 2018 | ## Earlier updates @@ -51,39 +66,38 @@ The following table describes important changes in each release of the *AWS Code | Change | Description | Date | | --- | --- | --- | -| Support for Windows builds | CodeBuild now supports builds for the Microsoft Windows Server platform, including a prepackaged build environment for the \.NET Core 2\.0 on Windows\. For more information, see [Microsoft Windows samples for CodeBuild](sample-windows.md)\. | May 25, 2018 | -| Support for build idempotency | When you run the start\-build command with the AWS Command Line Interface \(AWS CLI\), you can specify that the build is idempotent\. For more information, see [Run a build \(AWS CLI\)](run-build-cli.md)\. | May 15, 2018 | -| Support for overriding more build project settings | You can now override more build project settings when you create a build\. The overrides are only for that build\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. | May 15, 2018 | -| VPC Endpoint support | You can now use VPC endpoints to improve the security of your builds\. For more information, see [Use VPC endpoints](use-vpc-endpoints-with-codebuild.md)\. | March 18, 2018 | -| Support of triggers | You can now create triggers to schedule builds at regular frequencies\. For more information, see [Create AWS CodeBuild triggers](trigger-create.md)\. | March 28, 2018 | -| FIPS endpoints documentation | You can now learn about how to use the AWS Command Line Interface \(AWS CLI\) or an AWS SDK to tell CodeBuild to use one of four Federal Information Processing Standards \(FIPS\) endpoints\. For more information, see [Specify the AWS CodeBuild endpoint](endpoint-specify.md)\. | March 28, 2018 | -| AWS CodeBuild available in Asia Pacific \(Mumbai\), Europe \(Paris\), and South America \(São Paulo\) | AWS CodeBuild is now available in the Asia Pacific \(Mumbai\), Europe \(Paris\), and South America \(São Paulo\) regions\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | March 28, 2018 | -| GitHub Enterprise Server support | CodeBuild can now build from source code stored in a GitHub Enterprise Server repository\. For more information, see [GitHub Enterprise Server sample](sample-github-enterprise.md)\. | January, 25, 2018 | -| Git clone depth support | CodeBuild now supports the creation of a shallow clone with a history truncated to the specified number of commits\. For more information, see [Create a build project](create-project.md)\. | January, 25, 2018 | -| VPC support | VPC\-enabled builds are now able to access resources inside your VPC\. For more information, see [VPC support](vpc-support.md)\. | November, 27, 2017 | +| Support for Windows builds | CodeBuild now supports builds for the Microsoft Windows Server platform, including a prepackaged build environment for the \.NET Core 2\.0 on Windows\. For more information, see [Microsoft Windows samples for CodeBuild](sample-windows.md) \. | May 25, 2018 | +| Support for build idempotency | When you run the start\-build command with the AWS Command Line Interface \(AWS CLI\), you can specify that the build is idempotent\. For more information, see [Run a build \(AWS CLI\)](run-build-cli.md) \. | May 15, 2018 | +| Support for overriding more build project settings | You can now override more build project settings when you create a build\. The overrides are only for that build\. For more information, see [Run a build in AWS CodeBuild](run-build.md) \. | May 15, 2018 | +| VPC Endpoint support | You can now use VPC endpoints to improve the security of your builds\. For more information, see [Use VPC endpoints](use-vpc-endpoints-with-codebuild.md) \. | March 18, 2018 | +| Support of triggers | You can now create triggers to schedule builds at regular frequencies\. For more information, see [Create AWS CodeBuild triggers](trigger-create.md) \. | March 28, 2018 | +| FIPS endpoints documentation | You can now learn about how to use the AWS Command Line Interface \(AWS CLI\) or an AWS SDK to tell CodeBuild to use one of four Federal Information Processing Standards \(FIPS\) endpoints\. For more information, see [Specify the AWS CodeBuild endpoint](endpoint-specify.md) \. | March 28, 2018 | +| AWS CodeBuild available in Asia Pacific \(Mumbai\), Europe \(Paris\), and South America \(São Paulo\) | AWS CodeBuild is now available in the Asia Pacific \(Mumbai\), Europe \(Paris\), and South America \(São Paulo\) regions\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | March 28, 2018 | +| GitHub Enterprise Server support | CodeBuild can now build from source code stored in a GitHub Enterprise Server repository\. For more information, see [GitHub Enterprise Server sample](sample-github-enterprise.md) \. | January, 25, 2018 | +| Git clone depth support | CodeBuild now supports the creation of a shallow clone with a history truncated to the specified number of commits\. For more information, see [Create a build project](create-project.md) \. | January, 25, 2018 | +| VPC support | VPC\-enabled builds are now able to access resources inside your VPC\. For more information, see [VPC support](vpc-support.md) \. | November, 27, 2017 | | Dependency caching support | CodeBuild now supports the dependency caching\. This allows CodeBuild to save certain reusable pieces of the build environment in the cache and use this across builds\. | November, 27, 2017 | -| Build badges support | CodeBuild now supports the use of build badges, which provide an embeddable, dynamically generated image \(badge\) that displays the status of the latest build for a project\. For more information, see [Build badges sample](sample-build-badges.md)\. | November 27, 2017 | -| AWS Config integration | AWS Config now supports CodeBuild as an AWS resource, which means the service can track your CodeBuild projects\. For more information about AWS Config, see [AWS Config sample](how-to-integrate-config.md)\. | October 20, 2017 | -| Automatically rebuild updated source code in GitHub repositories | If your source code is stored in a GitHub repository, you can enable AWS CodeBuild to rebuild your source code whenever a code change is pushed to the repository\. For more information, see [GitHub pull request and webhook filter sample](sample-github-pull-request.md)\. | September 21, 2017 | -| New ways for storing and retrieving sensitive or large environment variables in Amazon EC2 Systems Manager Parameter Store | You can now use the AWS CodeBuild console or the AWS CLI to retrieve sensitive or large environment variables stored in Amazon EC2 Systems Manager Parameter Store\. You can also now use the AWS CodeBuild console to store these types of environment variables in Amazon EC2 Systems Manager Parameter Store\. Previously, you could only retrieve these types of environment variables by including them in a buildspec or by running build commands to automate the AWS CLI\. You could only store these types of environment variables by using the Amazon EC2 Systems Manager Parameter Store console\. For more information, see [Create a build project](create-project.md), [Change a build project's settings](change-project.md), and [Run a build](run-build.md)\. | September 14, 2017 | -| Build deletion support | You can now delete builds in AWS CodeBuild\. For more information, see [Delete builds](delete-builds.md)\. | August 31, 2017 | -| Updated way to retrieve sensitive or large environment variables stored in Amazon EC2 Systems Manager Parameter Store by using a buildspec | AWS CodeBuild now makes it easier to use a buildspec to retrieve sensitive or large environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Previously, you could only retrieve these types of environment variables by running build commands to automate the AWS CLI\. For more information, see the parameter\-store mapping in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. | August 10, 2017 | -| AWS CodeBuild supports Bitbucket | CodeBuild can now build from source code stored in a Bitbucket repository\. For more information, see [Create a build project](create-project.md) and [Run a build](run-build.md)\. | August 10, 2017 | -| AWS CodeBuild available in US West \(N\. California\), Europe \(London\), and Canada \(Central\) | AWS CodeBuild is now available in the US West \(N\. California\), Europe \(London\), and Canada \(Central\) regions\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | June 29, 2017 | -| Alternate buildspec file names and locations supported | You can now specify an alternate file name or location of a buildspec file to use for a build project, instead of a default buildspec file named buildspec\.yml at the root of the source code\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. | June 27, 2017 | +| Build badges support | CodeBuild now supports the use of build badges, which provide an embeddable, dynamically generated image \(badge\) that displays the status of the latest build for a project\. For more information, see [Build badges sample](sample-build-badges.md) \. | November 27, 2017 | +| AWS Config integration | AWS Config now supports CodeBuild as an AWS resource, which means the service can track your CodeBuild projects\. For more information about AWS Config, see [AWS Config sample](how-to-integrate-config.md) \. | October 20, 2017 | +| Automatically rebuild updated source code in GitHub repositories | If your source code is stored in a GitHub repository, you can enable AWS CodeBuild to rebuild your source code whenever a code change is pushed to the repository\. For more information, see [GitHub pull request and webhook filter sample](sample-github-pull-request.md) \. | September 21, 2017 | +| New ways for storing and retrieving sensitive or large environment variables in Amazon EC2 Systems Manager Parameter Store | You can now use the AWS CodeBuild console or the AWS CLI to retrieve sensitive or large environment variables stored in Amazon EC2 Systems Manager Parameter Store\. You can also now use the AWS CodeBuild console to store these types of environment variables in Amazon EC2 Systems Manager Parameter Store\. Previously, you could only retrieve these types of environment variables by including them in a buildspec or by running build commands to automate the AWS CLI\. You could only store these types of environment variables by using the Amazon EC2 Systems Manager Parameter Store console\. For more information, see [Create a build project](create-project.md) , [Change a build project's settings](change-project.md) , and [Run a build](run-build.md) \. | September 14, 2017 | +| Build deletion support | You can now delete builds in AWS CodeBuild\. For more information, see [Delete builds](delete-builds.md) \. | August 31, 2017 | +| Updated way to retrieve sensitive or large environment variables stored in Amazon EC2 Systems Manager Parameter Store by using a buildspec | AWS CodeBuild now makes it easier to use a buildspec to retrieve sensitive or large environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Previously, you could only retrieve these types of environment variables by running build commands to automate the AWS CLI\. For more information, see the parameter\-store mapping in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax) \. | August 10, 2017 | +| AWS CodeBuild supports Bitbucket | CodeBuild can now build from source code stored in a Bitbucket repository\. For more information, see [Create a build project](create-project.md) and [Run a build](run-build.md) \. | August 10, 2017 | +| AWS CodeBuild available in US West \(N\. California\), Europe \(London\), and Canada \(Central\) | AWS CodeBuild is now available in the US West \(N\. California\), Europe \(London\), and Canada \(Central\) regions\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | June 29, 2017 | +| Alternate buildspec file names and locations supported | You can now specify an alternate file name or location of a buildspec file to use for a build project, instead of a default buildspec file named buildspec\.yml at the root of the source code\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage) \. | June 27, 2017 | | Updated build notifications sample | CodeBuild now provides built\-in support for build notifications through Amazon CloudWatch Events and Amazon Simple Notification Service \(Amazon SNS\)\. The previous [Build notifications sample](sample-build-notifications.md) has been updated to demonstrate this new behavior\. | June 22, 2017 | -| Docker in custom image sample added | A sample showing how to use CodeBuild and a custom Docker build image to build and run a Docker image has been added\. For more information, see the [Docker in custom image sample](sample-docker-custom-image.md)\. | June 7, 2017 | -| Fetch source code for GitHub pull requests | When you run a build with CodeBuild that relies on source code stored in a GitHub repository, you can now specify a GitHub pull request ID to build\. You can also specify a commit ID, a branch name, or a tag name instead\. For more information, see the **Source version** value in [Run a build \(console\)](run-build-console.md) or the `sourceVersion` value in [Run a build \(AWS CLI\)](run-build-cli.md)\. | June 6, 2017 | -| Build specification version updated | A new version of the buildspec format has been released\. Version 0\.2 addresses the issue of CodeBuild running each build command in a separate instance of the default shell\. Also in version 0\.2, environment\_variables is renamed to env, and plaintext is renamed to variables\. For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. | May 9, 2017 | -| Dockerfiles for build images available in GitHub | Definitions for many of the build images provided by AWS CodeBuild are available as Dockerfiles in GitHub\. For more information, see the Definition column of the table in [Docker images provided by CodeBuild](build-env-ref-available.md)\. | May 2, 2017 | -| AWS CodeBuild available in Europe \(Frankfurt\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), and Asia Pacific \(Tokyo\) | AWS CodeBuild is now available in the Europe \(Frankfurt\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), and Asia Pacific \(Tokyo\) regions\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | March 21, 2017 | -| CodePipeline test action support for CodeBuild | You can now add to a pipeline in CodePipeline a test action that uses CodeBuild\. For more information, see [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](how-to-create-pipeline.md#how-to-create-pipeline-add-test)\. | March 8, 2017 | -| Buildspec files support fetching build output from within selected top\-level directories | Buildspec files now enable you to specify individual top\-level directories whose contents you can instruct CodeBuild to include in build output artifacts\. You do this by using the base\-directory mapping\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. | February 8, 2017 | -| Built\-in environment variables | AWS CodeBuild provides additional built\-in environment variables for your builds to use\. These include environment variables describing the entity that started the build, the URL to the source code repository, the source code's version ID, and more\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. | January 30, 2017 | -| AWS CodeBuild available in US East \(Ohio\) | AWS CodeBuild is now available in the US East \(Ohio\) region\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | January 19, 2017 | -| AWS Lambda sample | A reference was added to a sample showing how to use CodeBuild along with Lambda, AWS CloudFormation, and CodePipeline to build and deploy a serverless application that follows the AWS Serverless Application Model \(AWS SAM\) standard\. For more information, see the [AWS Lambda sample](sample-lambda.md)\. | December 20, 2016 | -| Shell and command behaviors information | CodeBuild runs each command you specify in a separate instance of a build environment's default shell\. This default behavior can produce some unexpected side effects for your commands\. We recommend some approaches to work around this default behavior if needed\. For more information, see [Shells and commands in build environments](build-env-ref-cmd.md)\. | December 9, 2016 | -| Environment variables information | CodeBuild provides several environment variables that you can use in your build commands\. You can also define your own environment variables\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. | December 7, 2016 | -| Troubleshooting topic | Troubleshooting information is now available\. For more information, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. | December 5, 2016 | -| Jenkins plugin initial release | This is the initial release of the CodeBuild Jenkins plugin\. For more information, see [Use AWS CodeBuild with Jenkins](jenkins-plugin.md)\. | December 5, 2016 | -| User Guide initial release | This is the initial release of the CodeBuild User Guide\. | December 1, 2016 | \ No newline at end of file +| Docker in custom image sample added | A sample showing how to use CodeBuild and a custom Docker build image to build and run a Docker image has been added\. For more information, see the [Docker in custom image sample](sample-docker-custom-image.md) \. | June 7, 2017 | +| Fetch source code for GitHub pull requests | When you run a build with CodeBuild that relies on source code stored in a GitHub repository, you can now specify a GitHub pull request ID to build\. You can also specify a commit ID, a branch name, or a tag name instead\. For more information, see the **Source version** value in [Run a build \(console\)](run-build-console.md) or the `sourceVersion` value in [Run a build \(AWS CLI\)](run-build-cli.md) \. | June 6, 2017 | +| Build specification version updated | A new version of the buildspec format has been released\. Version 0\.2 addresses the issue of CodeBuild running each build command in a separate instance of the default shell\. Also in version 0\.2, environment\_variables is renamed to env, and plaintext is renamed to variables\. For more information, see [Build specification reference for CodeBuild](build-spec-ref.md) \. | May 9, 2017 | +| Dockerfiles for build images available in GitHub | Definitions for many of the build images provided by AWS CodeBuild are available as Dockerfiles in GitHub\. For more information, see the Definition column of the table in [Docker images provided by CodeBuild](build-env-ref-available.md) \. | May 2, 2017 | +| AWS CodeBuild available in Europe \(Frankfurt\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), and Asia Pacific \(Tokyo\) | AWS CodeBuild is now available in the Europe \(Frankfurt\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), and Asia Pacific \(Tokyo\) regions\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | March 21, 2017 | +| CodePipeline test action support for CodeBuild | You can now add to a pipeline in CodePipeline a test action that uses CodeBuild\. For more information, see [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](how-to-create-pipeline-add-test.md) \. | March 8, 2017 | +| Buildspec files support fetching build output from within selected top\-level directories | Buildspec files now enable you to specify individual top\-level directories whose contents you can instruct CodeBuild to include in build output artifacts\. You do this by using the base\-directory mapping\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax) \. | February 8, 2017 | +| Built\-in environment variables | AWS CodeBuild provides additional built\-in environment variables for your builds to use\. These include environment variables describing the entity that started the build, the URL to the source code repository, the source code's version ID, and more\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md) \. | January 30, 2017 | +| AWS CodeBuild available in US East \(Ohio\) | AWS CodeBuild is now available in the US East \(Ohio\) region\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the Amazon Web Services General Reference\. | January 19, 2017 | +| Shell and command behaviors information | CodeBuild runs each command you specify in a separate instance of a build environment's default shell\. This default behavior can produce some unexpected side effects for your commands\. We recommend some approaches to work around this default behavior if needed\. For more information, see [Shells and commands in build environments](build-env-ref-cmd.md) \. | December 9, 2016 | +| Environment variables information | CodeBuild provides several environment variables that you can use in your build commands\. You can also define your own environment variables\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md) \. | December 7, 2016 | +| Troubleshooting topic | Troubleshooting information is now available\. For more information, see [Troubleshooting AWS CodeBuild](troubleshooting.md) \. | December 5, 2016 | +| Jenkins plugin initial release | This is the initial release of the CodeBuild Jenkins plugin\. For more information, see [Use AWS CodeBuild with Jenkins](jenkins-plugin.md) \. | December 5, 2016 | +| User Guide initial release | This is the initial release of the CodeBuild User Guide\. | December 1, 2016 | \ No newline at end of file diff --git a/doc_source/how-to-create-pipeline-add-test.md b/doc_source/how-to-create-pipeline-add-test.md new file mode 100644 index 0000000..9acb71e --- /dev/null +++ b/doc_source/how-to-create-pipeline-add-test.md @@ -0,0 +1,84 @@ +# Add a CodeBuild test action to a pipeline \(CodePipeline console\) + +1. Sign in to the AWS Management Console by using: + + Your AWS root account\. This is not recommended\. For more information, see [The account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. + + An administrator IAM user in your AWS account\. For more information, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. + + An IAM user in your AWS account with permission to perform the following minimum set of actions: + + ``` + codepipeline:* + iam:ListRoles + iam:PassRole + s3:CreateBucket + s3:GetBucketPolicy + s3:GetObject + s3:ListAllMyBuckets + s3:ListBucket + s3:PutBucketPolicy + codecommit:ListBranches + codecommit:ListRepositories + codedeploy:GetApplication + codedeploy:GetDeploymentGroup + codedeploy:ListApplications + codedeploy:ListDeploymentGroups + elasticbeanstalk:DescribeApplications + elasticbeanstalk:DescribeEnvironments + lambda:GetFunctionConfiguration + lambda:ListFunctions + opsworks:DescribeStacks + opsworks:DescribeApps + opsworks:DescribeLayers + ``` + +1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. + +1. In the AWS region selector, choose the AWS Region where your pipeline is located\. This must be an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. + +1. On the **Pipelines** page, choose the name of the pipeline\. + +1. On the pipeline details page, in the **Source** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyApp**\)\. +**Note** +This procedure shows you how to add a test action inside of a test stage between the **Source** and **Beta** stages\. If you want to add the test action somewhere else, rest your mouse pointer on the action just before, and make a note of the value for **Output artifact**\. + +1. Choose **Edit**\. + +1. Immediately after the **Source** stage, choose **Add stage**\. +**Note** +This procedure shows you how to add a test stage immediately after the **Source** stage to your pipeline\. To add a test action to an existing stage, choose **Edit stage** in the stage, and then skip to step 8 of this procedure\. To add the test stage somewhere else, choose **Add stage** in the desired place\. +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + + +1. For **Stage name**, enter the name of the test stage \(for example, **Test**\)\. If you choose a different name, use it throughout this procedure\. + +1. In the selected stage, choose **Add action**\. +**Note** +This procedure shows you how to add the test action in a test stage\. To add the test action somewhere else, choose **Add action** in the desired place\. You might first need to choose **Edit** in the existing stage where you want to add the test action\. + +1. In **Edit action**, for **Action name**, enter a name for the action \(for example, **Test**\)\. If you choose a different name, use it throughout this procedure\. + +1. For **Action provider**, under **Test**, choose **CodeBuild**\. + +1. If you already have a build project you want to use, for **Project name**, choose the name of the build project and skip to the next step in this procedure\. + + If you need to create a new CodeBuild build project, follow the instructions in [Create a build project \(console\)](create-project-console.md) and return to this procedure\. +**Important** +If you enable webhooks for a CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit\. One build is triggered through webhooks and one through CodePipeline\. Because billing is on a per\-build basis, you are billed for both builds\. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild\. In the CodeBuild console, clear the **Webhook**box\. For more information, see [Change a build project's settings \(console\)](change-project-console.md) + +1. For **Input artifacts**, select the value for **Output artifact** that you noted earlier in this procedure\. + +1. \(Optional\) If you want your test action to produce an output artifact, and you set up your buildspec accordingly, then for **Output artifact**, enter the value you want to assign to the output artifact\. + +1. Choose **Save**\. + +1. Choose **Release change**\. + +1. After the pipeline runs successfully, you can get the test results\. In the **Test** stage of the pipeline, choose the **CodeBuild** hyperlink to open the related build project page in the CodeBuild console\. + + + +1. On the build project page, in **Build history**, choose the **Build run** hyperlink\. + +1. On the build run page, in **Build logs**, choose the **View entire log** hyperlink to open the build log in the Amazon CloudWatch console\. + +1. Scroll through the build log to view the test results\. \ No newline at end of file diff --git a/doc_source/how-to-create-pipeline-add.md b/doc_source/how-to-create-pipeline-add.md new file mode 100644 index 0000000..1624ed7 --- /dev/null +++ b/doc_source/how-to-create-pipeline-add.md @@ -0,0 +1,100 @@ +# Add a CodeBuild build action to a pipeline \(CodePipeline console\) + +1. Sign in to the AWS Management Console by using: + + Your AWS root account\. This is not recommended\. For more information, see [The account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. + + An administrator IAM user in your AWS account\. For more information, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. + + An IAM user in your AWS account with permission to perform the following minimum set of actions: + + ``` + codepipeline:* + iam:ListRoles + iam:PassRole + s3:CreateBucket + s3:GetBucketPolicy + s3:GetObject + s3:ListAllMyBuckets + s3:ListBucket + s3:PutBucketPolicy + codecommit:ListBranches + codecommit:ListRepositories + codedeploy:GetApplication + codedeploy:GetDeploymentGroup + codedeploy:ListApplications + codedeploy:ListDeploymentGroups + elasticbeanstalk:DescribeApplications + elasticbeanstalk:DescribeEnvironments + lambda:GetFunctionConfiguration + lambda:ListFunctions + opsworks:DescribeStacks + opsworks:DescribeApps + opsworks:DescribeLayers + ``` + +1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. + +1. In the AWS region selector, choose the AWS Region where your pipeline is located\. This must be a Region where CodeBuild is supported\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. + +1. On the **Pipelines** page, choose the name of the pipeline\. + +1. On the pipeline details page, in the **Source** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyApp**\)\. +**Note** +This procedure shows you how to add a build action in a build stage between the **Source** and **Beta** stages\. If you want to add the build action somewhere else, choose the tooltip on the action just before the place where you want to add the build action, and make a note of the value for **Output artifact**\. + +1. Choose **Edit**\. + +1. Between the **Source** and **Beta** stages, choose **Add stage**\. +**Note** +This procedure shows you how to add a build stage between the **Source** and **Beta** stages to your pipeline\. To add a build action to an existing stage, choose **Edit stage** in the stage, and then skip to step 8 of this procedure\. To add the build stage somewhere else, choose **Add stage** in the desired place\. + + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + + +1. For **Stage name**, enter the name of the build stage \(for example, **Build**\)\. If you choose a different name, use it throughout this procedure\. + +1. Inside of the selected stage, choose **Add action**\. +**Note** +This procedure shows you how to add the build action inside of a build stage\. To add the build action somewhere else, choose **Add action** in the desired place\. You might first need to choose **Edit stage** in the existing stage where you want to add the build action\. + +1. In **Edit action**, for **Action name**, enter a name for the action \(for example, **CodeBuild**\)\. If you choose a different name, use it throughout this procedure\. + +1. For **Action provider**, choose **CodeBuild**\. + +1. If you already have a build project you want to use, for **Project name**, choose the name of the build project and skip to the next step in this procedure\. + + If you need to create a new CodeBuild build project, follow the instructions in [Create a build project \(console\)](create-project-console.md) and return to this procedure\. + + If you choose an existing build project, it must have build output artifact settings already defined \(even though CodePipeline overrides them\)\. For more information, see the description of **Artifacts** in [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project-console.md)\. +**Important** +If you enable webhooks for a CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit\. One build is triggered through webhooks and one through CodePipeline\. Because billing is on a per\-build basis, you are billed for both builds\. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild\. In the CodeBuild console, clear the **Webhook** box\. For more information, see [Change a build project's settings \(console\)](change-project-console.md) + +1. For **Input artifacts**, choose the output artifact that you noted earlier in this procedure\. + +1. For **Output artifacts**, enter a name for the output artifact \(for example, **MyAppBuild**\)\. + +1. Choose **Add action**\. + +1. Choose **Save**, and then choose **Save** to save your changes to the pipeline\. + +1. Choose **Release change**\. + +1. After the pipeline runs successfully, you can get the build output artifact\. With the pipeline displayed in the CodePipeline console, in the **Build** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyAppBuild**\)\. +**Note** +You can also get the build output artifact by choosing the **Build artifacts** link on the build details page in the CodeBuild console\. To get to this page, see [View build details \(console\)](view-build-details.md#view-build-details-console), and then skip to step 31 of this procedure\. + +1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. + +1. In the list of buckets, open the bucket used by the pipeline\. The name of the bucket should follow the format `codepipeline-region-ID-random-number`\. You can use the AWS CLI to run the CodePipeline get\-pipeline command to get the name of the bucket: + + ``` + aws codepipeline get-pipeline --name my-pipeline-name + ``` + + In the output, the `pipeline` object contains an `artifactStore` object, which contains a `location` value with the name of the bucket\. + +1. Open the folder that matches the name of your pipeline \(depending on the length of the pipeline's name, the folder name might be truncated\), and then open the folder matching the value for **Output artifact** that you noted earlier in this procedure\. + +1. Extract the contents of the file\. If there are multiple files in that folder, extract the contents of the file with the latest **Last Modified** timestamp\. \(You might need to give the file the `.zip` extension so that you can work with it in your system's ZIP utility\.\) The build output artifact is in the extracted contents of the file\. + +1. If you instructed CodePipeline to deploy the build output artifact, use the deployment provider's instructions to get to the build output artifact on the deployment targets\. \ No newline at end of file diff --git a/doc_source/how-to-create-pipeline-cli.md b/doc_source/how-to-create-pipeline-cli.md new file mode 100644 index 0000000..6e2909d --- /dev/null +++ b/doc_source/how-to-create-pipeline-cli.md @@ -0,0 +1,150 @@ +# Create a pipeline that uses CodeBuild \(AWS CLI\) + +Use the following procedure to create a pipeline that uses CodeBuild to build your source code\. + +To use the AWS CLI to create a pipeline that deploys your built source code or that only tests your source code, you can adapt the instructions in [Edit a pipeline \(AWS CLI\)](https://docs.aws.amazon.com/codepipeline/latest/userguide/how-to-edit-pipelines.html#how-to-edit-pipelines-cli) and the [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *AWS CodePipeline User Guide*\. + +1. Create or identify a build project in CodeBuild\. For more information, see [Create a build project](create-project.md)\. +**Important** +The build project must define build output artifact settings \(even though CodePipeline overrides them\)\. For more information, see the description of `artifacts` in [Create a build project \(AWS CLI\)](create-project-cli.md)\. + +1. Make sure you have configured the AWS CLI with the AWS access key and AWS secret access key that correspond to one of the IAM entities described in this topic\. For more information, see [Getting set up with the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*\. + +1. Create a JSON\-formatted file that represents the structure of the pipeline\. Name the file `create-pipeline.json` or similar\. For example, this JSON\-formatted structure creates a pipeline with a source action that references an S3 input bucket and a build action that uses CodeBuild: + + ``` + { + "pipeline": { + "roleArn": "arn:aws:iam:::role/", + "stages": [ + { + "name": "Source", + "actions": [ + { + "inputArtifacts": [], + "name": "Source", + "actionTypeId": { + "category": "Source", + "owner": "AWS", + "version": "1", + "provider": "S3" + }, + "outputArtifacts": [ + { + "name": "MyApp" + } + ], + "configuration": { + "S3Bucket": "", + "S3ObjectKey": "" + }, + "runOrder": 1 + } + ] + }, + { + "name": "Build", + "actions": [ + { + "inputArtifacts": [ + { + "name": "MyApp" + } + ], + "name": "Build", + "actionTypeId": { + "category": "Build", + "owner": "AWS", + "version": "1", + "provider": "CodeBuild" + }, + "outputArtifacts": [ + { + "name": "default" + } + ], + "configuration": { + "ProjectName": "" + }, + "runOrder": 1 + } + ] + } + ], + "artifactStore": { + "type": "S3", + "location": "" + }, + "name": "", + "version": 1 + } + } + ``` + + In this JSON\-formatted data: + + The value of `roleArn` must match the ARN of the CodePipeline service role you created or identified as part of the prerequisites\. + + The values of `S3Bucket` and `S3ObjectKey` in `configuration` assume the source code is stored in an S3 bucket\. For settings for other source code repository types, see the [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *AWS CodePipeline User Guide*\. + + The value of `ProjectName` is the name of the CodeBuild build project you created earlier in this procedure\. + + The value of `location` is the name of the S3 bucket used by this pipeline\. For more information, see [Create a policy for an S3 Bucket to use as the artifact store for CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/access-permissions.html#how-to-create-bucket-policy) in the *AWS CodePipeline User Guide*\. + + The value of `name` is the name of this pipeline\. All pipeline names must be unique to your account\. + + Although this data describes only a source action and a build action, you can add actions for activities related to testing, deploying the build output artifact, invoking AWS Lambda functions, and more\. For more information, see the [AWS CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *AWS CodePipeline User Guide*\. + +1. Switch to the folder that contains the JSON file, and then run the CodePipeline [create\-pipeline](https://docs.aws.amazon.com/cli/latest/reference/codepipeline/create-pipeline.html) command, specifying the file name: + + ``` + aws codepipeline create-pipeline --cli-input-json file://create-pipeline.json + ``` +**Note** +You must create the pipeline in an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. + + The JSON\-formatted data appears in the output, and CodePipeline creates the pipeline\. + +1. To get information about the pipeline's status, run the CodePipeline [get\-pipeline\-state](https://docs.aws.amazon.com/cli/latest/reference/codepipeline/get-pipeline-state.html) command, specifying the name of the pipeline: + + ``` + aws codepipeline get-pipeline-state --name + ``` + + In the output, look for information that confirms the build was successful\. Ellipses \(`...`\) are used to show data that has been omitted for brevity\. + + ``` + { + ... + "stageStates": [ + ... + { + "actionStates": [ + { + "actionName": "CodeBuild", + "latestExecution": { + "status": "SUCCEEDED", + ... + }, + ... + } + ] + } + ] + } + ``` + + If you run this command too early, you might not see any information about the build action\. You might need to run this command multiple times until the pipeline has finished running the build action\. + +1. After a successful build, follow these instructions to get the build output artifact\. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. +**Note** +You can also get the build output artifact by choosing the **Build artifacts** link on the related build details page in the CodeBuild console\. To get to this page, skip the rest of the steps in this procedure, and see [View build details \(console\)](view-build-details.md#view-build-details-console)\. + +1. In the list of buckets, open the bucket used by the pipeline\. The name of the bucket should follow the format `codepipeline--`\. You can get the bucket name from the `create-pipeline.json` file or you can run the CodePipeline get\-pipeline command to get the bucket's name\. + + ``` + aws codepipeline get-pipeline --name + ``` + + In the output, the `pipeline` object contains an `artifactStore` object, which contains a `location` value with the name of the bucket\. + +1. Open the folder that matches the name of your pipeline \(for example, ``\)\. + +1. In that folder, open the folder named `default`\. + +1. Extract the contents of the file\. If there are multiple files in that folder, extract the contents of the file with the latest **Last Modified** timestamp\. \(You might need to give the file a `.zip` extension so that you can work with it in your system's ZIP utility\.\) The build output artifact is in the extracted contents of the file\. \ No newline at end of file diff --git a/doc_source/how-to-create-pipeline-console.md b/doc_source/how-to-create-pipeline-console.md new file mode 100644 index 0000000..2e3d869 --- /dev/null +++ b/doc_source/how-to-create-pipeline-console.md @@ -0,0 +1,106 @@ +# Create a pipeline that uses CodeBuild \(CodePipeline console\) + +Use the following procedure to create a pipeline that uses CodeBuild to build and deploy your source code\. + +To create a pipeline that only tests your source code: ++ Use the following procedure to create the pipeline, and then delete the Build and Beta stages from the pipeline\. Then use the [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](how-to-create-pipeline-add-test.md) procedure in this topic to add to the pipeline a test action that uses CodeBuild\. ++ Use one of the other procedures in this topic to create the pipeline, and then use the [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](how-to-create-pipeline-add-test.md) procedure in this topic to add to the pipeline a test action that uses CodeBuild\. + +**To use the create pipeline wizard in CodePipeline to create a pipeline that uses CodeBuild** + +1. Sign in to the AWS Management Console by using: + + Your AWS root account\. This is not recommended\. For more information, see [The account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. + + An administrator IAM user in your AWS account\. For more information, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. + + An IAM user in your AWS account with permission to use the following minimum set of actions: + + ``` + codepipeline:* + iam:ListRoles + iam:PassRole + s3:CreateBucket + s3:GetBucketPolicy + s3:GetObject + s3:ListAllMyBuckets + s3:ListBucket + s3:PutBucketPolicy + codecommit:ListBranches + codecommit:ListRepositories + codedeploy:GetApplication + codedeploy:GetDeploymentGroup + codedeploy:ListApplications + codedeploy:ListDeploymentGroups + elasticbeanstalk:DescribeApplications + elasticbeanstalk:DescribeEnvironments + lambda:GetFunctionConfiguration + lambda:ListFunctions + opsworks:DescribeStacks + opsworks:DescribeApps + opsworks:DescribeLayers + ``` + +1. Open the AWS CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. + +1. In the AWS Region selector, choose the AWS Region where your build project AWS resources are located\. This must be an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. + +1. Create a pipeline\. If a CodePipeline information page is displayed, choose **Create pipeline**\. If a **Pipelines** page is displayed, choose **Create pipeline**\. + +1. On the **Step 1: Choose pipeline settings** page, for **Pipeline name**, enter a name for the pipeline \(for example, **CodeBuildDemoPipeline**\)\. If you choose a different name, be sure to use it throughout this procedure\. + +1. For **Role name**, do one of the following: + + Choose **New service role**, and in **Role Name**, enter the name for your new service role\. + + Choose **Existing service role**, and then choose the CodePipeline service role you created or identified as part of this topic's prerequisites\. + +1. For **Artifact store**, do one of the following: + + Choose **Default location** to use the default artifact store, such as the S3 artifact bucket designated as the default, for your pipeline in the AWS Region you have selected for your pipeline\. + + Choose **Custom location** if you already have an existing artifact store you have created, such as an S3 artifact bucket, in the same AWS Region as your pipeline\. +**Note** +This is not the source bucket for your pipeline's source code\. This is the artifact store for your pipeline\. A separate artifact store, such as an S3 bucket, is required for each pipeline, in the same AWS Region as the pipeline\. + +1. Choose **Next**\. + +1. On the **Step 2: Add source stage** page, for **Source provider**, do one of the following: + + If your source code is stored in an S3 bucket, choose **Amazon S3**\. For **Bucket**, select the S3 bucket that contains your source code\. For **S3 object key**, enter the name of the file the contains the source code \(for example, `file-name.zip`\)\. Choose **Next**\. + + If your source code is stored in an AWS CodeCommit repository, choose **CodeCommit**\. For **Repository name**, choose the name of the repository that contains the source code\. For **Branch name**, choose the name of the branch that contains the version of the source code you want to build\. Choose **Next**\. + + If your source code is stored in a GitHub repository, choose **GitHub**\. Choose **Connect to GitHub**, and follow the instructions to authenticate with GitHub\. For **Repository**, choose the name of the repository that contains the source code\. For **Branch**, choose the name of the branch that contains the version of the source code you want to build\. + + Choose **Next**\. + +1. On the **Step 3: Add build stage** page, for **Build provider**, choose **CodeBuild**\. + +1. If you already have a build project you want to use, for **Project name**, choose the name of the build project and skip to the next step in this procedure\. + + If you need to create a new CodeBuild build project, follow the instructions in [Create a build project \(console\)](create-project-console.md) and return to this procedure\. + + If you choose an existing build project, it must have build output artifact settings already defined \(even though CodePipeline overrides them\)\. For more information, see [Change a build project's settings \(console\)](change-project-console.md)\. +**Important** +If you enable webhooks for a CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit\. One build is triggered through webhooks, and one through CodePipeline\. Because billing is on a per\-build basis, you are billed for both builds\. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild\. In the AWS CodeBuild console, clear the **Webhook** box\. For more information, see [Change a build project's settings \(console\)](change-project-console.md)\. + +1. On the **Step 4: Add deploy stage** page, do one of the following: + + If you do not want to deploy the build output artifact, choose **Skip**, and confirm this choice when prompted\. + + If you want to deploy the build output artifact, for **Deploy provider**, choose a deployment provider, and then specify the settings when prompted\. + + Choose **Next**\. + +1. On the ** Review** page, review your choices, and then choose **Create pipeline**\. + +1. After the pipeline runs successfully, you can get the build output artifact\. With the pipeline displayed in the CodePipeline console, in the **Build** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyAppBuild**\)\. +**Note** +You can also get the build output artifact by choosing the **Build artifacts** link on the build details page in the CodeBuild console\. To get to this page, skip the rest of the steps in this procedure, and see [View build details \(console\)](view-build-details.md#view-build-details-console)\. + +1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. + +1. In the list of buckets, open the bucket used by the pipeline\. The name of the bucket should follow the format `codepipeline-region-ID-random-number`\. You can use the AWS CLI to run the CodePipeline get\-pipeline command to get the name of the bucket, where *my\-pipeline\-name* is the display name of your pipeline: + + ``` + aws codepipeline get-pipeline --name my-pipeline-name + ``` + + In the output, the `pipeline` object contains an `artifactStore` object, which contains a `location` value with the name of the bucket\. + +1. Open the folder that matches the name of your pipeline \(depending on the length of the pipeline's name, the folder name might be truncated\), and then open the folder that matches the value for **Output artifact** that you noted earlier\. + +1. Extract the contents of the file\. If there are multiple files in that folder, extract the contents of the file with the latest **Last Modified** timestamp\. \(You might need to give the file the `.zip` extension so that you can work with it in your system's ZIP utility\.\) The build output artifact is in the extracted contents of the file\. + +1. If you instructed CodePipeline to deploy the build output artifact, use the deployment provider's instructions to get to the build output artifact on the deployment targets\. \ No newline at end of file diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 529cfa2..0efa474 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -1,4 +1,4 @@ -# Use CodePipeline with AWS CodeBuild to test code and run builds +# Use AWS CodePipeline with AWS CodeBuild to test code and run builds You can automate your release process by using AWS CodePipeline to test your code and run your builds with AWS CodeBuild\. @@ -12,13 +12,6 @@ The following table lists tasks and the methods available for performing them\. | Create a continuous delivery \(CD\) pipeline with CodePipeline that automates builds with CodeBuild | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/how-to-create-pipeline.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/how-to-create-pipeline.html) | | Add test and build automation with CodeBuild to an existing pipeline in CodePipeline | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/how-to-create-pipeline.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/how-to-create-pipeline.html) | -**Topics** -+ [Prerequisites](#how-to-create-pipeline-prerequisites) -+ [Create a pipeline that uses CodeBuild \(CodePipeline console\)](#how-to-create-pipeline-console) -+ [Create a pipeline that uses CodeBuild \(AWS CLI\)](#how-to-create-pipeline-cli) -+ [Add a CodeBuild build action to a pipeline \(CodePipeline console\)](#how-to-create-pipeline-add) -+ [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](#how-to-create-pipeline-add-test) - ## Prerequisites 1. Answer the questions in [Plan a build](planning.md)\. @@ -47,529 +40,16 @@ The IAM entity that creates this CodePipeline service role must have permission **Note** The IAM entity that adds this CodePipeline service role policy must have permission in IAM to add service role policies to service roles\. -1. Create and upload the source code to a repository type supported by CodeBuild and CodePipeline, such as CodeCommit, Amazon S3, or GitHub\. \(CodePipeline does not currently support Bitbucket\.\) The source code should contain a buildspec file, but you can declare one when you define a build project later in this topic\. For more information, see the [Buildspec reference](build-spec-ref.md)\. +1. Create and upload the source code to a repository type supported by CodeBuild and CodePipeline, such as CodeCommit, Amazon S3, Bitbucket, or GitHub\. The source code should contain a buildspec file, but you can declare one when you define a build project later in this topic\. For more information, see the [Buildspec reference](build-spec-ref.md)\. **Important** If you plan to use the pipeline to deploy built source code, the build output artifact must be compatible with the deployment system you use\. For CodeDeploy, see the [AWS CodeDeploy sample](sample-codedeploy.md) in this guide and [Prepare a revision for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-revision.html) in the *AWS CodeDeploy User Guide*\. For AWS Elastic Beanstalk, see the [AWS Elastic Beanstalk sample](sample-elastic-beanstalk.md) in this guide and [Create an application source bundle](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.deployment.source.html) in the *AWS Elastic Beanstalk Developer Guide*\. For AWS OpsWorks, see [Application source](https://docs.aws.amazon.com/opsworks/latest/userguide/workingapps-creating.html#workingapps-creating-source) and [Using CodePipeline with AWS OpsWorks](https://docs.aws.amazon.com/opsworks/latest/userguide/other-services-cp.html) in the *AWS OpsWorks User Guide*\. -## Create a pipeline that uses CodeBuild \(CodePipeline console\) - -Use the following procedure to create a pipeline that uses CodeBuild to build and deploy your source code\. - -To create a pipeline that only tests your source code: -+ Use the following procedure to create the pipeline, and then delete the Build and Beta stages from the pipeline\. Then use the [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](#how-to-create-pipeline-add-test) procedure in this topic to add to the pipeline a test action that uses CodeBuild\. -+ Use one of the other procedures in this topic to create the pipeline, and then use the [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](#how-to-create-pipeline-add-test) procedure in this topic to add to the pipeline a test action that uses CodeBuild\. - -**To use the create pipeline wizard in CodePipeline to create a pipeline that uses CodeBuild** - -1. Sign in to the AWS Management Console by using: - + Your AWS root account\. This is not recommended\. For more information, see [The account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. - + An administrator IAM user in your AWS account\. For more information, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. - + An IAM user in your AWS account with permission to use the following minimum set of actions: - - ``` - codepipeline:* - iam:ListRoles - iam:PassRole - s3:CreateBucket - s3:GetBucketPolicy - s3:GetObject - s3:ListAllMyBuckets - s3:ListBucket - s3:PutBucketPolicy - codecommit:ListBranches - codecommit:ListRepositories - codedeploy:GetApplication - codedeploy:GetDeploymentGroup - codedeploy:ListApplications - codedeploy:ListDeploymentGroups - elasticbeanstalk:DescribeApplications - elasticbeanstalk:DescribeEnvironments - lambda:GetFunctionConfiguration - lambda:ListFunctions - opsworks:DescribeStacks - opsworks:DescribeApps - opsworks:DescribeLayers - ``` - -1. Open the AWS CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. - -1. In the AWS Region selector, choose the AWS Region where your build project AWS resources are located\. This must be an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. - -1. Create a pipeline\. If a CodePipeline information page is displayed, choose **Create pipeline**\. If a **Pipelines** page is displayed, choose **Create pipeline**\. - -1. On the **Step 1: Choose pipeline settings** page, for **Pipeline name**, enter a name for the pipeline \(for example, **CodeBuildDemoPipeline**\)\. If you choose a different name, be sure to use it throughout this procedure\. - -1. For **Role name**, do one of the following: - - Choose **New service role**, and in **Role Name**, enter the name for your new service role\. - - Choose **Existing service role**, and then choose the CodePipeline service role you created or identified as part of this topic's prerequisites\. - -1. For **Artifact store**, do one of the following: - + Choose **Default location** to use the default artifact store, such as the S3 artifact bucket designated as the default, for your pipeline in the AWS Region you have selected for your pipeline\. - + Choose **Custom location** if you already have an existing artifact store you have created, such as an S3 artifact bucket, in the same AWS Region as your pipeline\. -**Note** -This is not the source bucket for your pipeline's source code\. This is the artifact store for your pipeline\. A separate artifact store, such as an S3 bucket, is required for each pipeline, in the same AWS Region as the pipeline\. - -1. Choose **Next**\. - -1. On the **Step 2: Add source stage** page, for **Source provider**, do one of the following: - + If your source code is stored in an S3 bucket, choose **Amazon S3**\. For **Bucket**, select the S3 bucket that contains your source code\. For **S3 object key**, enter the name of the file the contains the source code \(for example, `file-name.zip`\)\. Choose **Next**\. - + If your source code is stored in an AWS CodeCommit repository, choose **CodeCommit**\. For **Repository name**, choose the name of the repository that contains the source code\. For **Branch name**, choose the name of the branch that contains the version of the source code you want to build\. Choose **Next**\. - + If your source code is stored in a GitHub repository, choose **GitHub**\. Choose **Connect to GitHub**, and follow the instructions to authenticate with GitHub\. For **Repository**, choose the name of the repository that contains the source code\. For **Branch**, choose the name of the branch that contains the version of the source code you want to build\. - - Choose **Next**\. - -1. On the **Step 3: Add build stage** page, for **Build provider**, choose **CodeBuild**\. - -1. If you already have a build project you want to use, for **Project name**, choose the name of the build project and skip ahead to step 22 in this procedure\. Otherwise, use the following steps to create a project in CodeBuild\. - - If you choose an existing build project, it must have build output artifact settings already defined \(even though CodePipeline overrides them\)\. For more information, see [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. -**Important** -If you enable webhooks for a CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit\. One build is triggered through webhooks, and one through CodePipeline\. Because billing is on a per\-build basis, you are billed for both builds\. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild\. In the AWS CodeBuild console, clear the **Webhook** box\. For more information, see [Change a build project's settings \(console\)](change-project.md#change-project-console)\. - -1. On the **Step 4: Add deploy stage** page, do one of the following: - + If you do not want to deploy the build output artifact, choose **Skip**, and confirm this choice when prompted\. - + If you want to deploy the build output artifact, for **Deploy provider**, choose a deployment provider, and then specify the settings when prompted\. - - Choose **Next**\. - -1. On the ** Review** page, review your choices, and then choose **Create pipeline**\. - -1. After the pipeline runs successfully, you can get the build output artifact\. With the pipeline displayed in the CodePipeline console, in the **Build** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyAppBuild**\)\. -**Note** -You can also get the build output artifact by choosing the **Build artifacts** link on the build details page in the CodeBuild console\. To get to this page, skip the rest of the steps in this procedure, and see [View build details \(console\)](view-build-details.md#view-build-details-console)\. - -1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. - -1. In the list of buckets, open the bucket used by the pipeline\. The name of the bucket should follow the format `codepipeline-region-ID-random-number`\. You can use the AWS CLI to run the CodePipeline get\-pipeline command to get the name of the bucket, where *my\-pipeline\-name* is the display name of your pipeline: - - ``` - aws codepipeline get-pipeline --name my-pipeline-name - ``` - - In the output, the `pipeline` object contains an `artifactStore` object, which contains a `location` value with the name of the bucket\. - -1. Open the folder that matches the name of your pipeline \(depending on the length of the pipeline's name, the folder name might be truncated\), and then open the folder that matches the value for **Output artifact** that you noted earlier\. - -1. Extract the contents of the file\. If there are multiple files in that folder, extract the contents of the file with the latest **Last Modified** timestamp\. \(You might need to give the file the `.zip` extension so that you can work with it in your system's ZIP utility\.\) The build output artifact is in the extracted contents of the file\. - -1. If you instructed CodePipeline to deploy the build output artifact, use the deployment provider's instructions to get to the build output artifact on the deployment targets\. - -## Create a pipeline that uses CodeBuild \(AWS CLI\) - -Use the following procedure to create a pipeline that uses CodeBuild to build your source code\. - -To use the AWS CLI to create a pipeline that deploys your built source code or that only tests your source code, you can adapt the instructions in [Edit a pipeline \(AWS CLI\)](https://docs.aws.amazon.com/codepipeline/latest/userguide/how-to-edit-pipelines.html#how-to-edit-pipelines-cli) and the [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *AWS CodePipeline User Guide*\. - -1. Create or identify a build project in CodeBuild\. For more information, see [Create a build project](create-project.md)\. -**Important** -The build project must define build output artifact settings \(even though CodePipeline overrides them\)\. For more information, see the description of `artifacts` in [Create a build project \(AWS CLI\)](create-project-cli.md)\. - -1. Make sure you have configured the AWS CLI with the AWS access key and AWS secret access key that correspond to one of the IAM entities described in this topic\. For more information, see [Getting set up with the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html) in the *AWS Command Line Interface User Guide*\. - -1. Create a JSON\-formatted file that represents the structure of the pipeline\. Name the file `create-pipeline.json` or similar\. For example, this JSON\-formatted structure creates a pipeline with a source action that references an S3 input bucket and a build action that uses CodeBuild: - - ``` - { - "pipeline": { - "roleArn": "arn:aws:iam::account-id:role/my-AWS-CodePipeline-service-role-name", - "stages": [ - { - "name": "Source", - "actions": [ - { - "inputArtifacts": [], - "name": "Source", - "actionTypeId": { - "category": "Source", - "owner": "AWS", - "version": "1", - "provider": "S3" - }, - "outputArtifacts": [ - { - "name": "MyApp" - } - ], - "configuration": { - "S3Bucket": "my-input-bucket-name", - "S3ObjectKey": "my-source-code-file-name.zip" - }, - "runOrder": 1 - } - ] - }, - { - "name": "Build", - "actions": [ - { - "inputArtifacts": [ - { - "name": "MyApp" - } - ], - "name": "Build", - "actionTypeId": { - "category": "Build", - "owner": "AWS", - "version": "1", - "provider": "CodeBuild" - }, - "outputArtifacts": [ - { - "name": "default" - } - ], - "configuration": { - "ProjectName": "my-build-project-name" - }, - "runOrder": 1 - } - ] - } - ], - "artifactStore": { - "type": "S3", - "location": "AWS-CodePipeline-internal-bucket-name" - }, - "name": "my-pipeline-name", - "version": 1 - } - } - ``` - - In this JSON\-formatted data: - + The value of `roleArn` must match the ARN of the CodePipeline service role you created or identified as part of the prerequisites\. - + The values of `S3Bucket` and `S3ObjectKey` in `configuration` assume the source code is stored in an S3 bucket\. For settings for other source code repository types, see the [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *AWS CodePipeline User Guide*\. - + The value of `ProjectName` is the name of the CodeBuild build project you created earlier in this procedure\. - + The value of `location` is the name of the S3 bucket used by this pipeline\. For more information, see [Create a policy for an S3 Bucket to use as the artifact store for CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/access-permissions.html#how-to-create-bucket-policy) in the *AWS CodePipeline User Guide*\. - + The value of `name` is the name of this pipeline\. All pipeline names must be unique to your account\. - - Although this data describes only a source action and a build action, you can add actions for activities related to testing, deploying the build output artifact, invoking AWS Lambda functions, and more\. For more information, see the [AWS CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *AWS CodePipeline User Guide*\. - -1. Switch to the folder that contains the JSON file, and then run the CodePipeline [create\-pipeline](https://docs.aws.amazon.com/cli/latest/reference/codepipeline/create-pipeline.html) command, specifying the file name: - - ``` - aws codepipeline create-pipeline --cli-input-json file://create-pipeline.json - ``` -**Note** -You must create the pipeline in an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. - - The JSON\-formatted data appears in the output, and CodePipeline creates the pipeline\. - -1. To get information about the pipeline's status, run the CodePipeline [get\-pipeline\-state](https://docs.aws.amazon.com/cli/latest/reference/codepipeline/get-pipeline-state.html) command, specifying the name of the pipeline: - - ``` - aws codepipeline get-pipeline-state --name my-pipeline-name - ``` - - In the output, look for information that confirms the build was successful\. Ellipses \(`...`\) are used to show data that has been omitted for brevity\. - - ``` - { - ... - "stageStates": [ - ... - { - "actionStates": [ - { - "actionName": "CodeBuild", - "latestExecution": { - "status": "SUCCEEDED", - ... - }, - ... - } - ] - } - ] - } - ``` - - If you run this command too early, you might not see any information about the build action\. You might need to run this command multiple times until the pipeline has finished running the build action\. - -1. After a successful build, follow these instructions to get the build output artifact\. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. -**Note** -You can also get the build output artifact by choosing the **Build artifacts** link on the related build details page in the CodeBuild console\. To get to this page, skip the rest of the steps in this procedure, and see [View build details \(console\)](view-build-details.md#view-build-details-console)\. - -1. In the list of buckets, open the bucket used by the pipeline\. The name of the bucket should follow the format `codepipeline-region-ID-random-number`\. You can get the bucket name from the `create-pipeline.json` file or you can run the CodePipeline get\-pipeline command to get the bucket's name\. - - ``` - aws codepipeline get-pipeline --name my-pipeline-name - ``` - - In the output, the `pipeline` object contains an `artifactStore` object, which contains a `location` value with the name of the bucket\. - -1. Open the folder that matches the name of your pipeline \(for example, `my-pipeline-name`\)\. - -1. In that folder, open the folder named `default`\. - -1. Extract the contents of the file\. If there are multiple files in that folder, extract the contents of the file with the latest **Last Modified** timestamp\. \(You might need to give the file a `.zip` extension so that you can work with it in your system's ZIP utility\.\) The build output artifact is in the extracted contents of the file\. - -## Add a CodeBuild build action to a pipeline \(CodePipeline console\) - -1. Sign in to the AWS Management Console by using: - + Your AWS root account\. This is not recommended\. For more information, see [The account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. - + An administrator IAM user in your AWS account\. For more information, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. - + An IAM user in your AWS account with permission to perform the following minimum set of actions: - - ``` - codepipeline:* - iam:ListRoles - iam:PassRole - s3:CreateBucket - s3:GetBucketPolicy - s3:GetObject - s3:ListAllMyBuckets - s3:ListBucket - s3:PutBucketPolicy - codecommit:ListBranches - codecommit:ListRepositories - codedeploy:GetApplication - codedeploy:GetDeploymentGroup - codedeploy:ListApplications - codedeploy:ListDeploymentGroups - elasticbeanstalk:DescribeApplications - elasticbeanstalk:DescribeEnvironments - lambda:GetFunctionConfiguration - lambda:ListFunctions - opsworks:DescribeStacks - opsworks:DescribeApps - opsworks:DescribeLayers - ``` - -1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. - -1. In the AWS region selector, choose the AWS Region where your pipeline is located\. This must be a Region where CodeBuild is supported\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. - -1. On the **Pipelines** page, choose the name of the pipeline\. - -1. On the pipeline details page, in the **Source** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyApp**\)\. -**Note** -This procedure shows you how to add a build action in a build stage between the **Source** and **Beta** stages\. If you want to add the build action somewhere else, choose the tooltip on the action just before the place where you want to add the build action, and make a note of the value for **Output artifact**\. - -1. Choose **Edit**\. - -1. Between the **Source** and **Beta** stages, choose **Add stage**\. -**Note** -This procedure shows you how to add a build stage between the **Source** and **Beta** stages to your pipeline\. To add a build action to an existing stage, choose **Edit stage** in the stage, and then skip to step 8 of this procedure\. To add the build stage somewhere else, choose **Add stage** in the desired place\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. For **Stage name**, enter the name of the build stage \(for example, **Build**\)\. If you choose a different name, use it throughout this procedure\. - -1. Inside of the selected stage, choose **Add action**\. -**Note** -This procedure shows you how to add the build action inside of a build stage\. To add the build action somewhere else, choose **Add action** in the desired place\. You might first need to choose **Edit stage** in the existing stage where you want to add the build action\. - -1. In **Edit action**, for **Action name**, enter a name for the action \(for example, **CodeBuild**\)\. If you choose a different name, use it throughout this procedure\. - -1. For **Action provider**, choose **CodeBuild**\. - -1. If you already have a build project in CodeBuild, for **Project name**, choose the name of the build project, and then skip to step 22 of this procedure\. - - If you choose an existing build project, it must have build output artifact settings already defined \(even though CodePipeline overrides them\)\. For more information, see the description of **Artifacts** in [Create a build project \(console\)](create-project-console.md) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. -**Important** -If you enable webhooks for a CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit\. One build is triggered through webhooks and one through CodePipeline\. Because billing is on a per\-build basis, you are billed for both builds\. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild\. In the CodeBuild console, clear the **Webhook** box\. For more information, see [Change a build project's settings \(console\)](change-project.md#change-project-console) - -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. - -1. For **Project name**, enter a name for this build project\. Build project names must be unique across each AWS account\. - -1. \(Optional\) Enter a description\. - -1. For **Environment**, do one of the following: - + To use a build environment based on a Docker image that is managed by CodeBuild, choose **Managed image**\. Make your selections from the **Operating system**, **Runtime**, and **Runtime version** drop\-down lists\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - + To use a build environment based on a Docker image in an Amazon ECR repository in your AWS account, choose **Custom image**\. For **Environment type**, choose an environment type, and then choose **Amazon ECR**\. Use the **Amazon ECR repository** and **Amazon ECR image** drop\-down lists to choose the Amazon ECR repository and Docker image in that repository\. - + To use a build environment based on a publicly available Docker image in Docker Hub, choose **Other location**\. In **Other location**, enter the Docker image ID, using the format `docker repository/docker-image-name`\. - - Select **Privileged** only if you plan to use this build project to build Docker images, and the build environment image you chose is not one provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it as needed\. You can do this by running the following build commands to initialize the Docker daemon in the `install` phase of your buildspec\. \(Do not run the following build commands if you chose a build environment image provided by CodeBuild with Docker support\.\) - - ``` - - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay& - - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" - ``` - -1. In **Service role**, do one of the following: - + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. -**Note** -When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. - -1. Expand **Additional configuration**\. - - To specify a build timeout other than 60 minutes \(the default\), use the **hours** and **minutes** boxes to set a timeout between 5 and 480 minutes \(8 hours\)\. - - For **Compute**, choose one of the available options\. - - For **Environment variables**, use **Name** and **Value** to specify any optional environment variables for the build environment to use\. To add more environment variables, choose **Add environment variable**\. -**Important** -We strongly discourage storing sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text in the CodeBuild console and AWS CLI\. -To store and retrieve sensitive values, we recommend your build commands use the AWS CLI to interact with the Amazon EC2 Systems Manager Parameter Store\. The AWS CLI is already installed and configured on all build environments provided by CodeBuild\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store CLI Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-cli) in the *Amazon EC2 Systems Manager User Guide* - -1. For **Buildspec**, do one of the following: - + If your source code includes a buildspec file, choose **Use a buildspec file**\. - + If your source code does not include a buildspec file, choose **Insert build commands**\. For **Build commands**, enter the commands you want to run during the build phase in the build environment\. For multiple commands, separate each command with `&&` for Linux\-based build environments or `;` for Windows\-based build environments\. For **Output files**, enter the paths to the build output files in the build environment that you want to send to CodePipeline\. For multiple files, separate each file path with a comma\. - -1. Choose **Create build project**\. - -1. Return to the CodePipeline console\. - -1. For **Input artifacts**, choose the output artifact that you noted earlier in this procedure\. - -1. For **Output artifacts**, enter a name for the output artifact \(for example, **MyAppBuild**\)\. - -1. Choose **Add action**\. - -1. Choose **Save**, and then choose **Save** to save your changes to the pipeline\. - -1. Choose **Release change**\. - -1. After the pipeline runs successfully, you can get the build output artifact\. With the pipeline displayed in the CodePipeline console, in the **Build** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyAppBuild**\)\. -**Note** -You can also get the build output artifact by choosing the **Build artifacts** link on the build details page in the CodeBuild console\. To get to this page, see [View build details \(console\)](view-build-details.md#view-build-details-console), and then skip to step 31 of this procedure\. - -1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. - -1. In the list of buckets, open the bucket used by the pipeline\. The name of the bucket should follow the format `codepipeline-region-ID-random-number`\. You can use the AWS CLI to run the CodePipeline get\-pipeline command to get the name of the bucket: - - ``` - aws codepipeline get-pipeline --name my-pipeline-name - ``` - - In the output, the `pipeline` object contains an `artifactStore` object, which contains a `location` value with the name of the bucket\. - -1. Open the folder that matches the name of your pipeline \(depending on the length of the pipeline's name, the folder name might be truncated\), and then open the folder matching the value for **Output artifact** that you noted earlier in this procedure\. - -1. Extract the contents of the file\. If there are multiple files in that folder, extract the contents of the file with the latest **Last Modified** timestamp\. \(You might need to give the file the `.zip` extension so that you can work with it in your system's ZIP utility\.\) The build output artifact is in the extracted contents of the file\. - -1. If you instructed CodePipeline to deploy the build output artifact, use the deployment provider's instructions to get to the build output artifact on the deployment targets\. - -## Add a CodeBuild test action to a pipeline \(CodePipeline console\) - -1. Sign in to the AWS Management Console by using: - + Your AWS root account\. This is not recommended\. For more information, see [The account root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. - + An administrator IAM user in your AWS account\. For more information, see [Creating your first IAM admin user and group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. - + An IAM user in your AWS account with permission to perform the following minimum set of actions: - - ``` - codepipeline:* - iam:ListRoles - iam:PassRole - s3:CreateBucket - s3:GetBucketPolicy - s3:GetObject - s3:ListAllMyBuckets - s3:ListBucket - s3:PutBucketPolicy - codecommit:ListBranches - codecommit:ListRepositories - codedeploy:GetApplication - codedeploy:GetDeploymentGroup - codedeploy:ListApplications - codedeploy:ListDeploymentGroups - elasticbeanstalk:DescribeApplications - elasticbeanstalk:DescribeEnvironments - lambda:GetFunctionConfiguration - lambda:ListFunctions - opsworks:DescribeStacks - opsworks:DescribeApps - opsworks:DescribeLayers - ``` - -1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. - -1. In the AWS region selector, choose the AWS Region where your pipeline is located\. This must be an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. - -1. On the **Pipelines** page, choose the name of the pipeline\. - -1. On the pipeline details page, in the **Source** action, choose the tooltip\. Make a note of the value for **Output artifact** \(for example, **MyApp**\)\. -**Note** -This procedure shows you how to add a test action inside of a test stage between the **Source** and **Beta** stages\. If you want to add the test action somewhere else, rest your mouse pointer on the action just before, and make a note of the value for **Output artifact**\. - -1. Choose **Edit**\. - -1. Immediately after the **Source** stage, choose **Add stage**\. -**Note** -This procedure shows you how to add a test stage immediately after the **Source** stage to your pipeline\. To add a test action to an existing stage, choose **Edit stage** in the stage, and then skip to step 8 of this procedure\. To add the test stage somewhere else, choose **Add stage** in the desired place\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. For **Stage name**, enter the name of the test stage \(for example, **Test**\)\. If you choose a different name, use it throughout this procedure\. - -1. In the selected stage, choose **Add action**\. -**Note** -This procedure shows you how to add the test action in a test stage\. To add the test action somewhere else, choose **Add action** in the desired place\. You might first need to choose **Edit** in the existing stage where you want to add the test action\. - -1. In **Edit action**, for **Action name**, enter a name for the action \(for example, **Test**\)\. If you choose a different name, use it throughout this procedure\. - -1. For **Action provider**, under **Test**, choose **CodeBuild**\. - -1. If you already have a build project in CodeBuild, for **Project name**, choose the name of the build project, and then skip to step 22 of this procedure\. -**Important** -If you enable webhooks for a CodeBuild project, and the project is used as a build step in CodePipeline, then two identical builds are created for each commit\. One build is triggered through webhooks and one through CodePipeline\. Because billing is on a per\-build basis, you are billed for both builds\. Therefore, if you are using CodePipeline, we recommend that you disable webhooks in CodeBuild\. In the CodeBuild console, clear the **Webhook**box\. For more information, see [Change a build project's settings \(console\)](change-project.md#change-project-console) - -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. - -1. For **Project name**, enter a name for this build project\. Build project names must be unique across each AWS account\. - -1. \(Optional\) Enter a description\. - -1. For **Environment**, do one of the following: - + To use a build environment based on a Docker image that is managed by CodeBuild, choose **Managed image**\. Make your selections from the **Operating system**, **Runtime**, and **Runtime version** drop\-down lists\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - + To use a build environment based on a Docker image in an Amazon ECR repository in your AWS account, choose **Custom image**\. For **Environment type**, choose an environment type, and then choose **Amazon ECR**\. Use the **Amazon ECR repository** and **Amazon ECR image** drop\-down lists to choose the Amazon ECR repository and Docker image in that repository\. - + To use a build environment based on a publicly available Docker image in Docker Hub, choose **Other location**\. In **Other location**, enter the Docker image ID, using the format `docker repository/docker-image-name`\. - - Select **Privileged** only if you plan to use this build project to build Docker images, and the build environment image you chose is not one provided by CodeBuild with Docker support\. Otherwise, all associated builds that attempt to interact with the Docker daemon fail\. You must also start the Docker daemon so that your builds can interact with it as needed\. You can do this by running the following build commands to initialize the Docker daemon in the `install` phase of your buildspec\. \(Do not run the following build commands if you chose a build environment image provided by CodeBuild with Docker support\.\) - - ``` - - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay& - - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" - ``` - -1. In **Service role**, do one of the following: - + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. -**Note** -When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. - -1. Expand **Additional configuration**\. - - To specify a build timeout other than 60 minutes \(the default\), use the **hours** and **minutes** boxes to set a timeout between 5 and 480 minutes \(8 hours\)\. - - For **Compute**, choose one of the available options\. - - For **Environment variables**, use **Name** and **Value** to specify any optional environment variables for the build environment to use\. To add more environment variables, choose **Add environment variable**\. -**Important** -We strongly discourage storing sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text in the CodeBuild console and AWS CLI\. -To store and retrieve sensitive values, we recommend your build commands use the AWS CLI to interact with the Amazon EC2 Systems Manager Parameter Store\. The AWS CLI is already installed and configured on all build environments provided by CodeBuild\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store CLI Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-cli) in the *Amazon EC2 Systems Manager User Guide* - -1. For **Buildspec**, do one of the following: - + If your source code includes a buildspec file, choose **Use a buildspec file**\. - + If your source code does not include a buildspec file, choose **Insert build commands**\. For **Build commands**, enter the commands you want to run during the build phase in the build environment\. For multiple commands, separate each command with `&&` for Linux\-based build environments or `;` for Windows\-based build environments\. For **Output files**, enter the paths to the build output files in the build environment that you want to send to CodePipeline\. For multiple files, separate each file path with a comma\. - -1. Choose **Create build project**\. - -1. Return to the CodePipeline console\. - -1. For **Input artifacts**, select the value for **Output artifact** that you noted earlier in this procedure\. - -1. \(Optional\) If you want your test action to produce an output artifact, and you set up your buildspec accordingly, then for **Output artifact**, enter the value you want to assign to the output artifact\. - -1. Choose **Save**\. - -1. Choose **Release change**\. - -1. After the pipeline runs successfully, you can get the test results\. In the **Test** stage of the pipeline, choose the **CodeBuild** hyperlink to open the related build project page in the CodeBuild console\. - -1. On the build project page, in **Build history**, choose the **Build run** hyperlink\. - -1. On the build run page, in **Build logs**, choose the **View entire log** hyperlink to open the build log in the Amazon CloudWatch console\. - -1. Scroll through the build log to view the test results\. \ No newline at end of file +**Topics** ++ [Prerequisites](#how-to-create-pipeline-prerequisites) ++ [Create a pipeline that uses CodeBuild \(CodePipeline console\)](how-to-create-pipeline-console.md) ++ [Create a pipeline that uses CodeBuild \(AWS CLI\)](how-to-create-pipeline-cli.md) ++ [Add a CodeBuild build action to a pipeline \(CodePipeline console\)](how-to-create-pipeline-add.md) ++ [Add a CodeBuild test action to a pipeline \(CodePipeline console\)](how-to-create-pipeline-add-test.md) \ No newline at end of file diff --git a/doc_source/how-to-integrate-config.md b/doc_source/how-to-integrate-config.md index 1468894..a321a2b 100644 --- a/doc_source/how-to-integrate-config.md +++ b/doc_source/how-to-integrate-config.md @@ -31,8 +31,7 @@ After you complete setup, it might take up to 10 minutes before you can see AWS 1. Sign in to the AWS Management Console and open the AWS Config console at [https://console\.aws\.amazon\.com/config](https://console.aws.amazon.com/config)\. -1. On the **Resource inventory** page, choose **Resources**\. Scroll down and select the **CodeBuild project** check box\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/config-select-project.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. On the **Resource inventory** page, select **AWS CodeBuild Project** under **Resource type**\. Scroll down and select the **CodeBuild project** check box\. 1. Choose **Look up**\. @@ -44,8 +43,4 @@ When you look up resources on the **Resource inventory** page, you can choose th The blocks at the top of the page are collectively called the timeline\. The timeline shows the date and time that the recording was made\. -For more information, see [Viewing configuration details in the AWS Config console](https://docs.aws.amazon.com/config/latest/developerguide/view-manage-resource-console.html) in the *AWS Config Developer Guide*\. - -Example of a CodeBuild project in AWS Config: - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/config-resources.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) \ No newline at end of file +For more information, see [Viewing configuration details in the AWS Config console](https://docs.aws.amazon.com/config/latest/developerguide/view-manage-resource-console.html) in the *AWS Config Developer Guide*\. \ No newline at end of file diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md index 49223b8..1598318 100644 --- a/doc_source/how-to-run.md +++ b/doc_source/how-to-run.md @@ -2,7 +2,7 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDK to set up, run, and monitor builds directly with CodeBuild\. -Not what you're looking for? To use AWS CodePipeline to run CodeBuild, see [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. +Not what you're looking for? To use AWS CodePipeline to run CodeBuild, see [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. **Topics** + [Prerequisites](#how-to-run-prerequisites) @@ -14,8 +14,8 @@ Answer the questions in [Plan a build](planning.md)\. ## Run AWS CodeBuild directly -1. Create the build project\. To use the console, see [Create a build project \(console\)](create-project-console.md)\. To use the AWS CLI, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. +1. Create the build project\. To use the console, see [Create a build project \(console\)](create-project-console.md)\. To use the AWS CLI, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. To use AWS SDK, see [Create a build project \(AWS SDKs\)](create-project-sdks.md)\. -1. Run the build\. To use the console, see [Run a build \(console\)](run-build-console.md)\. To use the AWS CLI, see [Run a build \(AWS CLI\)](run-build-cli.md)\. +1. Run the build\. To use the console, see [Run a build \(console\)](run-build-console.md)\. To use the AWS CLI, see [Run a build \(AWS CLI\)](run-build-cli.md)\. To use AWS SDK, see [Run a build \(AWS SDKs\)](run-build-sdks.md)\. -1. Get information about the build\. To use the console, see [View build details \(console\)](view-build-details.md#view-build-details-console)\. To use the AWS CLI, see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. \ No newline at end of file +1. Get information about the build\. To use the console, see [View build details \(console\)](view-build-details.md#view-build-details-console)\. To use the AWS CLI, see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. To use AWS SDK, see [View build details \(AWS SDKs\)](view-build-details.md#view-build-details-sdks)\. \ No newline at end of file diff --git a/doc_source/how-to-tag-project-delete.md b/doc_source/how-to-tag-project-delete.md index d6b8896..bbecfc6 100644 --- a/doc_source/how-to-tag-project-delete.md +++ b/doc_source/how-to-tag-project-delete.md @@ -23,7 +23,7 @@ You can use the CodeBuild console to remove the association between a tag and a ## Remove a tag from a project \(AWS CLI\) - To delete one or more tags from a build project, see [Change a build project's settings \(AWS CLI\)](change-project.md#change-project-cli)\. Update the `tags` section in the JSON\-formatted data with an updated list of tags that does not contain the ones you want to delete\. If you want to delete all tags, update the `tags` section to: + To delete one or more tags from a build project, see [Change a build project's settings \(AWS CLI\)](change-project-cli.md)\. Update the `tags` section in the JSON\-formatted data with an updated list of tags that does not contain the ones you want to delete\. If you want to delete all tags, update the `tags` section to: ``` "tags: []" diff --git a/doc_source/how-to-tag-project-update.md b/doc_source/how-to-tag-project-update.md index d822274..5c054c7 100644 --- a/doc_source/how-to-tag-project-update.md +++ b/doc_source/how-to-tag-project-update.md @@ -25,4 +25,4 @@ You can use the CodeBuild console to edit the tags associated with a CodeBuild p ## Edit tags for a project \(AWS CLI\) - To add, change, or delete tags from a build project, see [Change a build project's settings \(AWS CLI\)](change-project.md#change-project-cli)\. Update the `tags` section in the JSON\-formatted data you use to update the project\. \ No newline at end of file + To add, change, or delete tags from a build project, see [Change a build project's settings \(AWS CLI\)](change-project-cli.md)\. Update the `tags` section in the JSON\-formatted data you use to update the project\. \ No newline at end of file diff --git a/doc_source/index.md b/doc_source/index.md index 57f5042..6c66743 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,7 +1,7 @@ # AWS CodeBuild User Guide ----- -*****Copyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** +*****Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** ----- Amazon's trademarks and trade dress may not be used in @@ -18,40 +18,39 @@ Amazon's trademarks and trade dress may not be used in + [AWS CodeBuild concepts](concepts.md) + [Getting started with CodeBuild](getting-started-overview.md) + [Getting started with AWS CodeBuild using the console](getting-started.md) - + [Step 1: Create two S3 buckets](getting-started-input-bucket-console.md) - + [Step 2: Create the source code](getting-started-create-source-code-console.md) - + [Step 3: Create the buildspec file](getting-started-create-build-spec-console.md) + + [Step 1: Create the source code](getting-started-create-source-code-console.md) + + [Step 2: Create the buildspec file](getting-started-create-build-spec-console.md) + + [Step 3: Create two S3 buckets](getting-started-input-bucket-console.md) + [Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md) + [Step 5: Create the build project](getting-started-create-build-project-console.md) + [Step 6: Run the build](getting-started-run-build-console.md) + [Step 7: View summarized build information](getting-started-monitor-build-console.md) + [Step 8: View detailed build information](getting-started-build-log-console.md) + [Step 9: Get the build output artifact](getting-started-output-console.md) - + [Step 10: Delete the S3 input bucket](getting-started-clean-up-console.md) + + [Step 10: Delete the S3 buckets](getting-started-clean-up-console.md) + [Wrapping up](getting-started-next-steps-console.md) + [Getting started with AWS CodeBuild using the AWS CLI](getting-started-cli.md) - + [Step 1: Create two S3 buckets](getting-started-cli-input-bucket.md) - + [Step 2: Create the source code](getting-started-cli-create-source-code.md) - + [Step 3: Create the buildspec file](getting-started-cli-create-build-spec.md) + + [Step 1: Create the source code](getting-started-cli-create-source-code.md) + + [Step 2: Create the buildspec file](getting-started-cli-create-build-spec.md) + + [Step 3: Create two S3 buckets](getting-started-cli-input-bucket.md) + [Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md) + [Step 5: Create the build project](getting-started-cli-create-build-project.md) + [Step 6: Run the build](getting-started-cli-run-build.md) + [Step 7: View summarized build information](getting-started-cli-monitor-build.md) + [Step 8: View detailed build information](getting-started-cli-build-log.md) + [Step 9: Get the build output artifact](getting-started-cli-output.md) - + [Step 10: Delete the S3 input bucket](getting-started-cli-clean-up.md) + + [Step 10: Delete the S3 buckets](getting-started-cli-clean-up.md) + [Wrapping up](getting-started-cli-next-steps.md) + [CodeBuild samples](samples.md) + [Microsoft Windows samples for CodeBuild](sample-windows.md) + [CodeBuild use case-based samples](use-case-based-samples.md) - + [Use access tokens with your source provider in CodeBuild](sample-access-tokens.md) + [Amazon ECR sample for CodeBuild](sample-ecr.md) + [Amazon Elastic File System sample for AWS CodeBuild](sample-efs.md) + [CodeDeploy sample for CodeBuild](sample-codedeploy.md) + + [AWS CodePipeline integration with CodeBuild and batch builds](sample-pipeline-batch.md) + [AWS CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample](sample-pipeline-multi-input-output.md) + [Use AWS Config with CodeBuild sample](how-to-integrate-config.md) + [AWS Elastic Beanstalk sample for CodeBuild](sample-elastic-beanstalk.md) - + [AWS Lambda sample for CodeBuild](sample-lambda.md) + [Bitbucket pull request and webhook filter sample for CodeBuild](sample-bitbucket-pull-request.md) + [Build badges sample with CodeBuild](sample-build-badges.md) + [Build notifications sample for CodeBuild](sample-build-notifications.md) @@ -68,21 +67,20 @@ Amazon's trademarks and trade dress may not be used in + [Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) + [Plan a build in AWS CodeBuild](planning.md) + [Build specification reference for CodeBuild](build-spec-ref.md) + + [Batch build buildspec reference](batch-build-buildspec.md) + [Build environment reference for AWS CodeBuild](build-env-ref.md) + [Docker images provided by CodeBuild](build-env-ref-available.md) + + [Available runtimes](available-runtimes.md) + + [Runtime versions](runtime-versions.md) + [Build environment compute types](build-env-ref-compute-types.md) + [Shells and commands in build environments](build-env-ref-cmd.md) + [Environment variables in build environments](build-env-ref-env-vars.md) + [Background tasks in build environments](build-env-ref-background-tasks.md) - + [Test and debug locally with the AWS CodeBuild agent](use-codebuild-agent.md) -+ [Run AWS CodeBuild directly](how-to-run.md) + + [Run builds locally with the AWS CodeBuild agent](use-codebuild-agent.md) + [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md) + [Use VPC endpoints](use-vpc-endpoints-with-codebuild.md) + [AWS CloudFormation VPC template](cloudformation-vpc-template.md) + [Use AWS CodeBuild with a proxy server](use-proxy-server.md) -+ [Use CodePipeline with AWS CodeBuild to test code and run builds](how-to-create-pipeline.md) -+ [Use AWS CodeBuild with Jenkins](jenkins-plugin.md) -+ [Use AWS CodeBuild with Codecov](codecov-integration.md) + [Working with build projects and builds in AWS CodeBuild](builds-projects-and-builds.md) + [Working with build projects](working-with-build-projects.md) + [Create a build project in AWS CodeBuild](create-project.md) @@ -96,7 +94,13 @@ Amazon's trademarks and trade dress may not be used in + [Build caching in AWS CodeBuild](build-caching.md) + [Create AWS CodeBuild triggers](trigger-create.md) + [Edit AWS CodeBuild triggers](triggers-edit.md) + + [Using webhooks with AWS CodeBuild](webhooks.md) + + [Bitbucket webhook events](bitbucket-webhook.md) + + [GitHub webhook events](github-webhook.md) + [Change a build project's settings in AWS CodeBuild](change-project.md) + + [Change a build project's settings (console)](change-project-console.md) + + [Change a build project's settings (AWS CLI)](change-project-cli.md) + + [Change a build project's settings (AWS SDKs)](change-project-sdks.md) + [Delete a build project in AWS CodeBuild](delete-project.md) + [Working with shared projects](project-sharing.md) + [Tagging projects in AWS CodeBuild](how-to-tag-project.md) @@ -104,10 +108,13 @@ Amazon's trademarks and trade dress may not be used in + [View tags for a project](how-to-tag-project-list.md) + [Edit tags for a project](how-to-tag-project-update.md) + [Remove a tag from a project](how-to-tag-project-delete.md) + + [Batch builds in AWS CodeBuild](batch-build.md) + + [Public build projects in AWS CodeBuild](public-builds.md) + [Working with builds in AWS CodeBuild](builds-working.md) + [Run a build in AWS CodeBuild](run-build.md) + [Run a build (console)](run-build-console.md) + [Run a build (AWS CLI)](run-build-cli.md) + + [Run a batch build (AWS CLI)](run-batch-build-cli.md) + [Start running builds automatically (AWS CLI)](run-build-cli-auto-start.md) + [Stop running builds automatically (AWS CLI)](run-build-cli-auto-stop.md) + [Run a build (AWS SDKs)](run-build-sdks.md) @@ -115,6 +122,8 @@ Amazon's trademarks and trade dress may not be used in + [View a list of build IDs in AWS CodeBuild](view-build-list.md) + [View a list of build IDs for a build project in AWS CodeBuild](view-builds-for-project.md) + [Stop a build in AWS CodeBuild](stop-build.md) + + [Stop a batch build in AWS CodeBuild](stop-batch-build.md) + + [Retry a build in AWS CodeBuild](retry-build.md) + [View a running build in Session Manager](session-manager.md) + [Delete builds in AWS CodeBuild](delete-builds.md) + [Working with test reporting in AWS CodeBuild](test-reporting.md) @@ -122,8 +131,8 @@ Amazon's trademarks and trade dress may not be used in + [Working with report groups](test-report-group.md) + [Create a report group](report-group-create.md) + [Create a report group (buildspec)](test-report-group-create-buildspec.md) - + [Create a report group (CLI)](test-report-group-create-cli.md) + [Create a report group (console)](test-report-group-create-console.md) + + [Create a report group (CLI)](test-report-group-create-cli.md) + [Create a report group (AWS CloudFormation)](test-report-group-create-cfn.md) + [Update a report group](report-group-export-settings.md) + [Update a report group (console)](update-report-group-console.md) @@ -145,6 +154,7 @@ Amazon's trademarks and trade dress may not be used in + [Set up test reporting with Jest](test-report-jest.md) + [Set up test reporting with pytest](test-report-pytest.md) + [Set up test reporting with RSpec](test-report-rspec.md) + + [Code coverage reports](code-coverage-report.md) + [Logging and monitoring in AWS CodeBuild](logging-monitoring.md) + [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md) + [Monitoring AWS CodeBuild](monitoring-builds.md) @@ -165,11 +175,21 @@ Amazon's trademarks and trade dress may not be used in + [Compliance validation for AWS CodeBuild](codebuild-compliance-validation.md) + [Resilience in AWS CodeBuild](codebuild-disaster-recovery-resiliency.md) + [Infrastructure security in AWS CodeBuild](infrastructure-security.md) + + [Access your source provider in CodeBuild](access-tokens.md) + [Advanced topics](advanced-topics.md) + [Advanced setup](setting-up.md) + [Command line reference for AWS CodeBuild](cmd-ref.md) + [AWS SDKs and tools reference for AWS CodeBuild](sdk-ref.md) + [Specify the AWS CodeBuild endpoint](endpoint-specify.md) + + [Run AWS CodeBuild directly](how-to-run.md) + + [Use AWS CodePipeline with AWS CodeBuild to test code and run builds](how-to-create-pipeline.md) + + [Create a pipeline that uses CodeBuild (CodePipeline console)](how-to-create-pipeline-console.md) + + [Create a pipeline that uses CodeBuild (AWS CLI)](how-to-create-pipeline-cli.md) + + [Add a CodeBuild build action to a pipeline (CodePipeline console)](how-to-create-pipeline-add.md) + + [Add a CodeBuild test action to a pipeline (CodePipeline console)](how-to-create-pipeline-add-test.md) + + [Use AWS CodeBuild with Jenkins](jenkins-plugin.md) + + [Use AWS CodeBuild with Codecov](codecov-integration.md) + + [Use AWS CodeBuild with serverless applications](serverless-applications.md) + [Troubleshooting AWS CodeBuild](troubleshooting.md) + [Quotas for AWS CodeBuild](limits.md) + [Third party notices for AWS CodeBuild for Windows](notice.md) diff --git a/doc_source/limits.md b/doc_source/limits.md index 12b9351..5ddb5c5 100644 --- a/doc_source/limits.md +++ b/doc_source/limits.md @@ -2,7 +2,17 @@ The following tables list the current quotas in AWS CodeBuild\. These quotas are for each supported AWS Region for each AWS account, unless otherwise specified\. -## Build projects +## Service quotas + +The following are the default quotas for the AWS CodeBuild service\. + +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/limits.html) + +Quotas for the maximum number of concurrent running builds vary, depending on the compute type\. For some platforms and compute types, the default is 20\. For a new account, the quota can be as low as 5\. To request a higher concurrent build quota, or if you get a "Cannot have more than X active builds for the account" error, use the link above to make the request\. + +## Other limits + +### Build projects **** @@ -13,29 +23,20 @@ The following tables list the current quotas in AWS CodeBuild\. These quotas are | Allowed characters in a build project name | The letters A\-Z and a\-z, the numbers 0\-9, and the special characters \- and \_ | | Length of a build project name | 2 to 255 characters, inclusive | | Maximum length of a build project description | 255 characters | -| Maximum number of build projects | 5,000 | -| Maximum number of build projects you can request information about at one time using the AWS CLI or AWS SDKs | 100 | | Maximum number of reports you can add to a project | 5 | -| Maximum number of tags you can associate with a build project | 50 | | Number of minutes you can specify in a build project for the build timeout of all related builds | 5 to 480 \(8 hours\) | -| Number of security groups you can add under VPC configuration | 1 to 5 | -| Number of subnets you can add under VPC configuration | 1 to 16 | -## Builds +### Builds **** | Resource | Default | | --- | --- | -| Maximum number of builds you can request information about at one time using the AWS CLI or AWS SDKs | 100 | -| Maximum number of concurrent running builds\* | 60 | | Maximum time the history of a build is retained | 1 year | | Number of minutes you can specify for the build timeout of a single build | 5 to 480 \(8 hours\) | -\* Quotas for the maximum number of concurrent running builds vary, depending on the compute type\. For some platforms and compute types, the default is 20\. For a new account, the quota can be 1—5\. To request a higher concurrent build quota or if you get a "Cannot have more than X active builds for the account" error, contact AWS Support\. - -## Reports +### Reports **** @@ -43,18 +44,19 @@ The following tables list the current quotas in AWS CodeBuild\. These quotas are | Resource | Default | | --- | --- | | Maximum duration a test report is available after it is created | 30 days | -| Maximum number of report groups per AWS account | 1000 | +| Maximum length of a test case message | 5,000 characters | +| Maximum length of a test case name | 1,000 characters | +| Maximum number of report groups per AWS account | 1,000 | | Maximum number of test cases per report | 500 | -## Tags +### Tags - Tag limits apply to tags on CodeBuild build project and CodeBuild report group resources\. +Tag limits apply to tags on CodeBuild build projects and CodeBuild report group resources\. **** | Resource | Default | | --- | --- | -| Maximum number of tags you can associate with a resource | 50\. Tags are case sensitive | | Resource tag key names | Any combination of Unicode letters, numbers, spaces, and allowed characters in UTF\-8 between 1 and 127 characters in length\. Allowed characters are `+ - = . _ : / @` Tag key names must be unique, and each key can only have one value\. A tag key name cannot: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/limits.html) | | Resource tag values | Any combination of Unicode letters, numbers, spaces, and allowed characters in UTF\-8 between 0 and 255 characters in length\. Allowed characters are `+ - = . _ : / @` A key can only have one value, but many keys can have the same value\. A tag key value cannot contain emojis or any of the following characters:` ? ^ * [ \ ~ ! # $ % & * ( ) > < \| " ' ` [ ] { } ;` | \ No newline at end of file diff --git a/doc_source/monitoring-alarms.md b/doc_source/monitoring-alarms.md index 76e4348..2bd8d02 100644 --- a/doc_source/monitoring-alarms.md +++ b/doc_source/monitoring-alarms.md @@ -10,17 +10,12 @@ 1. Choose **Create Alarm**\. -1. Under **CloudWatch Metrics by Category**, choose **CodeBuild Metrics**\. If you know you want only project\-level metrics, choose **By Project**\. If you know you want only account\-level metrics, choose **Account Metrics**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-alarm-metrics-in-cw.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. Under **CloudWatch Metrics by Category**, choose **CodeBuild Metrics**\. If you know you want only project\-level metrics, choose **By Project**\. If you know you want only account\-level metrics, choose **Account Metrics**\. 1. On **Create Alarm**, if it isn't already selected, choose **Select Metric**\. -1. Choose a metric for which you want to create an alarm\. The options are **By Project** or **Account Metrics**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-alarm-account-metrics-in-cw.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. Choose a metric for which you want to create an alarm\. The options are **By Project** or **Account Metrics**\. 1. Choose **Next** or **Define Alarm** and then create your alarm\. For more information, see [Creating Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*\. For more information about setting up Amazon SNS notifications when an alarm is triggered, see [Set up Amazon SNS notifications](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/US_SetupSNS.html) in the *Amazon SNS Developer Guide*\. - The following shows an alarm that sends an Amazon SNS notification to a list named **codebuild\-sns\-notifications** when one or more failed builds are detected over 15 minutes\. The 15 minutes is calculated by multiplying the five minute period by the three specified data points\. The information displayed for a failed builds alarm at the project level or account level is identical\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-alarm-sample-cw.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - 1. Choose **Create Alarm**\. \ No newline at end of file diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index 6b057fd..8cef7f1 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.md @@ -12,7 +12,7 @@ CloudWatch metrics show the behavior of your builds over time\. For example, you + How many builds were attempted in a build project or an AWS account over time\. + How many builds were successful in a build project or an AWS account over time\. + How many builds failed in a build project or an AWS account over time\. -+ How much time CodeBuild spent executing builds in a build project or an AWS account over time\. ++ How much time CodeBuild spent running builds in a build project or an AWS account over time\. + Build resource utilization for a build or an entire build project\. Build resource utilization metrics include metrics such as CPU, memory, and storage utilization\. For more information, see [Monitoring CodeBuild metrics](monitoring-metrics.md)\. @@ -93,8 +93,6 @@ Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum ## CodeBuild CloudWatch resource utilization metrics -The following resource utilization metrics can be tracked\. - **Note** CodeBuild resource utilization metrics are only available in the following regions: Asia Pacific \(Tokyo\) Region @@ -113,6 +111,8 @@ US East \(Ohio\) Region US West \(N\. California\) Region US West \(Oregon\) Region +The following resource utilization metrics can be tracked\. + CPUUtilized The number of CPU units of allocated processing used by the build container\. Units: CPU units diff --git a/doc_source/monitoring-utilization-metrics.md b/doc_source/monitoring-utilization-metrics.md index a5eb08a..461eb5c 100644 --- a/doc_source/monitoring-utilization-metrics.md +++ b/doc_source/monitoring-utilization-metrics.md @@ -2,7 +2,10 @@ AWS CodeBuild monitors build resource utilization on your behalf and reports metrics through Amazon CloudWatch\. These include metrics such as CPU, memory, and storage utilization\. -You can use the CodeBuild console or the CloudWatch console to monitor resource utilization metrics for CodeBuild\. The following procedures show you how to access your resource utilization metrics\. +**Note** +CodeBuild resource utilization metrics are only recorded for builds that run for more than one minute\. + +You can use the CodeBuild console or the CloudWatch console to monitor resource utilization metrics for CodeBuild\. **Note** CodeBuild resource utilization metrics are only available in the following regions: @@ -22,6 +25,8 @@ US East \(Ohio\) Region US West \(N\. California\) Region US West \(Oregon\) Region +The following procedures show you how to access your resource utilization metrics\. + **Topics** + [Access resource utilization metrics \(CodeBuild console\)](#utilization-metrics-codebuild-console) + [Access resource utilization metrics \(Amazon CloudWatch console\)](#utilization-metrics-cloudwatch-console) diff --git a/doc_source/notice.md b/doc_source/notice.md index fa6b90b..30b657e 100644 --- a/doc_source/notice.md +++ b/doc_source/notice.md @@ -45,7 +45,7 @@ As part of the Supplemental License Terms for this Container OS Image for Window ## 2\) windows\-base Docker image—choco -\(license terms available at: [https://github\.com/chocolatey/chocolatey\.org/blob/master/LICENSE\.txt](https://github.com/chocolatey/chocolatey.org/blob/master/LICENSE.txt)\) +\(license terms available at: [https://github\.com/chocolatey/choco/blob/master/LICENSE](https://github.com/chocolatey/choco/blob/master/LICENSE)\) Copyright 2011 \- Present RealDimensions Software, LLC @@ -190,7 +190,7 @@ The following license terms describe additional use terms for this supplement\. ## 8\) windows\-base Docker image—visualfsharptools, v 4\.0 -\(license terms available at: [https://raw\.githubusercontent\.com/Microsoft/visualfsharp/master/License\.txt](https://raw.githubusercontent.com/Microsoft/visualfsharp/master/License.txt)\) +\(license terms available at: [https://github\.com/dotnet/fsharp/blob/main/License\.txt](https://github.com/dotnet/fsharp/blob/main/License.txt)\) Copyright \(c\) Microsoft Corporation\. All rights reserved\. @@ -376,7 +376,7 @@ The following license terms describe additional use terms for this supplement\. ## 12\) windows\-base Docker image—dotnet\-sdk -\(available at [https://github\.com/dotnet/core/blob/master/LICENSE\.TXT](https://github.com/dotnet/core/blob/master/LICENSE.TXT)\) +\(available at [https://github\.com/dotnet/core/blob/main/LICENSE\.TXT](https://github.com/dotnet/core/blob/main/LICENSE.TXT)\) The MIT License \(MIT\) diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md index 5f100e4..10bfa16 100644 --- a/doc_source/notification-rule-create.md +++ b/doc_source/notification-rule-create.md @@ -2,6 +2,8 @@ You can use notification rules to notify users when important changes, such as build successes and failures, occur\. Notification rules specify both the events and the Amazon SNS topic that is used to send notifications\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html) + + You can use the console or the AWS CLI to create notification rules for AWS CodeBuild\. # To create a notification rule \(console\) diff --git a/doc_source/planning.md b/doc_source/planning.md index 20361d3..bff9632 100644 --- a/doc_source/planning.md +++ b/doc_source/planning.md @@ -2,7 +2,9 @@ Before you use AWS CodeBuild, you must answer these questions: -1. **Where is the source code stored?** CodeBuild currently supports building from the following source code repository providers\. The source code must contain a build specification \(buildspec\) file\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can declare a buildspec in a build project definition\. +1. **Where is the source code stored?** CodeBuild currently supports building from the following source code repository providers\. The source code must contain a build specification \(buildspec\) file\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can declare a buildspec in a build project definition\. + + **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/planning.html) @@ -17,5 +19,5 @@ Before you use AWS CodeBuild, you must answer these questions: 1. **Do you want CodeBuild to work with your VPC?** If so, you need the VPC ID, the subnet IDs, and security group IDs for your VPC configuration\. For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. After you have answered these questions, you should have the settings and resources you need to run a build successfully\. To run your build, you can: -+ Use the AWS CodeBuild console, AWS CLI, or AWS SDKs\. For more information, see [Run AWS CodeBuild directly](how-to-run.md)\. -+ Create or identify a pipeline in AWS CodePipeline, and then add a build or test action that instructs CodeBuild to automatically test your code, run your build, or both\. For more information, see [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. \ No newline at end of file ++ Use the AWS CodeBuild console, AWS CLI, or AWS SDKs\. For more information, see [Run CodeBuild directly](how-to-run.md)\. ++ Create or identify a pipeline in AWS CodePipeline, and then add a build or test action that instructs CodeBuild to automatically test your code, run your build, or both\. For more information, see [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. \ No newline at end of file diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index 3fbf3a9..e2f1267 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -17,7 +17,7 @@ To share a project, your AWS account must own it\. You cannot share a project th ## Prerequisites for accessing shared projects shared with you -To access a shared report group, a consumer's IAM role requires the `BatchGetProjects` permission\. You can attach the following policy to their IAM role: +To access a shared project, a consumer's IAM role requires the `BatchGetProjects` permission\. You can attach the following policy to their IAM role: ``` { diff --git a/doc_source/public-builds.md b/doc_source/public-builds.md new file mode 100644 index 0000000..f6ed29c --- /dev/null +++ b/doc_source/public-builds.md @@ -0,0 +1,25 @@ +# Public build projects in AWS CodeBuild + +AWS CodeBuild allows you to make the build results, logs, and artifacts for your build projects available to the general public\. This allows contributors to your source repositories to view the results and download the artifacts of a build, without requiring them to have access to an AWS account\. + +When you make your project's builds available to the public, all of a project's build results, logs, and artifacts, including builds that were run when the project was private, are made available to the public\. Likewise, when you make a public build project private, the build results for that project are no longer available to the public\. + +For information about how to change the public visibility of your project's build results, see [Enable public build access](change-project-console.md#change-project-console.public-builds)\. + +CodeBuild provides a URL for the public builds for your project that is unique to your project\. To obtain the public URL for your build project, perform the following procedure: + +1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. + +1. In the navigation pane, choose **Build projects**\. + +1. Choose the link for the build project you want to obtain the public URL for\. + +1. The public URL is displayed in the **Public project URL** field in the **Configuration** section\. You can choose the link to open the URL, or copy the URL with the copy button\. + +**Warning** +The following should be kept in mind when making your project's build results public: +All of a project's build results, logs, and artifacts, including builds that were run when the project was private, are available to the public\. +All build logs and artifacts are available to the public\. Environment variables, source code, and other sensitive information may have been output to the build logs and artifacts\. You must be careful about what information is output to the build logs\. Some best practices are: +Do not store sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. We recommend that you use an Amazon EC2 Systems Manager Parameter Store or AWS Secrets Manager to store sensitive values\. +Follow [Best practices for using webhooks](webhooks.md#webhook-best-practices) to limit which entities can trigger a build, and do not store the buildspec in the project itself, to ensure that your webhooks are as secure as possible\. +A malicious user can use public builds to distribute malicious artifacts\. We recommend that project administrators review all pull requests to verify that the pull request is a legitimate change\. We also recommend that you validate any artifacts with their checksums to make sure that the correct artifacts are being downloaded\. \ No newline at end of file diff --git a/doc_source/report-create.md b/doc_source/report-create.md index eee2c43..e2b0c71 100644 --- a/doc_source/report-create.md +++ b/doc_source/report-create.md @@ -4,16 +4,34 @@ **To create a test report** -1. Create a build project\. For information, see [Create a build project in AWS CodeBuild](create-project.md)\. +1. Create a build project\. For information, see [Create a build project in AWS CodeBuild](create-project.md)\. -1. Configure the buildspec file of your project with test report informaton: +1. Configure the buildspec file of your project with test report informaton: - 1. Add a `reports:` section and specify the name for your report group\. CodeBuild creates a report group for you using your project name and the name you specified in the format `project-name`\-`report-group-name-in-buildspec`\. If you already have a report group you want to use, specify its ARN\. \(If you use its name instead of its ARN, CodeBuild creates a new report group\.\) For more information, see [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. + 1. Add a `reports:` section and specify either the ARN of an existing report group, or the name of a report group\. - 1. Under the report group, specify the location of the files that store test results\. If you use more than one report group, specify test result file locations for each one\. A new test report is created each time your build project runs\. For more information, see [Specify test files](report-group-test-cases.md)\. + If you specify an ARN, CodeBuild uses that report group\. + + If you specify a name, CodeBuild creates a report group for you using your project name, and the name you specified, in the format **\-**\. If the named report group already exists, CodeBuild uses that report group\. + + 1. Under the report group, specify the location of the files that contain the test results\. If you use more than one report group, specify test result file locations for each one\. A new test report is created each time your build project runs\. For more information, see [Specify test files](report-group-test-cases.md)\. 1. In the `commands` section of the `build` or `post_build` sequence, specify the commands that run the tests cases you specified for your report groups\. For more information, see [ Specify test commands ](report-group-test-case-commands.md)\. -1. Run a build of the build project\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. + The following is an example of a buildspec `reports` section: + + ``` + reports: + php-reports: + files: + - "reports/php/*.xml" + file-format: "JUNITXML" + nunit-reports: + files: + - "reports/nunit/*.xml" + file-format: "NUNITXML" + ``` + +1. Run a build of the build project\. For more information, see [Run a build in AWS CodeBuild](run-build.md)\. -1. When the build is complete, choose the new build run from **Build history** on your project page\. Choose **Reports** to view the test report\. For more information, see [ View test reports for a build ](test-view-reports.md#test-view-project-reports)\. \ No newline at end of file +1. When the build is complete, choose the new build run from **Build history** on your project page\. Choose **Reports** to view the test report\. For more information, see [View test reports for a build](test-view-reports.md#test-view-project-reports)\. \ No newline at end of file diff --git a/doc_source/report-group-create.md b/doc_source/report-group-create.md index 52cbea4..43756c0 100644 --- a/doc_source/report-group-create.md +++ b/doc_source/report-group-create.md @@ -4,6 +4,6 @@ **Topics** + [Create a report group \(buildspec\)](test-report-group-create-buildspec.md) -+ [Create a report group \(CLI\)](test-report-group-create-cli.md) + [Create a report group \(console\)](test-report-group-create-console.md) ++ [Create a report group \(CLI\)](test-report-group-create-cli.md) + [Create a report group \(AWS CloudFormation\)](test-report-group-create-cfn.md) \ No newline at end of file diff --git a/doc_source/report-group-export-settings.md b/doc_source/report-group-export-settings.md index e5dea19..9918839 100644 --- a/doc_source/report-group-export-settings.md +++ b/doc_source/report-group-export-settings.md @@ -3,10 +3,10 @@ When you update a report group, you can specify information about whether to export the raw test result data to files in an Amazon S3 bucket\. If you choose to export to an S3 bucket, you can specify the following for your report group: + Whether the raw test results files are compressed in a ZIP file\. + Whether the raw test result files are encrypted\. You can specify encryption with one of the following: - + A customer master key \(CMK\) for Amazon S3 that is managed by the AWS Key Management Service\. - + A CMK that you create and configure\. + + An AWS managed key for Amazon S3\. + + A customer managed key that you create and configure\. - For more information, see [Data encryption](security-encryption.md)\. +For more information, see [Data encryption](security-encryption.md)\. If you use the AWS CLI to update a report group, you can also update or add tags\. For more information, see [Tagging report groups in AWS CodeBuildTag a report group](how-to-tag-report-group.md)\. diff --git a/doc_source/report-group-test-cases.md b/doc_source/report-group-test-cases.md index 81756ec..66b76d5 100644 --- a/doc_source/report-group-test-cases.md +++ b/doc_source/report-group-test-cases.md @@ -15,5 +15,5 @@ reports: sampleReportGroup: #Cucumber reports from json plugin files: - 'cucumber-json/target/cucumber-json-report.json' - file-format: CucumberJson #Type of the report, defaults to JunitXml + file-format: CUCUMBERJSON #Type of the report, defaults to JUNITXML ``` \ No newline at end of file diff --git a/doc_source/report-groups-sharing.md b/doc_source/report-groups-sharing.md index 78d7b32..182f100 100644 --- a/doc_source/report-groups-sharing.md +++ b/doc_source/report-groups-sharing.md @@ -70,7 +70,7 @@ Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/referen Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/put-resource-policy.html) command: -1. Create a file named `policy.json` and copy the following into it\. +1. Create a file named `policy.json` and copy the following into it\. ``` { @@ -83,7 +83,7 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference "Action":[ "codebuild:BatchGetReportGroups", "codebuild:BatchGetReports", - "codebuild:ListBuildsForProject", + "codebuild:ListReportsForReportGroup", "codebuild:DescribeTestCases"], "Resource":"arn-of-report-group-to-share" }] @@ -99,21 +99,21 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference "Effect":"Allow", "Principal":{ "AWS": [ - "arn:aws:iam:123456789012:user/Alice", + "arn:aws:iam::123456789012:user/Alice", "123456789012" ] }, "Action":[ "codebuild:BatchGetReportGroups", "codebuild:BatchGetReports", - "codebuild:ListBuildsForProject", + "codebuild:ListReportsForReportGroup", "codebuild:DescribeTestCases"], "Resource":"arn:aws:codebuild:us-west-2:123456789012:report-group/my-report-group" }] } ``` -1. Run the following command\. +1. Run the following command\. ``` aws codebuild put-resource-policy --resource-arn report-group-arn --policy file://policy.json diff --git a/doc_source/retry-build.md b/doc_source/retry-build.md new file mode 100644 index 0000000..3b11df6 --- /dev/null +++ b/doc_source/retry-build.md @@ -0,0 +1,39 @@ +# Retry a build in AWS CodeBuild + +You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to retry either a single build or a batch build in AWS CodeBuild\. + +**Topics** ++ [Retry a build \(console\)](#retry-build-console) ++ [Retry a build \(AWS CLI\)](#retry-build-cli) ++ [Retry a build \(AWS SDKs\)](#retry-build-sdks) + +## Retry a build \(console\) + +1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. + +1. Do one of the following: + + If the ***build\-project\-name*:*build\-ID*** page is displayed, choose **Retry build**\. + + In the navigation pane, choose **Build history**\. In the list of builds, select the box for the build, and then choose **Retry build**\. + + In the navigation pane, choose **Build projects**\. In the list of build projects, in the **Name** column, choose the link for the build project's name\. In the list of builds, select the box for the build, and then choose **Retry build**\. + +**Note** +By default, only the most recent 100 builds or build projects are displayed\. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows\. + +## Retry a build \(AWS CLI\) ++ Run the retry\-build command: + + ``` + aws codebuild retry-build --id --idempotency-token + ``` + + In the preceding command, replace the following placeholder: + + **: Required string\. The ID of the build or batch build to retry\. To get a list of build IDs, see the following topics: + + [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-build-list-cli) + + [View a list of batch build IDs \(AWS CLI\)](view-build-list.md#view-batch-build-list-cli) + + [View a list of build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) + + [View a list of batch build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-batch-builds-for-project-cli) + + `--idempotency-token`: Optional\. If you run the retry\-build command with the option, a unique case\-sensitive identifier, or token, is included with the `retry-build` request\. The token is valid for 5 minutes after the request\. If you repeat the `retry-build` request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. + +## Retry a build \(AWS SDKs\) + +For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file diff --git a/doc_source/run-batch-build-cli.md b/doc_source/run-batch-build-cli.md new file mode 100644 index 0000000..7e58b7a --- /dev/null +++ b/doc_source/run-batch-build-cli.md @@ -0,0 +1,57 @@ +# Run a batch build \(AWS CLI\) + +1. Run the `start-build-batch` command in one of the following ways: + + ``` + aws codebuild start-build-batch --project-name + ``` + + Use this if you want to run a build that uses the latest version of the build input artifact and the build project's existing settings\. + + ``` + aws codebuild start-build-batch --generate-cli-skeleton > + ``` + + Use this if you want to run a build with an earlier version of the build input artifact or if you want to override the settings for the build output artifacts, environment variables, buildspec, or default build timeout period\. + +1. If you run the start\-build\-batch command with the `--project-name` option, replace ** with the name of the build project, and then skip to step 6 of this procedure\. To get a list of build projects, see [View a list of build project names](view-project-list.md)\. + +1. If you run the start\-build\-batch command with the `--idempotency-token` option, a unique case\-sensitive identifier, or token, is included with the `start-build-batch` request\. The token is valid for 5 minutes after the request\. If you repeat the `start-build-batch` request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. + +1. If you run the start\-build\-batch command with the `--generate-cli-skeleton` option, JSON\-formatted data is output to the ** file\. This file is similar to the skelton produced by the start\-build command, with the addition of the following object\. For more information about the common objects, see [Run a build \(AWS CLI\)](run-build-cli.md)\. + + Modify this file to add any build overrides, and save your results\. + + ``` + "buildBatchConfigOverride": { + "combineArtifacts": combineArtifacts, + "restrictions": { + "computeTypesAllowed": [ + allowedComputeTypes + ], + "maximumBuildsAllowed": maximumBuildsAllowed + }, + "serviceRole": "batchServiceRole", + "timeoutInMins": batchTimeout + } + ``` + + The `buildBatchConfigOverride` object is a [ProjectBuildBatchConfig](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectBuildBatchConfig.html) structure that contains the batch build configuration overides for this build\. +*combineArtifacts* +A boolean that specifies if the build artifacts for the batch build should be combined into a single artifact location\. +*allowedComputeTypes* +An array of strings that specify the compute types that are allowed for the batch build\. See [Build environment compute types](https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-compute-types.html) for these values\. +*maximumBuildsAllowed* +Specifies the maximum number of builds allowed\. +*batchServiceRole* +Specifies the service role ARN for the batch build project\. +*batchTimeout* +Specifies the maximum amount of time, in minutes, that the batch build must be completed in\. + +1. Switch to the directory that contains the file you just saved, and run the `start-build-batch` command again\. + + ``` + aws codebuild start-build-batch --cli-input-json file://start-build.json + ``` + +1. If successful, the JSON representation of a [BuildBatch](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_BuildBatch.html) object appears in the console output\. See the [StartBuildBatch Response Syntax](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_StartBuildBatch.html#API_StartBuildBatch_ResponseSyntax) for an example of this data\. \ No newline at end of file diff --git a/doc_source/run-build-cli-auto-start.md b/doc_source/run-build-cli-auto-start.md index 223a094..ae94018 100644 --- a/doc_source/run-build-cli-auto-start.md +++ b/doc_source/run-build-cli-auto-start.md @@ -2,7 +2,7 @@ If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can use GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. -Run the create\-webhookcommand as follows: +Run the create\-webhook command as follows: ``` aws codebuild create-webhook --project-name diff --git a/doc_source/run-build-cli.md b/doc_source/run-build-cli.md index 33fb710..f5f12cb 100644 --- a/doc_source/run-build-cli.md +++ b/doc_source/run-build-cli.md @@ -1,7 +1,7 @@ # Run a build \(AWS CLI\) **Note** -To use CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in [Create a pipeline that uses CodeBuild \(AWS CLI\)](how-to-create-pipeline.md#how-to-create-pipeline-cli)\. +To use CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in [Create a pipeline that uses CodeBuild \(AWS CLI\)](how-to-create-pipeline-cli.md)\. For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md)\. 1. Run the `start-build` command in one of the following ways: @@ -22,7 +22,7 @@ For more information about using the AWS CLI with CodeBuild, see the [Command li 1. If you run the start\-build command with the `--idempotency-token` option, a unique case\-sensitive identifier or token, is included with the `start-build` request\. The token is valid for 5 minutes after the request\. If you repeat the `start-build` request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. -1. If you run the start\-buildcommand with the `--generate-cli-skeleton` option, JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `start-build.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Modify the copied data to match the following format, and save your results: +1. If you run the start\-build command with the `--generate-cli-skeleton` option, JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `start-build.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Modify the copied data to match the following format, and save your results: ``` { @@ -34,27 +34,27 @@ For more information about using the AWS CLI with CodeBuild, see the [Command li "path": "path", "namespaceType": "namespaceType", "name": "artifactsOverride-name", - "packaging": "packaging" + "packaging": "packaging" }, "buildspecOverride": "buildspecOverride", "cacheOverride": { - "location": "cacheOverride-location", - "type": "cacheOverride-type" - }, + "location": "cacheOverride-location", + "type": "cacheOverride-type" + }, "certificateOverride": "certificateOverride", "computeTypeOverride": "computeTypeOverride", "environmentTypeOverride": "environmentTypeOverride", "environmentVariablesOverride": { - "name": "environmentVariablesOverride-name", - "value": "environmentVariablesValue", - "type": "environmentVariablesOverride-type" - }, + "name": "environmentVariablesOverride-name", + "value": "environmentVariablesValue", + "type": "environmentVariablesOverride-type" + }, "gitCloneDepthOverride": "gitCloneDepthOverride", "imageOverride": "imageOverride", "idempotencyToken": "idempotencyToken", "insecureSslOverride": "insecureSslOverride", "privilegedModeOverride": "privilegedModeOverride", - "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride", + "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride", "reportBuildStatusOverride": "reportBuildStatusOverride", "timeoutInMinutesOverride": "timeoutInMinutesOverride", "sourceAuthOverride": "sourceAuthOverride", diff --git a/doc_source/run-build-console.md b/doc_source/run-build-console.md index a4ff816..7a1c3b3 100644 --- a/doc_source/run-build-console.md +++ b/doc_source/run-build-console.md @@ -1,93 +1,30 @@ # Run a build \(console\) -To use AWS CodePipeline to run a build with CodeBuild, skip these steps and follow the instructions in [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. +To use AWS CodePipeline to run a build with CodeBuild, skip these steps and follow the instructions in [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. -1. Do one of the following: - + If you just finished creating a build project, the **Build project: *project\-name*** page should be displayed\. Choose **Start build**\. - + If you created a build project earlier, in the navigation pane, choose **Build projects**\. Choose the build project, and then choose **Start build**\. +1. In the navigation pane, choose **Build projects**\. -1. On the **Start build** page, do one of the following: - + For Amazon S3, for the optional **Source version** value, enter the version ID for the version of the input artifact you want to build\. If **Source version** is left blank, the latest version is used\. - + For CodeCommit, for **Reference type**, choose **Branch**, **Git tag**, or **Commit ID**\. Next, choose the branch, Git tag, or enter a commit ID to specify the version of your source code\. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md)\. Change the value for **Git clone depth**\. This creates a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - + For GitHub or GitHub Enterprise Server, for the optional **Source version** value, enter a commit ID, pull request ID, branch name, or tag name for the version of the source code you want to build\. If you specify a pull request ID, it must use the format `pr/pull-request-ID` \(for example, `pr/25`\)\. If you specify a branch name, the branch's HEAD commit ID is used\. If **Source version** is blank, the default branch's HEAD commit ID is used\. Change the value for **Git clone depth**\. This creates a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - + For Bitbucket, for the optional **Source version** value, enter a commit ID, branch name, or tag name for the version of the source code you want to build\. If you specify a branch name, the branch's HEAD commit ID is used\. If **Source version** is blank, the default branch's HEAD commit ID is used\. Change the value for **Git clone depth**\. This creates a shallow clone with a history truncated to the specified number of commits\. If you want a full clone, choose **Full**\. - + To use a different source provider for this build only, choose **Advanced build options**\. For more information about source provider options and settings, see [Choose source provider](create-project-console.md#create-project-source-provider)\. +1. In the list of build projects, choose the build project\. -1. Choose **Advanced build overrides**\. +1. You can run the build with the default build project settings, or override build settings for this build only\. - Here you can change settings for this build only\. The settings in this section are optional\. + 1. If you want to run the build with the default build project settings, choose **Start build**\. The build starts immediately\. - Under **Source**, you can: - + Choose **Add source** to add a secondary source\. - + Choose **Remove source** to remove a secondary source\. - + Use **Source provider** and **Source version** to modify settings for a source\. + 1. If you want to override the default build project settings, choose **Start build with overrides**\. In the **Start build** page, you can override the following: + + **Build configuration** + + **Source** + + **Environment variable overrides** - Under **Environment**, you can: - + Override settings for **Environment image**, **Operating system**, **Runtime**, and **Runtime version**\. - + Select or clear **Privileged**\. -**Note** -By default, Docker containers do not allow access to any devices\. Privileged mode grants a build project's Docker container access to all devices\. For more information, see [Runtime Privilege and Linux Capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) on the Docker Docs website\. - + In **Service role**, you can change the service role that CodeBuild uses to call dependent AWS services for you\. Choose **New service role** to have CodeBuild create a service role for you\. - + Choose **Override build specification** to use a different build specification\. - + Change the value for **Timeout**\. - + Change the value for **Compute**\. - + From **Certificate**, choose a different setting\. + If you need to select more advanced overrides, choose **Advanced build overrides**\. In this page, you can override the following: + + **Build configuration** + + **Source** + + **Environment** + + **Buildspec** + + **Artifacts** + + **Logs** - Under **Buildspec**, you can: - + Choose **Use a buildspec file** to use a buildspec\.yml file\. By default, CodeBuild looks for a file named `buildspec.yml` in the source code root directory\. If your buildspec file uses a different name or location, enter its path from the source root in **Buildspec name** \(for example, **buildspec\-two\.yml** or **configuration/buildspec\.yml**\. If the buildspec file is in an S3 bucket, it must be in the same AWS Region as your build project\. Specify the buildspec file by its ARN \(for example, **arn:aws:s3:::my\-codebuild\-sample2/buildspec\.yml**\)\. - + Choose **Insert build commands** to enter commands you want to run during the build phase\. + When you have made your override selections, choose **Start build**\. - Under **Build Artifacts**, you can: - + From **Type**, choose a different artifacts type\. - + In **Name**, enter a different output artifact name\. - + If you want a name specified in the buildspec file to override any name specified in the console, select **Enable semantic versioning**\. The name in a buildspec file uses the Shell command language\. For example, you can append a date and time to your artifact name so that it is always unique\. Unique artifact names prevent artifacts from being overwritten\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - + In **Path**, enter a different output artifact path\. - + In **Namespace type**, choose a different type\. Choose **Build ID** to insert the build ID into the path of the build output file \(for example, `My-Path/Build-ID/My-Artifact.zip`\)\. Otherwise, choose **None**\. - + From **Bucket name** choose a different S3 bucket for your output artifacts\. - + If you do not want your build artifacts encrypted, select **Disable artifacts encryption**\. - + Select **Artifacts packaging**, and then choose **Zip** to put the build artifact files in a compressed file\. To put the build artifact files in the specified S3 bucket individually \(not compressed\), choose **None**\. - + Under **Cache**, from **Type**, choose a different cache setting\. - + To override secondary artifacts for this build only: - + To remove a secondary artifact, in **Secondary artifacts**, choose the **X** in its row\. - + To add a secondary artifact, choose **Add artifact**, and then enter the information for your secondary artifact\. For more information, see step 8 in [Create a build project \(console\)](create-project-console.md)\. - - Under **Logs**, you can override your log settings by selecting or clearing **CloudWatch Logs** and **S3 logs**\. - + If you enable **CloudWatch logs**: - + In **Group name**, enter the name of your Amazon CloudWatch Logs group\. - + In **Stream name**, enter your Amazon CloudWatch Logs stream name\. - + If you enable **S3 logs**: - + From **Bucket**, choose the name of the S3 bucket for your logs\. - + In **Path prefix**, enter the prefix for your logs\. - - Under **Service role**, you can change the service role that CodeBuild uses to call dependent AWS services for you\. Choose **Create a role** to have CodeBuild create a service role for you\. - -1. Expand **Environment variables override**\. - - The environment variable list is pre\-populated with the environment variables that are set in the build project\. If you want to change the value of a pre\-populated environment variable for this build only, change the values for **Value** and/or **Type**\. Choose **Add environment variable** to add a new environment variable for this build only\. -**Note** -The **Remove** button cannot be used to remove a pre\-populated environment variable\. The **Remove** button is only used to remove an environment variable added or modified for this build\. - - Others can see an environment variable by using the CodeBuild console and the AWS CLI\. If you have no concerns about the visibility of your environment variable, set the **Name** and **Value** fields, and then set **Type** to **Plaintext**\. - - We recommend that you store an environment variable with a sensitive value, such as an AWS access key ID, an AWS secret access key, or a password as a parameter in Amazon EC2 Systems Manager Parameter Store\. For **Type**, choose **Parameter**\. For **Name**, type an identifier for CodeBuild to reference\. For **Value**, enter the parameter's name as stored in Amazon EC2 Systems Manager Parameter Store\. Using a parameter named `/CodeBuild/dockerLoginPassword` as an example, for **Type**, choose **Parameter**\. For **Name**, enter `LOGIN_PASSWORD`\. For **Value**, enter `/CodeBuild/dockerLoginPassword`\. - - We recommend that you store parameters in Amazon EC2 Systems Manager Parameter Store with parameter names that start with `/CodeBuild/` \(for example, `/CodeBuild/dockerLoginPassword`\)\. You can use the CodeBuild console to create a parameter in Amazon EC2 Systems Manager\. Choose **Create a parameter**, and then follow the instructions\. \(In that dialog box, for **KMS key**, you can optionally specify the ARN of an AWS KMS key in your account\. Amazon EC2 Systems Manager uses this key to encrypt the parameter's value during storage and decrypt during retrieval\.\) If you use the CodeBuild console to create a parameter, the console starts the parameter with `/CodeBuild/` as it is being stored\. For more information, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Walkthrough: Create and test a String parameter \(console\)](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-console.html) in the *Amazon EC2 Systems Manager User Guide*\. - - If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store, the build project's service role must allow the `ssm:GetParameters` action\. If you chose **Create a service role in your account** earlier, then CodeBuild includes this action in the default service role for your build project automatically\. However, if you chose **Choose an existing service role from your account**, then you must include this action in your service role separately\. - - If your build project refers to parameters stored in Amazon EC2 Systems Manager Parameter Store with parameter names that do not start with `/CodeBuild/`, and you chose **Create a service role in your account**, then you must update that service role to allow access to parameter names that do not start with `/CodeBuild/`\. This is because that service role allows access only to parameter names that start with `/CodeBuild/`\. - - Any environment variables you set replace existing environment variables\. For example, if the Docker image already contains an environment variable named `MY_VAR` with a value of `my_value`, and you set an environment variable named `MY_VAR` with a value of `other_value`, then `my_value` is replaced by `other_value`\. Similarly, if the Docker image already contains an environment variable named `PATH` with a value of `/usr/local/sbin:/usr/local/bin`, and you set an environment variable named `PATH` with a value of `$PATH:/usr/share/ant/bin`, then `/usr/local/sbin:/usr/local/bin` is replaced by the literal value `$PATH:/usr/share/ant/bin`\. - - Do not set any environment variable with a name that begins with `CODEBUILD_`\. This prefix is reserved for internal use\. - - If an environment variable with the same name is defined in multiple places, its value is determined as follows: - + The value in the start build operation call takes highest precedence\. - + The value in the build project definition takes next precedence\. - + The value in the buildspec declaration takes lowest precedence\. - -1. Choose **Start build**\. - - For detailed information about this build, see [View build details \(console\)](view-build-details.md#view-build-details-console)\. \ No newline at end of file +For detailed information about this build, see [View build details \(console\)](view-build-details.md#view-build-details-console)\. \ No newline at end of file diff --git a/doc_source/run-build-sdks.md b/doc_source/run-build-sdks.md index 9a83f16..47558b7 100644 --- a/doc_source/run-build-sdks.md +++ b/doc_source/run-build-sdks.md @@ -1,5 +1,5 @@ # Run a build \(AWS SDKs\) -To use CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in [Use CodePipeline with AWS CodeBuild to test code and run builds](how-to-create-pipeline.md) instead\. +To use CodePipeline to run a build with AWS CodeBuild, skip these steps and follow the instructions in [Use AWS CodePipeline with AWS CodeBuild to test code and run builds](how-to-create-pipeline.md) instead\. For information about using CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 2f52ee8..f2a8626 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -5,6 +5,7 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to run a build in Co **Topics** + [Run a build \(console\)](run-build-console.md) + [Run a build \(AWS CLI\)](run-build-cli.md) ++ [Run a batch build \(AWS CLI\)](run-batch-build-cli.md) + [Start running builds automatically \(AWS CLI\)](run-build-cli-auto-start.md) + [Stop running builds automatically \(AWS CLI\)](run-build-cli-auto-stop.md) + [Run a build \(AWS SDKs\)](run-build-sdks.md) \ No newline at end of file diff --git a/doc_source/runtime-versions.md b/doc_source/runtime-versions.md new file mode 100644 index 0000000..bf0d8c8 --- /dev/null +++ b/doc_source/runtime-versions.md @@ -0,0 +1,12 @@ +# Runtime versions + +When you specify a runtime in the [`runtime-versions`](build-spec-ref.md#build-spec.phases.install.runtime-versions) section of your buildspec file, you can specify a specific version, a specific major version and the latest minor version, or the latest version\. The following table lists the available runtimes and how to specify them\. Not all runtime versions are available on all images\. For more information, see [Available runtimes](available-runtimes.md)\. + + +**Ubuntu and Amazon Linux 2 platform runtime versions** +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/runtime-versions.html) + +**Note** +The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the Android Runtime \(ART\)\. + +You can use a build specification to install other components \(for example, the AWS CLI, Apache Maven, Apache Ant, Mocha, RSpec, or similar\) during the `install` build phase\. For more information, see [Buildspec example](build-spec-ref.md#build-spec-ref-example)\. \ No newline at end of file diff --git a/doc_source/sample-access-tokens.md b/doc_source/sample-access-tokens.md deleted file mode 100644 index 6cbfb24..0000000 --- a/doc_source/sample-access-tokens.md +++ /dev/null @@ -1,137 +0,0 @@ -# Use access tokens with your source provider in CodeBuild - - This sample shows you how to connect to GitHub or Bitbucket with an access token\. For GitHub or GitHub Enterprise Server, you use a personal access token\. For Bitbucket, you use an app password\. - -## Access token prerequisites - - Before you begin, you must add the proper permission scopes to your access token\. - - For GitHub, your personal access token must have the following scopes\. -+ **repo**: Grants full control of private repositories\. -+ **repo:status**: Grants access to commit statuses\. -+ **admin:repo\_hook**: Grants full control of repository hooks\. This scope is not required if your token has the `repo` scope\. - -For more information, see [Understanding scopes for OAuth apps](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/) on the GitHub website\. - - For Bitbucket, your app password must have the following scopes\. -+ **repository:read**: Grants read access to all the repositories to which the authorizing user has access\. -+ **pullrequest:read**: Grants read access to pull requests\. If your project has a Bitbucket webhook, then your app password must have this scope\. -+ **webhook**: Grants access to webhooks\. If your project has a webhook operation, then your app password must have this scope\. - -For more information, see [Scopes for Bitbucket Cloud REST API](https://developer.atlassian.com/cloud/bitbucket/bitbucket-cloud-rest-api-scopes/) and [OAuth on Bitbucket Cloud](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) on the Bitbucket website\. - -## Connect source providers with access tokens \(console\) - - To use the console to connect your project to GitHub or Bitbucket using access tokens, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. - -For GitHub: - -1. For **Source provider**, choose **GitHub**\. - -1. For **Repository**, choose **Connect with a GitHub personal access token**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-access-token-console.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. In **GitHub personal access token**, enter your GitHub personal access token\. - -1. Choose **Save token**\. - -For Bitbucket: - -1. For **Source provider**, choose **Bitbucket**\. -**Note** -CodeBuild does not support Bitbucket Server\. - -1. For **Repository**, choose **Connect with a Bitbucket app password**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/bitbucket-access-token-console.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. In **Bitbucket username**, enter your Bitbucket user name\. - -1. In **Bitbucket app password**, enter your Bitbucket app password\. - -1. Choose **Save Bitbucket credentials**\. - -## Connect source providers with access tokens \(CLI\) - -Follow these steps to use the AWS CLI to connect your project to GitHub or Bitbucket using access tokens\. For information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. - -1. Run the import\-source\-credentials command: - - ``` - aws codebuild import-source-credentials --generate-cli-skeleton - ``` - - JSON\-formatted data appears in the output\. Copy the data to a file \(for example, `import-source-credentials.json`\) in a location on the local computer or instance where the AWS CLI is installed\. Modify the copied data as follows, and save your results\. - - ``` - { - "serverType": "server-type", - "authType": "auth-type", - "shouldOverwrite": "should-overwrite", - "token": "token", - "username": "username" - } - ``` - - Replace the following: - + *server\-type*: Required value\. The source provider used for this credential\. Valid values are GITHUB, GITHUB\_ENTERPRISE, and BITBUCKET\. - + *auth\-type*: Required value\. The type of authentication used to connect to a GitHub, GitHub Enterprise Server, or Bitbucket repository\. Valid values include PERSONAL\_ACCESS\_TOKEN and BASIC\_AUTH\. You cannot use the CodeBuild API to create an OAUTH connection\. You must use the CodeBuild console instead\. - + *should\-overwrite*: Optional value\. Set to `false` to prevent overwriting the repository source credentials\. Set to `true` to overwrite the repository source credentials\. The default value is `true`\. - + *token*: Required value\. For GitHub or GitHub Enterprise Server, this is the personal access token\. For Bitbucket, this is the app password\. - + *username*: Optional value\. The Bitbucket user name when authType is BASIC\_AUTH\. This parameter is ignored for other types of source providers or connections\. - -1. To connect your account with an access token, switch to the directory that contains the `import-source-credentials.json` file you saved in step 1 and run the import\-source\-credentials command again\. - - ``` - aws codebuild import-source-credentials --cli-input-json file://import-source-credentials.json - ``` - - JSON\-formatted data appears in the output with an Amazon Resource Name \(ARN\)\. - - ``` - { - "arn": "arn:aws:codebuild:region:account-id:token/server-type" - } - ``` -**Note** - If you run the import\-source\-credentials command with the same server type and auth type a second time, the stored access token is updated\. - - After your account is connected with an access token, you can use `create-project` to create your CodeBuild project\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. - -1. To view the connected access tokens, run the list\-source\-credentials command\. - - ``` - aws codebuild list-source-credentials - ``` - - A JSON\-formatted `sourceCredentialsInfos` object appears in the output: - - ``` - { - "sourceCredentialsInfos": [ - { - "authType": "auth-type", - "serverType": "server-type", - "arn": "arn" - } - ] - } - ``` - - The `sourceCredentialsObject` contains a list of connected source credentials information: - + The `authType` is the type of authentication used by credentials\. This can be `OAUTH`, `BASIC_AUTH`, or `PERSONAL_ACCESS_TOKEN`\. - + The `serverType` is the type of source provider\. This can be `GITHUB`, `GITHUB_ENTERPRISE`, or `BITBUCKET`\. - + The `arn` is the ARN of the token\. - -1. To disconnect from a source provider and remove its access tokens, run the delete\-source\-credentials command with its ARN\. - - ``` - aws codebuild delete-source-credentials --arn arn-of-your-credentials - ``` - - JSON\-formatted data is returned with an ARN of the deleted credentials\. - - ``` - { - "arn": "arn:aws:codebuild:region:account-id:token/server-type" - } - ``` \ No newline at end of file diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 15f946c..b458484 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -1,12 +1,16 @@ # Bitbucket pull request and webhook filter sample for CodeBuild +AWS CodeBuild supports webhooks when the source repository is Bitbucket\. This means that for a CodeBuild build project that has its source code stored in a Bitbucket repository, webhooks can be used to rebuild the source code every time a code change is pushed to the repository\. For more information, see [](bitbucket-webhook.md)\. + This sample shows you how to create a pull request using a Bitbucket repository\. It also shows you how to use a Bitbucket webhook to trigger CodeBuild to create a build of a project\. +**Note** +When using webhooks, it is possible for a user to trigger an unexpected build\. To mitigate this risk, see [Best practices for using webhooks](webhooks.md#webhook-best-practices)\. + **Topics** + [Prerequisites](#sample-bitbucket-pull-request-prerequisites) + [Create a build project with Bitbucket as the source repository and enable webhooks](#sample-bitbucket-pull-request-create) + [Trigger a build with a Bitbucket webhook](#sample-bitbucket-pull-request-trigger) -+ [Filter Bitbucket webhook events](#sample-bitbucket-pull-request-filter-webhook-events) ## Prerequisites @@ -23,280 +27,90 @@ This sample shows you how to create a pull request using a Bitbucket repository\ 1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. -1. On the **Create build project** page, in **Project configuration**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. +1. Choose **Create build project**\. -1. In **Source**, for **Source provider**, choose **Bitbucket**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/bitbucket-pr-sample-source.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - - Follow the instructions to connect or reconnect, and then choose **Grant access**\. -**Note** -CodeBuild does not support Bitbucket Server\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/bitbucket-webhook-prerequisite.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. In **Project configuration**: +**Project name** +Enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. -1. Choose **Use a repository in my account**\. You cannot use a webhook if you use a public Bitbucket repository\. +1. In **Source**: +**Source provider** +Choose **Bitbucket**\. Follow the instructions to connect \(or reconnect\) with Bitbucket and then choose **Authorize**\. +**Repository** +Choose **Repository in my Bitbucket account**\. +If you have not previously connected to your Bitbucket account, enter your Bitbucket username and app password, and select **Save Bitbucket credentials**\. +**Bitbucket repository** +Enter the URL for your Bitbucket repository\. -1. In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository**\. You can select this check box only if you chose **Repository in my Bitbucket account**\. +1. In **Primary source webhook events**, select the following\. **Note** - If a build is triggered by a Bitbucket webhook, the **Report build status** setting is ignored\. The build status is always sent to Bitbucket\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-pr-webhook.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. Choose other settings for your project\. For more information about source provider options and settings, see [Choose source provider](create-project-console.md#create-project-source-provider)\. - -1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. - -## Trigger a build with a Bitbucket webhook +The **Primary source webhook events** section is only visible if you chose **Repository in my Bitbucket account** in the previous step\. - For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code\. + 1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. On the navigation pane, choose **Build projects**, and then choose a project associated with a Bitbucket repository with webhooks\. For information about creating a Bitbucket webhook project, see [Create a build project with Bitbucket as the source repository and enable webhooks](#sample-bitbucket-pull-request-create)\. - -1. Make some changes in the code in your project's Bitbucket repository\. - -1. Create a pull request on your Bitbucket repository\. For more information, see [Making a pull request](https://www.atlassian.com/git/tutorials/making-a-pull-request)\. + 1. From **Event type**, choose one or more events\. -1. On the Bitbucket webhooks page, choose **View request** to see a list of recent events\. + 1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters\. -1. Choose **View details** to see details about the response returned by CodeBuild\. It might look something like this: + 1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters\. - ``` - "response":"Webhook received and buld started: https://us-east-1.console.aws.amazon.com/codebuild/home..." - "statusCode":200 - ``` + 1. Choose **Add filter group** to add another filter group, if needed\. -1. Navigate to the Bitbucket pull request page to see the status of the build\. + For more information about Bitbucket webhook event types and filters, see [Bitbucket webhook events](bitbucket-webhook.md)\. -## Filter Bitbucket webhook events +1. In **Environment**: +**Environment image** +Choose one of the following: +To use a Docker image managed by AWS CodeBuild: +Choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. +To use another Docker image: +Choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. +To use a private Docker image: +Choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. +**Service role** +Choose one of the following: + + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. + + If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. +When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. - You can use webhook filter groups to specify which Bitbucket webhook events trigger a build\. For example, you can specify that a build is triggered for specified branches only\. +1. In **Buildspec**, do one of the following: + + Choose **Use a buildspec file** to use the buildspec\.yml file in the source code root directory\. + + Choose **Insert build commands** to use the console to insert build commands\. - You can specify more than one webhook filter group\. A build is triggered if the filters on one or more filter groups evaluate to true\. When you create a filter group, you specify: -+ An event\. For Bitbucket, you can choose one or more of the following events: `PUSH`, `PULL_REQUEST_CREATED`, `PULL_REQUEST_UPDATED`, and `PULL_REQUEST_MERGED`\. The webhook's event type is in its header in the `X-Event-Key` field\. The following table shows how `X-Event-Key` header values map to the event types\. -**Note** -You must enable the `merged` event in your Bitbucket webhook setting if you create a webhook filter group that uses the `PULL_REQUEST_MERGED` event type\. -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html) -+ One or more optional filters\. Use a regular expression to specify a filter\. For an event to trigger a build, every filter associated with it must evaluate to true\. - + `ACTOR_ACCOUNT_ID` \(`ACTOR_ID` in the console\): A webhook event triggers a build when a Bitbucket account ID matches the regular expression pattern\. This value appears in the `account_id` property of the `actor` object in the webhook filter payload\. - + `HEAD_REF`: A webhook event triggers a build when the head reference matches the regular expression pattern \(for example, `refs/heads/branch-name` and `refs/tags/tag-name`\)\. A `HEAD_REF` filter evaluates the Git reference name for the branch or tag\. The branch or tag name appears in the `name` field of the `new` object in the `push` object of the webhook payload\. For pull request events, the branch name appears in the `name` field in the `branch` object of the `source` object in the webhook payload\. - + `BASE_REF`: A webhook event triggers a build when the base reference matches the regular expression pattern\. A `BASE_REF` filter works with pull request events only \(for example, `refs/heads/branch-name`\)\. A `BASE_REF` filter evaluates the Git reference name for the branch\. The branch name appears in the `name` field of the `branch` object in the `destination` object in the webhook payload\. - + `FILE_PATH`: A webhook triggers a build when the path of a changed file matches the regular expression pattern\. - + `COMMIT_MESSAGE`: A webhook triggers a build when the head commit message matches the regular expression pattern\. + For more information, see the [Buildspec reference](build-spec-ref.md)\. -**Note** - You can find the webhook payload in the webhook settings of your Bitbucket repository\. +1. In **Artifacts**: +**Type** +Choose one of the following: + + If you do not want to create build output artifacts, choose **No artifacts**\. + + To store the build output in an S3 bucket, choose **Amazon S3**, and then do the following: + + If you want to use your project name for the build output ZIP file or folder, leave **Name** blank\. Otherwise, enter the name\. By default, the artifact name is the project name\. If you want to use a different name, enter it in the artifacts name box\. If you want to output a ZIP file, include the zip extension\. + + For **Bucket name**, choose the name of the output bucket\. + + If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter the locations of the files from the build that you want to put into the build output ZIP file or folder\. For multiple locations, separate each location with a comma \(for example, `appspec.yml, target/my-app.jar`\)\. For more information, see the description of `files` in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. +**Additional configuration** +Expand **Additional configuration** and set options as appropriate\. -**Topics** -+ [Filter Bitbucket webhook events \(console\)](#sample-bitbucket-pull-request-filter-webhook-events-console) -+ [Filter Bitbucket webhook events \(SDK\)](#sample-bitbucket-pull-request-filter-webhook-events-sdk) -+ [Filter Bitbucket webhook events \(AWS CloudFormation\)](#sample-bitbucket-pull-request-filter-webhook-events-cfn) - -### Filter Bitbucket webhook events \(console\) - - To use the AWS Management Console to filter webhook events: - -1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. - -1. From **Event type**, choose one or more events\. - -1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters\. - -1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters\. - -1. Choose **Add filter group** to add another filter group\. - - For more information, see [Create a build project \(console\)](create-project-console.md) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. - -In this example, a webhook filter group triggers a build for pull requests only: +1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +## Trigger a build with a Bitbucket webhook -Using an example of two filter groups, a build is triggered when one or both evaluate to true: -+ The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/master$` and head references that match `^refs/heads/branch1!`\. -+ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`\. +For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. -In this example, a webhook filter group triggers a build for all requests except tag events\. +1. On the navigation pane, choose **Build projects**, and then choose a project associated with a Bitbucket repository with webhooks\. For information about creating a Bitbucket webhook project, see [Create a build project with Bitbucket as the source repository and enable webhooks](#sample-bitbucket-pull-request-create)\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. Make some changes in the code in your project's Bitbucket repository\. -In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change\. +1. Create a pull request on your Bitbucket repository\. For more information, see [Making a pull request](https://www.atlassian.com/git/tutorials/making-a-pull-request)\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +1. On the Bitbucket webhooks page, choose **View request** to see a list of recent events\. -In this example, a webhook filter group triggers a build only when a change is made by a Bitbucket user who does not have an account ID that matches the regular expression `actor-account-id`\. +1. Choose **View details** to see details about the response returned by CodeBuild\. It might look something like this: -**Note** - For information about how to find your Bitbucket account ID, see https://api\.bitbucket\.org/2\.0/users/*user\-name*, where *user\-name* is your Bitbucket user name\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-bitbucket.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -### Filter Bitbucket webhook events \(SDK\) - - To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods\. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*\. - - To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" - } - ] -] -``` - - To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names\. Using an example of two filter groups, a build is triggered when one or both evaluate to true: -+ The first filter group specifies pull requests that are created or updated on branches with Git reference names that match the regular expression `^refs/heads/master$` and head references that match `^refs/heads/myBranch$`\. -+ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/heads/myBranch$" - }, - { - "type": "BASE_REF", - "pattern": "^refs/heads/master$" - } - ], - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/heads/myBranch$" - } - ] -] -``` - - You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build\. In this example, a build is triggered for all requests except tag events\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/tags/.*", - "excludeMatchedPattern": true - } - ] -] -``` - -You can create a filter that triggers a build only when a change is made by a Bitbucket user with account ID `actor-account-id`\. + ``` + "response":"Webhook received and build started: https://us-east-1.console.aws.amazon.com/codebuild/home..." + "statusCode":200 + ``` -**Note** - For information about how to find your Bitbucket account ID, see https://api\.bitbucket\.org/2\.0/users/*user\-name*, where *user\-name* is your Bitbucket user name\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" - }, - { - "type": "ACTOR_ACCOUNT_ID", - "pattern": "actor-account-id" - } - ] -] -``` - -You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change\. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "FILE_PATH", - "pattern": "^buildspec.*" - } - ] -] -``` - -You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument\. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`\. - -``` - "filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "COMMIT_MESSAGE", - "pattern": "\[CodeBuild\]" - } - ] - ] -``` - -### Filter Bitbucket webhook events \(AWS CloudFormation\) - - To use an AWS CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property\. The following YAML\-formatted portion of an AWS CloudFormation template creates two filter groups\. Together, they trigger a build when one or both evaluate to true: -+ The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/master$` by a Bitbucket user who does not have account ID `12345`\. -+ The second filter group specifies push requests are created on branches with Git reference names that match the regular expression `^refs/heads/.*`\. -+ The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`\. - -``` -CodeBuildProject: - Type: AWS::CodeBuild::Project - Properties: - Name: MyProject - ServiceRole: service-role - Artifacts: - Type: NO_ARTIFACTS - Environment: - Type: LINUX_CONTAINER - ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:4.0 - Source: - Type: BITBUCKET - Location: source-location - Triggers: - Webhook: true - FilterGroups: - - - Type: EVENT - Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - - Type: BASE_REF - Pattern: ^refs/heads/master$ - ExcludeMatchedPattern: false - - Type: ACTOR_ACCOUNT_ID - Pattern: 12345 - ExcludeMatchedPattern: true - - - Type: EVENT - Pattern: PUSH - - Type: HEAD_REF - Pattern: ^refs/heads/.* - - - Type: EVENT - Pattern: PUSH - - Type: COMMIT_MESSAGE - - Pattern: \[CodeBuild\] -``` \ No newline at end of file +1. Navigate to the Bitbucket pull request page to see the status of the build\. \ No newline at end of file diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 33d0546..9c4729d 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -8,7 +8,7 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, 1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. -1. On the **Create build project** page, in **Project configuration**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. +1. In **Project name**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. 1. In **Source**, for **Source provider**, choose the source code provider type, and then do one of the following: **Note** @@ -24,7 +24,7 @@ Updating your project source might affect the accuracy of the project's build ba For **Environment image**, do one of the following: + To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. - + To use private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. + + To use a private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. 1. In **Service role**, do one of the following: + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. @@ -32,7 +32,7 @@ Updating your project source might affect the accuracy of the project's build ba **Note** When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. -1. For **Buildspec**, do one of the following: +1. In **Buildspec**, do one of the following: + Choose **Use a buildspec file** to use the buildspec\.yml file in the source code root directory\. + Choose **Insert build commands** to use the console to insert build commands\. @@ -59,17 +59,24 @@ You can use AWS CodeBuild console or the AWS CLI to access build badges\. + In the CodeBuild console, in the list of build projects, in the **Name** column, choose the link that corresponds to the build project\. On the **Build project: *project\-name*** page, in **Configuration**, choose **Copy badge URL**\. For more information, see [View a build project's details \(console\)](view-project-details.md#view-project-details-console)\. + In the AWS CLI, run the `batch-get-projects` command\. The build badge URL is included in the project environment details section of the output\. For more information, see [View a build project's details \(AWS CLI\)](view-project-details.md#view-project-details-cli)\. -**Important** -The build badge request URL is for the master branch, but you can specify any branch in your source repository that you have used to run a build\. +The build badge request URL is generated with a common default branch, but you can specify any branch in your source repository that you have used to run a build\. For example: -## Publish your CodeBuild build badges +``` +https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch= +``` + +You can also specify a tag from your source repository by substituting the `branch` parameter with the `tag` parameter in the badge URL\. For example: -You can include your build badge request URL in a markdown file in your preferred repository \(for example, GitHub or CodeCommit\) to display the status of the latest build\. +``` +https://codebuild.us-east-1.amazon.com/badges?uuid=...&tag= +``` + +## Publish your CodeBuild build badges -Sample markdown code: +You can display the status of the latest build in a markdown file using your build badge URL in a markdown image\. This is useful to display the status of the most recent build in the readme\.md file in your source repository \(for example, GitHub or CodeCommit\)\. For example: ``` -![Build Status](https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch=master) +![]() ``` ## CodeBuild badge statuses diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index e891fed..2511b02 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -49,9 +49,13 @@ For more information, see [Editing customer managed policies](https://docs.aws.a 1. Choose **Create topic**\. - 1. On the **Topic details: CodeBuildDemoTopic** page, copy the **Topic ARN** value\. You need this value for the next step\. + 1. On the **Topic details: CodeBuildDemoTopic** page, copy the **Topic ARN** value\. You need this value for the next step\. + + ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/topic-arn.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + For more information, see [Create a topic](https://docs.aws.amazon.com/sns/latest/dg/CreateTopic.html) in the *Amazon SNS Developer Guide*\. 1. Subscribe one or more recipients to the topic to receive email notifications\. @@ -64,9 +68,13 @@ For more information, see [Editing customer managed policies](https://docs.aws.a 1. For **Protocol**, choose **Email**\. - 1. For **Endpoint**, enter the recipient's full email address\. + 1. For **Endpoint**, enter the recipient's full email address\. + + ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-subscription.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + 1. Choose **Create Subscription**\. 1. Amazon SNS sends a subscription confirmation email to the recipient\. To begin receiving email notifications, the recipient must choose the **Confirm subscription** link in the subscription confirmation email\. After the recipient clicks the link, if successfully subscribed, Amazon SNS displays a confirmation message in the recipient's web browser\. @@ -115,9 +123,6 @@ For more information, see [Editing customer managed policies](https://docs.aws.a } ``` - Compare your results: -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-rule.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - 1. Choose **Edit** and replace the code in **Event Pattern Preview** with one of the following two rule patterns\. This first rule pattern triggers an event when a build starts or completes for the specified build projects in AWS CodeBuild\. @@ -197,6 +202,10 @@ For more information, see [Editing customer managed policies](https://docs.aws.a + To trigger events only for individual build phase status changes, remove the name of each build phase status in the `completed-phase-status` array that you do not want to trigger an event for\. + To trigger events for all build projects, remove the `project-name` array\. + To trigger events for individual build projects, specify the name of each build project in the `project-name` array\. + + For more information about event patterns, see [Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/filtering-examples-structure.html) in the Amazon EventBridge User Guide\. + + For more information about filtering with event patterns, see [Content\-based Filtering with Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/content-filtering-with-event-patterns.html) in the Amazon EventBridge User Guide\. **Note** If you want to trigger events for both build state changes and build phase changes, you must create two separate rules: one for build state changes and another for build phase changes\. If you try to combine both rules into a single rule, the combined rule might produce unexpected results or stop working altogether\. @@ -240,19 +249,13 @@ If you want to trigger events for both build state changes and build phase chang "Build '' for build project '' has completed the build phase of '' with a status of ''." ``` - Compare your results so far to the following, which shows a rule with a `detail-type` value of `CodeBuild Build State Change`: -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-rule-2.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - 1. Choose **Configure details**\. 1. On the **Step 2: Configure rule details** page, enter a name and an optional description\. For **State**, leave **Enabled** selected\. - Compare your results so far to the following screen shot: -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-rule-3.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - 1. Choose **Create rule**\. -1. Create build projects, run the builds, and view build information by following the steps in [Run AWS CodeBuild directly](how-to-run.md)\. +1. Create build projects, run the builds, and view build information by following the steps in [Run CodeBuild directly](how-to-run.md)\. 1. Confirm that CodeBuild is now successfully sending build notifications\. For example, check to see if the build notification emails are now in your inbox\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 795a890..69acaf5 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -17,28 +17,28 @@ Running this sample might result in charges to your AWS account\. These include mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false ``` - If successful, this directory structure and files is created\. + If successful, this directory structure and files are created\. ``` - (root directory name) - `-- my-app - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- com - | `-- mycompany - | `-- app - | `-- App.java - `-- test - `-- java - `-- com - `-- mycompany - `-- app - `-- AppTest.java + . + └── my-app + ├── pom.xml + └── src + ├── main + │ └── java + │ └── com + │ └── mycompany + │ └── app + │ └── App.java + └── test + └── java + └── com + └── mycompany + └── app + └── AppTest.java ``` -1. Create a file with this content\. Name the file `buildspec.yml`, and then add it to the `(root directory name)/my-app` directory\. +1. Create a file with this content\. Name the file `buildspec.yml`, and then add it to the `my-app` directory\. ``` version: 0.2 @@ -62,7 +62,7 @@ Running this sample might result in charges to your AWS account\. These include discard-paths: yes ``` -1. Create a file with this content\. Name the file `appspec.yml`, and then add it to the `(root directory name)/my-app` directory\. +1. Create a file with this content\. Name the file `appspec.yml`, and then add it to the `my-app` directory\. ``` version: 0.0 @@ -75,49 +75,50 @@ Running this sample might result in charges to your AWS account\. These include When finished, your directory structure and file should look like this\. ``` - (root directory name) - `-- my-app - |-- buildspec.yml - |-- appspec.yml - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- com - | `-- mycompany - | `-- app - | `-- App.java - `-- test - `-- java - `-- com - `-- mycompany - `-- app - ` -- AppTest.java + . + └── my-app + ├── buildspec.yml + ├── appspec.yml + ├── pom.xml + └── src + ├── main + │ └── java + │ └── com + │ └── mycompany + │ └── app + │ └── App.java + └── test + └── java + └── com + └── mycompany + └── app + └── AppTest.java ``` -1. Create a ZIP file that contains the directory structure and files inside of `(root directory name)/my-app`, and then upload the ZIP file to a source code repository type supported by AWS CodeBuild and CodeDeploy, such as an S3 input bucket or a GitHub or Bitbucket repository\. +1. Create a ZIP file that contains the directory structure and files inside of `my-app`, and then upload the ZIP file to a source code repository type supported by AWS CodeBuild and CodeDeploy, such as an S3 input bucket or a GitHub or Bitbucket repository\. **Important** If you want to use CodePipeline to deploy the resulting build output artifact, you cannot upload the source code to a Bitbucket repository\. -Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP file, just the directories and files inside of `(root directory name)/my-app`\. The ZIP file should contain these directories and files: +Do not add `my-app` to the ZIP file, just the directories and files inside of `my-app`\. The ZIP file should contain these directories and files: ``` - CodeDeploySample.zip - |--buildspec.yml - |-- appspec.yml - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- com - | `-- mycompany - | `-- app - | `-- App.java - `-- test - `-- java - `-- com - `-- mycompany - `-- app - ` -- AppTest.java + . + └── CodeDeploySample.zip + ├── buildspec.yml + ├── appspec.yml + ├── pom.xml + └── src + ├── main + │ └── java + │ └── com + │ └── mycompany + │ └── app + │ └── App.java + └── test + └── java + └── com + └── mycompany + └── app + └── AppTest.java ``` 1. Create a build project by following the steps in [Create a build project](create-project.md)\. @@ -162,7 +163,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP To deploy with CodeDeploy, see [Deploying a revision with CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-deploy-revision.html) in the *AWS CodeDeploy User Guide*\. - To deploy with CodePipeline, see [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. + To deploy with CodePipeline, see [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. 1. To find the build output artifact after the deployment is complete, sign in to the instance and look in the `/tmp` directory for the file named `my-app-1.0-SNAPSHOT.jar`\. diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index f2ba604..05752c0 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -8,7 +8,7 @@ 1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. -1. On the **Create build project** page, in **Project configuration**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. +1. In **Project name**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. 1. In **Source**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub, and then choose **Authorize**\. @@ -20,7 +20,7 @@ For **Environment image**, do one of the following: + To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. - + To use private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. + + To use a private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. 1. In **Service role**, do one of the following: + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. @@ -28,7 +28,7 @@ **Note** When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. -1. For **Buildspec**, do one of the following: +1. In **Buildspec**, do one of the following: + Choose **Use a buildspec file** to use the buildspec\.yml file in the source code root directory\. + Choose **Insert build commands** to use the console to insert build commands\. diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index ac74700..8bea6e3 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -24,7 +24,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. Create a build project, run the build, and view related build information by following the steps in [Run AWS CodeBuild directly](how-to-run.md)\. - If you use the AWS CLI to create the build project, the JSON\-formatted input to the`create-project` command might look similar to this\. \(Replace the placeholders with your own values\.\) + If you use the AWS CLI to create the build project, the JSON\-formatted input to the `create-project` command might look similar to this\. \(Replace the placeholders with your own values\.\) ``` { @@ -57,8 +57,8 @@ This sample assumes this directory structure\. ``` (root directory name) - |-- buildspec.yml - `-- Dockerfile +├── buildspec.yml +└── Dockerfile ``` ## Files @@ -73,7 +73,7 @@ version: 0.2 phases: install: commands: - - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2& + - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout 15 sh -c "until docker info; do echo .; sleep 1; done" pre_build: commands: diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 3884774..5039dcc 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -78,7 +78,7 @@ The IAM entity that modifies this policy must have permission in IAM to modify p Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket\. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`\. -1. Follow the steps in [Run AWS CodeBuild directly](how-to-run.md) to create a build project, run the build, and view build information\. +1. Follow the steps in [Run CodeBuild directly](how-to-run.md) to create a build project, run the build, and view build information\. If you use the console to create your project: @@ -151,8 +151,8 @@ This sample assumes this directory structure\. ``` (root directory name) - |-- buildspec.yml - `-- Dockerfile +├── buildspec.yml +└── Dockerfile ``` ## Files @@ -161,9 +161,6 @@ This sample uses these files\. `buildspec.yml` \(in `(root directory name)`\) -**Note** -If you are using a version of Docker earlier than 17\.06, remove the `--no-include-email` option\. - ``` version: 0.2 @@ -171,7 +168,7 @@ phases: pre_build: commands: - echo Logging in to Amazon ECR... - - $(aws ecr get-login --no-include-email --region $AWS_DEFAULT_REGION) + - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com build: commands: - echo Build started on `date` @@ -203,6 +200,9 @@ COPY --from=build /bin/HelloWorld /bin/HelloWorld ENTRYPOINT ["/bin/HelloWorld"] ``` +**Note** +CodeBuild overrides the `ENTRYPOINT` for custom Docker images\. + ## Adapting the sample to push the image to Docker Hub To push the Docker image to Docker Hub instead of Amazon ECR, edit this sample's code\. @@ -216,7 +216,7 @@ If you are using a version of Docker earlier than 17\.06, remove the `--no-inclu pre_build: commands: - echo Logging in to Amazon ECR... - - $(aws ecr get-login --no-include-email --region $AWS_DEFAULT_REGION) + - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com build: commands: - echo Build started on `date` @@ -300,7 +300,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains ... ``` -1. Follow the steps in [Run AWS CodeBuild directly](how-to-run.md) to create a build environment, run the build, and view related build information\. +1. Follow the steps in [Run CodeBuild directly](how-to-run.md) to create a build environment, run the build, and view related build information\. 1. Confirm that AWS CodeBuild successfully pushed the Docker image to the repository\. Sign in to Docker Hub, go to the repository, and choose the **Tags** tab\. The `latest` tag should contain a very recent **Last Updated** value\. diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index af085d8..a18922a 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -20,7 +20,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. Create a build project, run the build, and view related build information by following the steps in [Run AWS CodeBuild directly](how-to-run.md)\. - If you use the AWS CLI to create the build project, the JSON\-formatted input to the`create-project` command might look similar to this\. \(Replace the placeholders with your own values\.\) + If you use the AWS CLI to create the build project, the JSON\-formatted input to the `create-project` command might look similar to this\. \(Replace the placeholders with your own values\.\) ``` { @@ -71,6 +71,17 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. For **Action**, select the pull\-only actions: **ecr:GetDownloadUrlForLayer**, **ecr:BatchGetImage**, and **ecr:BatchCheckLayerAvailability**\. + 1. For **Conditions**, add the following: + + ``` + { + "StringEquals":{ + "aws:SourceAccount":"", + "aws:SourceArn":"arn:aws:codebuild:::project/" + } + } + ``` + 1. Choose **Save**\. This policy is displayed in **Permissions**\. The principal is what you entered for **Principal** in step 3 of this procedure: @@ -79,6 +90,45 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains The following sample policy uses both CodeBuild credentials and a cross\-account Amazon ECR image\. + ``` + { + "Version":"2012-10-17", + "Statement":[ + { + "Sid":"CodeBuildAccessPrincipal", + "Effect":"Allow", + "Principal":{ + "Service":"codebuild.amazonaws.com" + }, + "Action":[ + "ecr:GetDownloadUrlForLayer", + "ecr:BatchGetImage", + "ecr:BatchCheckLayerAvailability" + ], + "Condition":{ + "StringEquals":{ + "aws:SourceArn":"arn:aws:codebuild:::project/", + "aws:SourceAccount":"" + } + } + }, + { + "Sid":"CodeBuildAccessCrossAccount", + "Effect":"Allow", + "Principal":{ + "AWS":"arn:aws:iam:::root" + }, + "Action":[ + "ecr:GetDownloadUrlForLayer", + "ecr:BatchGetImage", + "ecr:BatchCheckLayerAvailability" + ] + } + ] + } + ``` + + If your projects use CodeBuild credentials and you would like your CodeBuild projects to have open access to the Amazon ECR repository, you can omit the `Condition` keys and add the following sample policy\. + ``` { "Version":"2012-10-17", @@ -111,7 +161,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains } ``` -1. Create a build project, run the build, and view build information by following the steps in [Run AWS CodeBuild directly](how-to-run.md)\. +1. Create a build project, run the build, and view build information by following the steps in [Run CodeBuild directly](how-to-run.md)\. If you use the AWS CLI to create the build project, the JSON\-formatted input to the `create-project` command might look similar to this\. \(Replace the placeholders with your own values\.\) @@ -130,7 +180,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains }, "environment": { "type": "LINUX_CONTAINER", - "image": "account-ID.dkr.ecr.region-ID.amazonaws.com/your-Amazon-ECR-repo-name:latest", + "image": "account-ID.dkr.ecr.region-ID.amazonaws.com/your-Amazon-ECR-repo-name:tag", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "arn:aws:iam::account-ID:role/role-name", @@ -148,8 +198,8 @@ This sample assumes this directory structure\. ``` (root directory name) - |-- buildspec.yml - `-- hello.go +├── buildspec.yml +└── hello.go ``` ## Go project files diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 1ba07a4..16b1be4 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -23,6 +23,8 @@ Data in transit for your file system is encrypted\. To encrypt data in transit u **Note** A file system created in Amazon EFS is supported on Linux platforms only\. + + ## Create a VPC using AWS CloudFormation Create your VPC with an AWS CloudFormation template\. @@ -59,6 +61,8 @@ Data in transit for your file system is encrypted\. To encrypt data in transit u 1. Choose **Create File System**\. +1. \(Optional\) We recommend adding a policy to your Amazon EFS file system that enforces encryption of data in transit\. In the Amazon EFS console, choose **File system policy**, choose **Edit**, select the box labeled **Enforce in\-transit encryption for all clients**, and then choose **Save**\. + ## Create a CodeBuild project to use with Amazon EFS Create a AWS CodeBuild project that uses the VPC you created earlier in this sample\. When the build is run, it mounts the Amazon EFS file system created earlier\. Next, it stores the \.jar file created by your Java application in your file system's mount point directory\. @@ -98,15 +102,26 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 1. From **Security Groups**, choose the default security group\. 1. In **File systems**, enter the following information: - + For **Identifier**, enter a unique file system identifier\. It must be fewer than 129 characters and contain only alphanumeric characters and underscores\. CodeBuild uses this identifier to create an environment variable that identifies the elastic file system\. The environment variable format is `CODEBUILD_file-system-identifier` in capital letters\. For example, if you enter **efs\-1**, the environment variable is `CODEBUILD_EFS-1`\. - + For **ID**, choose the file system ID\. - + \(Optional\) Enter a directory in the file system\. CodeBuild mounts this directory\. If you leave **Directory path** blank, CodeBuild mounts the entire file system\. The path is relative to the root of the file system\. - + For **Mount point**, enter the absolute path of the directory in your build container where the file system is mounted\. If this directory does not exist, CodeBuild creates it during the build\. - + \(Optional\) Enter mount options\. If you leave **Mount options** blank, CodeBuild uses its default mount options \(`nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2`\)\. For more information, see [Recommended NFS Mount Options](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs-nfs-mount-settings.html) in the *Amazon Elastic File System User Guide*\. + + For **Identifier**, enter a unique file system identifier\. It must be fewer than 129 characters and contain only alphanumeric characters and underscores\. CodeBuild uses this identifier to create an environment variable that identifies the elastic file system\. The environment variable format is `CODEBUILD_` in capital letters\. For example, if you enter `my_efs`, the environment variable is `CODEBUILD_MY_EFS`\. + + For **ID**, choose the file system ID\. + + \(Optional\) Enter a directory in the file system\. CodeBuild mounts this directory\. If you leave **Directory path** blank, CodeBuild mounts the entire file system\. The path is relative to the root of the file system\. + + For **Mount point**, enter the absolute path of the directory in your build container where the file system is mounted\. If this directory does not exist, CodeBuild creates it during the build\. + + \(Optional\) Enter mount options\. If you leave **Mount options** blank, CodeBuild uses its default mount options: + + ``` + nfsvers=4.1 + rsize=1048576 + wsize=1048576 + hard + timeo=600 + retrans=2 + ``` + + For more information, see [Recommended NFS Mount Options](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs-nfs-mount-settings.html) in the *Amazon Elastic File System User Guide*\. 1. For **Build specification**, choose **Insert build commands**, and then choose **Switch to editor**\. -1. Enter the following buildspec commands into the editor\. Replace `file-system-identifier` with the identifier you entered in step 17\. Use capital letters \(for example, `CODEBUILD_EFS-1`\)\. +1. Enter the following build spec commands into the editor\. Replace `` with the identifier you entered in step 17\. Use capital letters \(for example, `CODEBUILD_MY_EFS`\)\. ``` version: 0.2 @@ -116,7 +131,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo java: corretto11 build: commands: - - mvn compile -Dgpg.skip=true -Dmaven.repo.local=$CODEBUILD_file-system-identifier + - mvn compile -Dgpg.skip=true -Dmaven.repo.local=$CODEBUILD_ ``` 1. Use the default values for all other settings, and then choose **Create build project**\. When your build is complete, the console page for your project is displayed\. @@ -125,8 +140,39 @@ By default, Docker containers do not allow access to any devices\. Privileged mo ## CodeBuild and Amazon EFS sample summary + + After your AWS CodeBuild project is built: + You have a \.jar file created by your Java application that is built to your Amazon EFS file system under your mount point directory\. + An environment variable that identifies your file system is created using the file system identifier you entered when you created the project\. - For more information, see [Mounting file systems](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs.html) in the *Amazon Elastic File System User Guide*\. \ No newline at end of file + For more information, see [Mounting file systems](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs.html) in the *Amazon Elastic File System User Guide*\. + +## Troubleshooting + +The following are errors you might encounter when setting up Amazon EFS with CodeBuild\. + +**Topics** ++ [CLIENT\_ERROR: mounting '127\.0\.0\.1:/' failed\. permission denied](#sample-efs-troubleshooting.permission-denied) ++ [CLIENT\_ERROR: mounting '127\.0\.0\.1:/' failed\. connection reset by peer](#sample-efs-troubleshooting.connection-reset) ++ [VPC\_CLIENT\_ERROR: Unexpected EC2 error: UnauthorizedOperation](#sample-efs-troubleshooting.unauthorized-operation) + +### CLIENT\_ERROR: mounting '127\.0\.0\.1:/' failed\. permission denied + +IAM authorization is not supported for mounting Amazon EFS with CodeBuild\. If you are using a custom Amazon EFS file system policy, you will need to grant read and write access to all IAM principals\. For example: + +``` +"Principal": { + "AWS": "*" +} +``` + +### CLIENT\_ERROR: mounting '127\.0\.0\.1:/' failed\. connection reset by peer + +There are two possible causes for this error: ++ The CodeBuild VPC subnet is in a different availability zone than the Amazon EFS mount target\. You can resolve this by adding a VPC subnet in the same availability zone as the Amazon EFS mount target\. ++ The security group does not have permissions to communicate with Amazon EFS\. You can resolve this by adding an inbound rule to allow all traffic from either the VPC \(add the primary CIDR block for your VPC\), or the security group itself\. + +### VPC\_CLIENT\_ERROR: Unexpected EC2 error: UnauthorizedOperation + +This error occurs when all of the subnets in your VPC configuration for the CodeBuild project are public subnets\. You must have at least one private subnet in the VPC to ensure network connectivity\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 49e8aff..660f230 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -1,6 +1,6 @@ # AWS Elastic Beanstalk sample for CodeBuild -This sample instructs AWS CodeBuild to use Maven to produce as build output a single WAR file named `my-web-app.war`\. This sample then deploys the WAR file to the instances in an AWS Elastic Beanstalk environment\. +This sample uses AWS CodeBuild with Maven to produce a single WAR file named `ROOT.war` as the build output\. This sample then deploys the WAR file to the instances in an AWS Elastic Beanstalk environment\. **Important** Running this sample might result in charges to your AWS account\. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon EC2\. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon EC2 pricing](http://aws.amazon.com/ec2/pricing)\. @@ -14,30 +14,30 @@ In this section, you use Maven to produce the source code\. Later, you use CodeB 1. Switch to an empty directory on your local computer or instance, and then run this Maven command\. ``` - mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-web-app -DarchetypeArtifactId=maven-archetype-webapp -DinteractiveMode=false + mvn archetype:generate "-DgroupId=com.mycompany.app" "-DartifactId=ROOT" "-DarchetypeArtifactId=maven-archetype-webapp" "-DinteractiveMode=false" ``` If successful, this directory structure and files are created\. ``` - (root directory name) - `-- my-web-app - |-- pom.xml - `-- src - `-- main - |-- resources - `-- webapp - |-- WEB-INF - | `-- web.xml - `-- index.jsp + . + └── ROOT + ├── pom.xml + └── src + └── main + ├── resources + └── webapp + ├── WEB-INF + │ └── web.xml + └── index.jsp ``` -1. Create a subdirectory named `.ebextensions` in the `(root directory name)/my-web-app` directory\. In the `.ebextensions` subdirectory, create a file named `fix-path.config` with this content\. +1. Create a subdirectory named `.ebextensions` in the `ROOT` directory\. In the `.ebextensions` subdirectory, create a file named `fix-path.config` with this content\. ``` container_commands: fix_path: - command: "unzip my-web-app.war 2>&1 > /var/log/my_last_deploy.log" + command: "unzip ROOT.war 2>&1 > /var/log/my_last_deploy.log" ``` After you run Maven, continue with one of the following scenarios: @@ -53,7 +53,7 @@ In this scenario, you create and upload the source code\. You then use the AWS C In this step, you add an Elastic Beanstalk configuration file and a buildspec file to the code in [Create the source code](#sample-elastic-beanstalk-prepare-source)\. You then upload the source code to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. -1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. +1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `ROOT` directory\. ``` version: 0.2 @@ -65,35 +65,35 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi post_build: commands: - mvn package - - mv target/my-web-app.war my-web-app.war + - mv target/ROOT.war ROOT.war artifacts: files: - - my-web-app.war + - ROOT.war - .ebextensions/**/* ``` 1. Your file structure should now look like this\. ``` - (root directory name) - `-- my-web-app - |-- .ebextensions - | `-- fix-path.config - |-- src - | `-- main - | |-- resources - | `-- webapp - | |-- WEB-INF - | | `-- web.xml - | `-- index.jsp - |-- buildpsec.yml - `-- pom.xml + . + └── ROOT + ├── .ebextensions + │ └── fix-path.config + ├── src + │ └── main + │ ├── resources + │ └── webapp + │ ├── WEB-INF + │ │ └── web.xml + │ └── index.jsp + ├── buildpsec.yml + └── pom.xml ``` -1. Upload the contents of the `my-web-app` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. +1. Upload the contents of the `ROOT` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. **Important** -Do not upload `(root directory name)` or `(root directory name)/my-web-app`, just the directories and files in `(root directory name)/my-web-app`\. - If you are using an S3 input bucket, it must be versioned\. Be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket\. Do not add `(root directory name)` or `(root directory name)/my-web-app` to the ZIP file, just the directories and files in `(root directory name)/my-web-app`\. For more information, see [How to Configure Versioning on a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html#how-to-enable-disable-versioning-intro) in the *Amazon S3 Developer Guide*\. +Do not upload `ROOT`, just the directories and files in `ROOT`\. + If you are using an S3 input bucket, it must be versioned\. Be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket\. Do not add `ROOT` to the ZIP file, just the directories and files in `ROOT`\. For more information, see [How to Configure Versioning on a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html#how-to-enable-disable-versioning-intro) in the *Amazon S3 Developer Guide*\. ### Step a2: Create the build project and run the build @@ -110,7 +110,7 @@ In this step, you use the AWS CodeBuild console to create a build project and th + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. + For **Artifacts**: + For **Type**, choose **Amazon S3**\. + For **Bucket name**, enter the name of an S3 bucket\. @@ -141,7 +141,7 @@ In this scenario, you complete the steps to prepare and upload the source code\. In this step, you create and add a buildspec file to the code you created in [Create the source code](#sample-elastic-beanstalk-prepare-source)\. You then upload the source code to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. -1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. +1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `ROOT` directory\. ``` version: 0.2 @@ -153,36 +153,35 @@ In this step, you create and add a buildspec file to the code you created in [Cr post_build: commands: - mvn package - - mv target/my-web-app.war my-web-app.war + - mv target/ROOT.war ROOT.war artifacts: files: - - my-web-app.war + - ROOT.war - .ebextensions/**/* - base-directory: 'target/my-web-app' ``` 1. Your file structure should now look like this\. ``` - (root directory name) - `-- my-web-app - |-- .ebextensions - | `-- fix-path.config - |-- src - | `-- main - | |-- resources - | `-- webapp - | |-- WEB-INF - | | `-- web.xml - | `-- index.jsp - |-- buildpsec.yml - `-- pom.xml + . + └── ROOT + ├── .ebextensions + │ └── fix-path.config + ├── src + │ └── main + │ ├── resources + │ └── webapp + │ ├── WEB-INF + │ │ └── web.xml + │ └── index.jsp + ├── buildpsec.yml + └── pom.xml ``` -1. Upload the contents of the `my-web-app` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. +1. Upload the contents of the `ROOT` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. **Important** -Do not upload `(root directory name)` or `(root directory name)/my-web-app`, just the directories and files in `(root directory name)/my-web-app`\. - If you are using an S3 input bucket, it must be versioned\. Be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket\. Do not add `(root directory name)` or `(root directory name)/my-web-app` to the ZIP file, just the directories and files in `(root directory name)/my-web-app`\. For more information, see [How to Configure Versioning on a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html#how-to-enable-disable-versioning-intro) in the *Amazon S3 Developer Guide*\. +Do not upload `ROOT`, just the directories and files in `ROOT`\. + If you are using an S3 input bucket, it must be versioned\. Be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket\. Do not add `ROOT` to the ZIP file, just the directories and files in `ROOT`\. For more information, see [How to Configure Versioning on a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html#how-to-enable-disable-versioning-intro) in the *Amazon S3 Developer Guide*\. ### Step b2: Create a build project @@ -195,7 +194,7 @@ In this step, you create an AWS CodeBuild build project to use with your pipelin + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. + For **Artifacts**: + For **Type**, choose **Amazon S3**\. + For **Bucket name**, enter the name of an S3 bucket\. @@ -222,7 +221,7 @@ In this step, you use the AWS CodePipeline console to create a pipeline\. After Use the AWS Region selector to choose an AWS Region where CodeBuild is supported\. If you're storing the source code in an S3 input bucket, the output bucket must be in the same AWS region as the input bucket\. -1. Create a pipeline\. For information, see [Create a pipeline that uses CodeBuild \(CodePipeline console\)](how-to-create-pipeline.md#how-to-create-pipeline-console)\. Leave all settings at their default values, except for these settings\. +1. Create a pipeline\. For information, see [Create a pipeline that uses CodeBuild \(CodePipeline console\)](how-to-create-pipeline-console.md)\. Leave all settings at their default values, except for these settings\. + On **Add build stage**, for **Build provider**, choose **AWS CodeBuild**\. For **Project name**, choose the build project you just created\. + On **Add deploy stage**, for **Deploy provider**, choose **AWS Elastic Beanstalk**\. + For **Application name**, choose the Elastic Beanstalk application you just created\. @@ -242,7 +241,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi 1. Create or identify a service role that Elastic Beanstalk and the CLI can use on your behalf\. For information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. -1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. +1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `ROOT` directory\. ``` version: 0.2 @@ -254,10 +253,10 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi post_build: commands: - mvn package - - mv target/my-web-app.war my-web-app.war + - mv target/ROOT.war ROOT.war artifacts: files: - - my-web-app.war + - ROOT.war - .ebextensions/**/* eb_codebuild_settings: CodeBuildServiceRole: my-service-role-name @@ -271,26 +270,28 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi 1. Your file structure should now look like this\. ``` - (root directory name) - `-- my-web-app - |-- .ebextensions - | `-- fix-path.config - |-- src - | `-- main - | |-- resources - | `-- webapp - | |-- WEB-INF - | | `-- web.xml - | `-- index.jsp - |-- buildpsec.yml - `-- pom.xml + . + └── ROOT + ├── .ebextensions + │ └── fix-path.config + ├── src + │ └── main + │ ├── resources + │ └── webapp + │ ├── WEB-INF + │ │ └── web.xml + │ └── index.jsp + ├── buildpsec.yml + └── pom.xml ``` ### Step c2: Install and run the EB CLI + + 1. If you have not already done so, install and configure the EB CLI on the same computer or instance where you created the source code\. For information, see [Install the Elastic Beanstalk command line interface \(EB CLI\)](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-install.html) and [Configure the EB CLI](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli3-configuration.html) in the *AWS Elastic Beanstalk Developer Guide*\. -1. From the command line or terminal, run the cd command or similar to switch to your `(root directory name)/my-web-app` directory\. Run the eb init command to configure the EB CLI\. +1. From the command line or terminal, run the cd command or similar to switch to your `(root directory name)/ROOT` directory\. Run the eb init command to configure the EB CLI\. ``` eb init diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 84abb3e..49646e8 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -48,7 +48,7 @@ This bucket must be in the same AWS region as your builds\. For example, if you 1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. -1. On the **Create build project** page, in **Project configuration**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. +1. In **Project name**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. 1. In **Source**, in **Source provider**, choose **GitHub Enterprise**\. + For **Personal Access Token**, paste the token you copied to your clipboard and choose **Save Token**\. In **Repository URL**, enter the URL for your GitHub Enterprise Server repository\. @@ -67,7 +67,7 @@ We recommend that you use **Enable insecure SSL** for testing only\. It should n For **Environment image**, do one of the following: + To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. - + To use private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. + + To use a private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. 1. In **Service role**, do one of the following: + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. @@ -84,7 +84,7 @@ When you use the console to create or update a build project, you can create a C For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. -1. For **Buildspec**, do one of the following: +1. In **Buildspec**, do one of the following: + Choose **Use a buildspec file** to use the buildspec\.yml file in the source code root directory\. + Choose **Insert build commands** to use the console to insert build commands\. @@ -106,7 +106,7 @@ When you use the console to create or update a build project, you can create a C Do not append a trailing slash \(/\) to the end of the path prefix\. + If you want to use a local cache, choose **Local**, and then choose one or more local cache modes\. **Note** -Docker layer cache mode is available for Linux only\. If you choose it, your project must run in privileged mode\. The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_GENERAL1_2XLARGE` compute type do not support the use of a local cache\. +Docker layer cache mode is available for Linux only\. If you choose it, your project must run in privileged mode\. Using a cache saves considerable build time because reusable pieces of the build environment are stored in the cache and used across builds\. For information about specifying a cache in the buildspec file, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build caching in AWS CodeBuild](build-caching.md)\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 3109040..95f5a99 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -3,7 +3,7 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This means that for a CodeBuild build project that has its source code stored in a GitHub repository, webhooks can be used to rebuild the source code every time a code change is pushed to the repository\. **Note** - We recommend that you use a filter group to specify which GitHub users can trigger a build in a public repository\. This can prevent a user from triggering an unexpected build\. For more information, see [ Filter GitHub webhook events](#sample-github-pull-request-filter-webhook-events)\. +When using webhooks, it is possible for a user to trigger an unexpected build\. To mitigate this risk, see [Best practices for using webhooks](webhooks.md#webhook-best-practices)\. ## Create a build project with GitHub as the source repository and enable webhooks \(console\) @@ -11,49 +11,67 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 1. If a CodeBuild information page is displayed, choose **Create build project**\. Otherwise, on the navigation pane, expand **Build**, choose **Build projects**, and then choose **Create build project**\. -1. Choose **Create build project**\. +1. Choose **Create build project**\. -1. In **Project configuration**: +1. In **Project configuration**: +**Project name** +Enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. - On the **Create build project** page, in **Project configuration**, enter a name for this build project\. Build project names must be unique across each AWS account\. You can also include an optional description of the build project to help other users understand what this project is used for\. +1. In **Source**: +**Source provider** +Choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub and then choose **Authorize**\. +**Repository** +Choose **Repository in my GitHub account**\. +**GitHub repository** +Enter the URL for your GitHub repository\. -1. In **Source**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub and then choose **Authorize**\. +1. In **Primary source webhook events**, select the following\. +**Note** +The **Primary source webhook events** section is only visible if you chose **Repository in my GitHub account** in the previous step\. + + 1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. - Choose **Repository in my GitHub account**\. + 1. From **Event type**, choose one or more events\. - In **GitHub repository**, enter the URL for your GitHub repository\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-pr-sample-source.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + 1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters\. -1. In **Primary source webhook events**, select **Rebuild every time a code change is pushed to this repository**\. You can select this check box only if you chose **Repository in my GitHub account**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-pr-webhook.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + 1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters\. -1. In **Environment**: + 1. Choose **Add filter group** to add another filter group, if needed\. - For **Environment image**, do one of the following: - + To use a Docker image managed by AWS CodeBuild, choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. - + To use private Docker image, choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. + For more information about GitHub webhook event types and filters, see [GitHub webhook events](github-webhook.md)\. -1. In **Service role**, do one of the following: +1. In **Environment**: +**Environment image** +Choose one of the following: +To use a Docker image managed by AWS CodeBuild: +Choose **Managed image**, and then make selections from **Operating system**, **Runtime\(s\)**, **Image**, and **Image version**\. Make a selection from **Environment type** if it is available\. +To use another Docker image: +Choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. If you choose **Other registry**, for **External registry URL**, enter the name and tag of the Docker image in Docker Hub, using the format `docker repository/docker image name`\. If you choose **Amazon ECR**, use **Amazon ECR repository** and **Amazon ECR image** to choose the Docker image in your AWS account\. +To use a private Docker image: +Choose **Custom image**\. For **Environment type**, choose **ARM**, **Linux**, **Linux GPU**, or **Windows**\. For **Image registry**, choose **Other registry**, and then enter the ARN of the credentials for your private Docker image\. The credentials must be created by Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) in the *AWS Secrets Manager User Guide*\. +**Service role** +Choose one of the following: + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, enter a name for the new role\. + If you have a CodeBuild service role, choose **Existing service role**\. In **Role ARN**, choose the service role\. -**Note** When you use the console to create or update a build project, you can create a CodeBuild service role at the same time\. By default, the role works with that build project only\. If you use the console to associate this service role with another build project, the role is updated to work with the other build project\. A service role can work with up to 10 build projects\. -1. For **Buildspec**, do one of the following: +1. In **Buildspec**, do one of the following: + Choose **Use a buildspec file** to use the buildspec\.yml file in the source code root directory\. + Choose **Insert build commands** to use the console to insert build commands\. For more information, see the [Buildspec reference](build-spec-ref.md)\. -1. In **Artifacts**, for **Type**, do one of the following: +1. In **Artifacts**: +**Type** +Choose one of the following: + If you do not want to create build output artifacts, choose **No artifacts**\. + To store the build output in an S3 bucket, choose **Amazon S3**, and then do the following: + If you want to use your project name for the build output ZIP file or folder, leave **Name** blank\. Otherwise, enter the name\. By default, the artifact name is the project name\. If you want to use a different name, enter it in the artifacts name box\. If you want to output a ZIP file, include the zip extension\. + For **Bucket name**, choose the name of the output bucket\. - + If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter the locations of the files from the build that you want to put into the build output ZIP file or folder\. For multiple locations, separate each location with a comma \(for example, `appspec.yml, target/my-app.jar`\)\. For more information, see the description of `files` in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - -1. Expand **Additional configuration** and set options as appropriate\. + + If you chose **Insert build commands** earlier in this procedure, for **Output files**, enter the locations of the files from the build that you want to put into the build output ZIP file or folder\. For multiple locations, separate each location with a comma \(for example, `appspec.yml, target/my-app.jar`\)\. For more information, see the description of `files` in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. +**Additional configuration** +Expand **Additional configuration** and set options as appropriate\. 1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. @@ -65,248 +83,10 @@ When you use the console to create or update a build project, you can create a C 1. Do one of the following: + Choose the link for the build project with webhooks you want to verify, and then choose **Build details**\. - + Choose the button next to the build project with webhooks you want to verify, choose **View details**, and then choose **Build details**\. + + Choose the button next to the build project with webhooks you want to verify, choose **View details**, and then choose the **Build details** tab\. -1. In **Source**, choose the **Webhook** URL link\. +1. In **Primary source webhook events**, choose the **Webhook** URL link\. 1. In your GitHub repository, on the **Settings** page, under **Webhooks**, verify that **Pull Requests** and **Pushes** are selected\. -1. In your GitHub profile settings, under **Personal settings**, **Applications**, **Authorized OAuth Apps**, you should see that your application has been authorized to access the AWS Region you selected\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-oauth-apps.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -## Filter GitHub webhook events - - You can use webhook filter groups to specify which GitHub webhook events trigger a build\. For example, you can specify that a build is triggered for specified branches only\. - - You can create one or more webhook filter groups to specify which webhook events trigger a build\. A build is triggered if all the filters on one or more filter groups evaluate to true\. When you create a filter group, you specify: -+ An event\. For GitHub, you can choose one or more of the following events: `PUSH`, `PULL_REQUEST_CREATED`, `PULL_REQUEST_UPDATED`, `PULL_REQUEST_REOPENED`, and `PULL_REQUEST_MERGED`\. The webhook event type is in the `X-GitHub-Event` header in the webhook payload\. In the `X-GitHub-Event` header, you might see `pull_request` or `push`\. For a pull request event, the type is in the `action` field of the webhook event payload\. The following table shows how `X-GitHub-Event` header values and webhook pull request payload `action` field values map to the available event types\. -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/sample-github-pull-request.html) -**Note** - The `PULL_REQUEST_REOPENED` event type can be used with GitHub and GitHub Enterprise Server only\. -+ One or more optional filters\. Use a regular expression to specify a filter\. For an event to trigger a build, every filter associated with it must evaluate to true\. - + `ACTOR_ACCOUNT_ID` \(`ACTOR_ID` in the console\): A webhook event triggers a build when a GitHub or GitHub Enterprise Server account ID matches the regular expression pattern\. This value is found in the `id` property of the `sender` object in the webhook payload\. - + `HEAD_REF`: A webhook event triggers a build when the head reference matches the regular expression pattern \(for example, `refs/heads/branch-name` or `refs/tags/tag-name`\)\. For a push event, the reference name is found in the `ref` property in the webhook payload\. For pull requests events, the branch name is found in the `ref` property of the `head` object in the webhook payload\. - + `BASE_REF`: A webhook event triggers a build when the base reference matches the regular expression pattern \(for example, `refs/heads/branch-name`\)\. A `BASE_REF` filter can be used with pull request events only\. The branch name is found in the `ref` property of the `base` object in the webhook payload\. - + `FILE_PATH`: A webhook triggers a build when the path of a changed file matches the regular expressions pattern\. A `FILE_PATH` filter can be used with GitHub push and pull request events and GitHub Enterprise Server push events\. It cannot be used with GitHub Enterprise Server pull request events\. - + `COMMIT_MESSAGE`: A webhook triggers a build when the head commit message matches the regular expression pattern\. A `COMMIT_MESSAGE` filter can be used with GitHub push and pull request events and GitHub Enterprise Server push events\. It cannot be used with GitHub Enterprise Server pull request events\. - -**Note** - You can find the webhook payload in the webhook settings of your GitHub repository\. - -**Topics** -+ [Filter GitHub webhook events \(console\)](#sample-github-pull-request-filter-webhook-events-console) -+ [Filter GitHub webhook events \(SDK\)](#sample-github-pull-request-filter-webhook-events-sdk) -+ [Filter GitHub webhook events \(AWS CloudFormation\)](#sample-github-pull-request-filter-webhook-events-cfn) - -### Filter GitHub webhook events \(console\) - - To use the AWS Management Console to filter webhook events: - -1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. - -1. From **Event type**, choose one or more events\. - -1. To filter when an event triggers a build, under **Start a build under these conditions**, add one or more optional filters\. - -1. To filter when an event is not triggered, under **Don't start a build under these conditions**, add one or more optional filters\. - -1. Choose **Add filter group** to add another filter group\. - - For more information, see [Create a build project \(console\)](create-project-console.md) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. - -In this example, a webhook filter group triggers a build for pull requests only: - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -Using an example of two webhook filter groups, a build is triggered when one or both evaluate to true: -+ The first filter group specifies pull requests that are created, updated, or reopened on branches with Git reference names that match the regular expression `^refs/heads/master$` and head references that match `^refs/heads/branch1$`\. -+ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/branch1$`\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -In this example, a webhook filter group triggers a build for all requests except tag events\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -In this example, a webhook filter group triggers a build only when files with names that match the regular expression `^buildspec.*` change\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -In this example, a webhook filter group triggers a build only when a change is made by a specified GitHub or GitHub Enterprise Server user with an account ID that matches the regular expression `actor-account-id`\. - -**Note** - For information about how to find your GitHub account ID, see https://api\.github\.com/users/*user\-name*, where *user\-name* is your GitHub user name\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -In this example, a webhook filter group triggers a build for a push event when the head commit message matches the regular expression `\[CodeBuild\]`\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -### Filter GitHub webhook events \(SDK\) - -To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` field in the request syntax of the `CreateWebhook` or `UpdateWebhook` API methods\. For more information, see [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *CodeBuild API Reference*\. - - To create a webhook filter that triggers a build for pull requests only, insert the following into the request syntax: - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" - } - ] -] -``` - - To create a webhook filter that triggers a build for specified branches only, use the `pattern` parameter to specify a regular expression to filter branch names\. Using an example of two filter groups, a build is triggered when one or both evaluate to true: -+ The first filter group specifies pull requests that are created, updated, or reopened on branches with Git reference names that match the regular expression `^refs/heads/master$` and head references that match `^refs/heads/myBranch$`\. -+ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/heads/myBranch$" - }, - { - "type": "BASE_REF", - "pattern": "^refs/heads/master$" - } - ], - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/heads/myBranch$" - } - ] -] -``` - - You can use the `excludeMatchedPattern` parameter to specify which events do not trigger a build\. For example, in this example a build is triggered for all requests except tag events\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/tags/.*", - "excludeMatchedPattern": true - } - ] -] -``` - -You can create a filter that triggers a build only when files with names that match the regular expression in the `pattern` argument change\. In this example, the filter group specifies that a build is triggered only when files with a name that matches the regular expression `^buildspec.*` change\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "FILE_PATH", - "pattern": "^buildspec.*" - } - ] -] -``` - -You can create a filter that triggers a build only when a change is made by a specified GitHub or GitHub Enterprise Server user with account ID `actor-account-id`\. - -**Note** - For information about how to find your GitHub account ID, see https://api\.github\.com/users/*user\-name*, where *user\-name* is your GitHub user name\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_REOPENED, PULL_REQUEST_MERGED" - }, - { - "type": "ACTOR_ACCOUNT_ID", - "pattern": "actor-account-id" - } - ] -] -``` - -You can create a filter that triggers a build only when the head commit message matches the regular expression in the pattern argument\. In this example, the filter group specifies that a build is triggered only when the head commit message of the push event matches the regular expression `\[CodeBuild\]`\. - -``` -"filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "COMMIT_MESSAGE", - "pattern": "\[CodeBuild\]" - } - ] -] -``` - -### Filter GitHub webhook events \(AWS CloudFormation\) - - To use an AWS CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property\. The following YAML\-formatted portion of an AWS CloudFormation template creates two filter groups\. Together, they trigger a build when one or both evaluate to true: -+ The first filter group specifies pull requests are created or updated on branches with Git reference names that match the regular expression `^refs/heads/master$` by a GitHub user who does not have account ID `12345`\. -+ The second filter group specifies push requests are created on files with names that match the regular expression `READ_ME` in branches with Git reference names that match the regular expression `^refs/heads/.*`\. -+ The third filter group specifies a push request with a head commit message matching the regular expression `\[CodeBuild\]`\. - -``` -CodeBuildProject: - Type: AWS::CodeBuild::Project - Properties: - Name: MyProject - ServiceRole: service-role - Artifacts: - Type: NO_ARTIFACTS - Environment: - Type: LINUX_CONTAINER - ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:4.0 - Source: - Type: GITHUB - Location: source-location - Triggers: - Webhook: true - FilterGroups: - - - Type: EVENT - Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - - Type: BASE_REF - Pattern: ^refs/heads/master$ - ExcludeMatchedPattern: false - - Type: ACTOR_ACCOUNT_ID - Pattern: 12345 - ExcludeMatchedPattern: true - - - Type: EVENT - Pattern: PUSH - - Type: HEAD_REF - Pattern: ^refs/heads/.* - - Type: FILE_PATH - Pattern: READ_ME - ExcludeMatchedPattern: true - - - Type: EVENT - Pattern: PUSH - - Type: COMMIT_MESSAGE - - Pattern: \[CodeBuild\] -``` \ No newline at end of file +1. In your GitHub profile settings, under **Personal settings**, **Applications**, **Authorized OAuth Apps**, you should see that your application has been authorized to access the AWS Region you selected\. \ No newline at end of file diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index c39dfaf..e43b9f5 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -8,7 +8,7 @@ You can create an AWS CodeBuild build project with more than one input source an 1. Upload your sources to one or more S3 buckets, CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket repositories\. -1. Choose which source is the primary source\. This is the source in which CodeBuild looks for and executes your buildspec file\. +1. Choose which source is the primary source\. This is the source in which CodeBuild looks for and runs your buildspec file\. 1. Create a build project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md)\. @@ -26,12 +26,12 @@ You can create an AWS CodeBuild build project with more than one input source an "secondarySources": [ { "type": "CODECOMMIT", - "location": "https://git-codecommit.us-west-2.amazonaws.com/v1/repos/repo" + "location": "https://git-codecommit.us-west-2.amazonaws.com/v1/repos/repo", "sourceIdentifier": "source1" }, { "type": "GITHUB", - "location": "https://github.com/awslabs/aws-codebuild-jenkins-plugin" + "location": "https://github.com/awslabs/aws-codebuild-jenkins-plugin", "sourceIdentifier": "source2" } ], @@ -83,6 +83,8 @@ phases: - touch file2 artifacts: + files: + - '**.*' secondary-artifacts: artifact1: base-directory: $CODEBUILD_SRC_DIR_source1 @@ -137,4 +139,4 @@ artifacts: For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. -To learn how to to create a pipeline that uses multiple source inputs to CodeBuild to create multiple output artifacts, see [ AWS CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample ](sample-pipeline-multi-input-output.md)\. \ No newline at end of file +To learn how to to create a pipeline that uses multiple source inputs to CodeBuild to create multiple output artifacts, see [AWS CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample ](sample-pipeline-multi-input-output.md)\. \ No newline at end of file diff --git a/doc_source/sample-pipeline-batch.md b/doc_source/sample-pipeline-batch.md new file mode 100644 index 0000000..5cb39db --- /dev/null +++ b/doc_source/sample-pipeline-batch.md @@ -0,0 +1,277 @@ +# AWS CodePipeline integration with CodeBuild and batch builds + +AWS CodeBuild now supports batch builds\. This sample demonstrates how to use AWS CodePipeline to create a build project that uses batch builds\. + +You can use a JSON\-formatted file that defines the structure of your pipeline, and then use it with the AWS CLI to create the pipeline\. For more information, see [AWS CodePipeline Pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*\. + +## Batch build with individual artifacts + +Use the following JSON file as an example of a pipeline structure that creates a batch build with separate artifacts\. To enable batch builds in CodePipeline, set the `BatchEnabled` parameter of the `configuration` object to `true`\. + +``` +{ + "pipeline": { + "roleArn": "arn:aws:iam::account-id:role/my-AWS-CodePipeline-service-role-name", + "stages": [ + { + "name": "Source", + "actions": [ + { + "inputArtifacts": [], + "name": "Source1", + "actionTypeId": { + "category": "Source", + "owner": "AWS", + "version": "1", + "provider": "S3" + }, + "outputArtifacts": [ + { + "name": "source1" + } + ], + "configuration": { + "S3Bucket": "my-input-bucket-name", + "S3ObjectKey": "my-source-code-file-name.zip" + }, + "runOrder": 1 + }, + { + "inputArtifacts": [], + "name": "Source2", + "actionTypeId": { + "category": "Source", + "owner": "AWS", + "version": "1", + "provider": "S3" + }, + "outputArtifacts": [ + { + "name": "source2" + } + ], + "configuration": { + "S3Bucket": "my-other-input-bucket-name", + "S3ObjectKey": "my-other-source-code-file-name.zip" + }, + "runOrder": 1 + } + ] + }, + { + "name": "Build", + "actions": [ + { + "inputArtifacts": [ + { + "name": "source1" + }, + { + "name": "source2" + } + ], + "name": "Build", + "actionTypeId": { + "category": "Build", + "owner": "AWS", + "version": "1", + "provider": "AWS CodeBuild" + }, + "outputArtifacts": [ + { + "name": "build1" + }, + { + "name": "build1_artifact1" + }, + { + "name": "build1_artifact2" + }, + { + "name": "build2_artifact1" + }, + { + "name": "build2_artifact2" + } + ], + "configuration": { + "ProjectName": "my-build-project-name", + "PrimarySource": "source1", + "BatchEnabled": "true" + }, + "runOrder": 1 + } + ] + } + ], + "artifactStore": { + "type": "S3", + "location": "AWS-CodePipeline-internal-bucket-name" + }, + "name": "my-pipeline-name", + "version": 1 + } +} +``` + +The following is an example of a CodeBuild buildspec file that will work with this pipeline configuration\. + +``` +version: 0.2 +batch: + build-list: + - identifier: build1 + env: + compute-type: BUILD_GENERAL1_SMALL + - identifier: build2 + env: + compute-type: BUILD_GENERAL1_MEDIUM + +phases: + build: + commands: + - echo 'file' > output_file + +artifacts: + files: + - output_file + secondary-artifacts: + artifact1: + files: + - output_file + artifact2: + files: + - output_file +``` + +The names of the output artifacts specified in the pipeline's JSON file must match the identifier of the builds and artifacts defined in your buildspec file\. The syntax is *buildIdentifier* for the primary artifacts, and *buildIdentifier*\_*artifactIdentifier* for the secondary artifacts\. + +For example, for output artifact name `build1`, CodeBuild will upload the primary artifact of `build1` to the location of `build1`\. For output name `build1_artifact1`, CodeBuild will upload the secondary artifact `artifact1` of `build1` to the location of `build1_artifact1`, and so on\. If only one output location is specified, the name should be *buildIdentifier* only\. + +After you create the JSON file, you can create your pipeline\. Use the AWS CLI to run the **create\-pipeline** command and pass the file to the `--cli-input-json` parameter\. For more information, see [Create a pipeline \(CLI\)](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html#pipelines-create-cli) in the *AWS CodePipeline User Guide*\. + +## Batch build with combined artifacts + +Use the following JSON file as an example of a pipeline structure that creates a batch build with combined artifacts\. To enable batch builds in CodePipeline, set the `BatchEnabled` parameter of the `configuration` object to `true`\. To combine the build artifacts into the same location, set the `CombineArtifacts` parameter of the `configuration` object to `true`\. + +``` +{ + "pipeline": { + "roleArn": "arn:aws:iam::account-id:role/my-AWS-CodePipeline-service-role-name", + "stages": [ + { + "name": "Source", + "actions": [ + { + "inputArtifacts": [], + "name": "Source1", + "actionTypeId": { + "category": "Source", + "owner": "AWS", + "version": "1", + "provider": "S3" + }, + "outputArtifacts": [ + { + "name": "source1" + } + ], + "configuration": { + "S3Bucket": "my-input-bucket-name", + "S3ObjectKey": "my-source-code-file-name.zip" + }, + "runOrder": 1 + }, + { + "inputArtifacts": [], + "name": "Source2", + "actionTypeId": { + "category": "Source", + "owner": "AWS", + "version": "1", + "provider": "S3" + }, + "outputArtifacts": [ + { + "name": "source2" + } + ], + "configuration": { + "S3Bucket": "my-other-input-bucket-name", + "S3ObjectKey": "my-other-source-code-file-name.zip" + }, + "runOrder": 1 + } + ] + }, + { + "name": "Build", + "actions": [ + { + "inputArtifacts": [ + { + "name": "source1" + }, + { + "name": "source2" + } + ], + "name": "Build", + "actionTypeId": { + "category": "Build", + "owner": "AWS", + "version": "1", + "provider": "AWS CodeBuild" + }, + "outputArtifacts": [ + { + "name": "output1 " + } + ], + "configuration": { + "ProjectName": "my-build-project-name", + "PrimarySource": "source1", + "BatchEnabled": "true", + "CombineArtifacts": "true" + }, + "runOrder": 1 + } + ] + } + ], + "artifactStore": { + "type": "S3", + "location": "AWS-CodePipeline-internal-bucket-name" + }, + "name": "my-pipeline-name", + "version": 1 + } +} +``` + +The following is an example of a CodeBuild buildspec file that will work with this pipeline configuration\. + +``` +version: 0.2 +batch: + build-list: + - identifier: build1 + env: + compute-type: BUILD_GENERAL1_SMALL + - identifier: build2 + env: + compute-type: BUILD_GENERAL1_MEDIUM + +phases: + build: + commands: + - echo 'file' > output_file + +artifacts: + files: + - output_file +``` + +If combined artifacts is enabled for the batch build, there is only one output allowed\. CodeBuild will combine the primary artifacts of all the builds into one single ZIP file\. + +After you create the JSON file, you can create your pipeline\. Use the AWS CLI to run the **create\-pipeline** command and pass the file to the `--cli-input-json` parameter\. For more information, see [Create a pipeline \(CLI\)](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipelines-create.html#pipelines-create-cli) in the *AWS CodePipeline User Guide*\. \ No newline at end of file diff --git a/doc_source/sample-pipeline-multi-input-output.md b/doc_source/sample-pipeline-multi-input-output.md index cfbab88..30d509d 100644 --- a/doc_source/sample-pipeline-multi-input-output.md +++ b/doc_source/sample-pipeline-multi-input-output.md @@ -2,7 +2,7 @@ An AWS CodeBuild project can take more than one input source\. It can also create more than one output artifact\. This sample demonstrates how to use AWS CodePipeline to create a build project that uses multiple input sources to create multiple output artifacts\. For more information, see [Multiple input sources and output artifacts sample](sample-multi-in-out.md)\. - You can use a JSON\-formatted file that defines the structure of your pipeline, and then use it with the AWS CLI to create the pipeline\. Use the following JSON file as an example of a pipeline structure that creates a build with more than one input source and more than one output artifact\. Later in this sample you see how this file specifies the multiple inputs and outputs\. For more information, see [AWS CodePipeline Pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*\. +You can use a JSON\-formatted file that defines the structure of your pipeline, and then use it with the AWS CLI to create the pipeline\. Use the following JSON file as an example of a pipeline structure that creates a build with more than one input source and more than one output artifact\. Later in this sample you see how this file specifies the multiple inputs and outputs\. For more information, see [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*\. ``` { @@ -104,7 +104,6 @@ An AWS CodeBuild project can take more than one input source\. It can also creat + One of your input sources must be designated the `PrimarySource`\. This source is the directory where CodeBuild looks for and runs your buildspec file\. The keyword `PrimarySource` is used to specify the primary source in the `configuration` section of the CodeBuild stage in the JSON file\. + Each input source is installed in its own directory\. This directory is stored in the built\-in environment variable `$CODEBUILD_SRC_DIR` for the primary source and `$CODEBUILD_SRC_DIR_yourInputArtifactName` for all other sources\. For the pipeline in this sample, the two input source directories are `$CODEBUILD_SRC_DIR` and `$CODEBUILD_SRC_DIR_source2`\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. + The names of the output artifacts specified in the pipeline's JSON file must match the names of the secondary artifacts defined in your buildspec file\. This pipeline uses the following buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. -+ ``` version: 0.2 @@ -117,6 +116,8 @@ An AWS CodeBuild project can take more than one input source\. It can also creat - touch source2_file artifacts: + files: + - '**/*' secondary-artifacts: artifact1: base-directory: $CODEBUILD_SRC_DIR diff --git a/doc_source/sample-private-registry.md b/doc_source/sample-private-registry.md index 57b73d8..b8c230b 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -18,15 +18,14 @@ ``` docker pull amazonlinux docker images amazonlinux --format {{.ID}} - docker tag image-id your-username/repository-name:latest + docker tag image-id your-username/repository-name:tag docker login docker push your-username/repository-name ``` 1. Follow the steps in [Creating a basic secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) in the *AWS Secrets Manager User Guide*\. In step 3, in **Select secret type**, do the following: - 1. Choose **Other type of secrets**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/private-registry-sample-secrets-manager.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + 1. Choose **Other type of secrets**\. 1. In **Secret key/value**, create one key\-value pair for your Docker Hub user name and one key\-value pair for your Docker Hub password\. @@ -40,7 +39,7 @@ For more information, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) -1. When you create an AWS CodeBuild project in the console, CodeBuild attaches the required permission for you\. If you use an AWS KMS key other than `DefaultEncryptionKey`, you must add it to the service role\. For more information, see [Modifying a role \(console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_modify.html#roles-managingrole-editing-console) in the *AWS Identity and Management User Guide*\. +1. When you create an AWS CodeBuild project in the console, CodeBuild attaches the required permission for you\. If you use an AWS KMS key other than `DefaultEncryptionKey`, you must add it to the service role\. For more information, see [Modifying a role \(console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_modify.html#roles-managingrole-editing-console) in the *IAM User Guide*\. For your service role to work with Secrets Manager, it must have, at a minimum, the `secretsmanager:GetSecretValue` permission\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/private-registry-sample-iam.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 536f666..087c35f 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -1,14 +1,14 @@ # Runtime versions in buildspec file sample for CodeBuild - If you use the Amazon Linux 2 \(AL2\) standard image version 1\.0 or later, or the Ubuntu standard image version 2\.0 or later, you can specify one or more runtimes in the `runtime-versions` section of your buildspec file\. This sample shows how you can change your project runtime, specify more than one runtime, and specify a runtime that is dependent on another runtime\. For information about supported runtimes, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. +If you use the Amazon Linux 2 \(AL2\) standard image version 1\.0 or later, or the Ubuntu standard image version 2\.0 or later, you can specify one or more runtimes in the `runtime-versions` section of your buildspec file\. This sample shows how you can change your project runtime, specify more than one runtime, and specify a runtime that is dependent on another runtime\. For information about supported runtimes, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. **Note** - If you use Docker in your build container, your build must run in privileged mode\. For more information, see [Run a build in AWS CodeBuild](run-build.md) and [Create a build project in AWS CodeBuild](create-project.md)\. +If you use Docker in your build container, your build must run in privileged mode\. For more information, see [Run a build in AWS CodeBuild](run-build.md) and [Create a build project in AWS CodeBuild](create-project.md)\. ## Update your runtime version - You can modify the runtime used by your project to a new version by updating the `runtime-versions` section of your buildpec file\. The following examples show how to specify java versions 8 and 11\. -+ A `runtime-versions` section that specifies version 8 of Java if you use the Amazon Linux 2 standard image: +You can modify the runtime used by your project to a new version by updating the `runtime-versions` section of your buildspec file\. The following examples show how to specify java versions 8 and 11\. ++ A `runtime-versions` section that specifies version 8 of Java: ``` phases: @@ -16,7 +16,7 @@ runtime-versions: java: corretto8 ``` -+ A `runtime-versions` section that specifies version 11 of Java if you use the Amazon Linux 2 standard image: ++ A `runtime-versions` section that specifies version 11 of Java: ``` phases: @@ -24,46 +24,30 @@ runtime-versions: java: corretto11 ``` -+ A `runtime-versions` section that specifies version 8 of Java if you use the Ubuntu standard image 2\.0: - ``` - phases: - install: - runtime-versions: - java: openjdk8 - ``` -+ A `runtime-versions` section that specifies version 11 of Java if you use the Ubuntu standard image 2\.0: +The following examples show how to specify different versions of Python using the Ubuntu standard image 5\.0 or the Amazon Linux 2 standard image 3\.0: ++ A `runtime-versions` section that specifies Python version 3\.7: ``` phases: install: runtime-versions: - java: openjdk11 + python: 3.7 ``` - - The following examples show how you to specify different versions of Node\.js using the Ubuntu standard image 2\.0 or the Amazon Linux 2 standard image 2\.0: -+ A `runtime-versions` section that specifies Node\.js version 8: ++ A `runtime-versions` section that specifies Python version 3\.8: ``` phases: install: runtime-versions: - nodejs: 8 + python: 3.8 ``` -+ A `runtime-versions` section that specifies Node\.js version 10: - ``` - phases: - install: - runtime-versions: - nodejs: 10 - ``` +This sample demonstrates a project that starts with the Java version 8 runtime, and then is updated to the Java version 10 runtime\. - This sample demonstrates a project that starts with the Java version 8 runtime, and then is updated to the Java version 10 runtime\. +1. Follow steps 1 and 2 in [Create the source code](sample-elastic-beanstalk.md#sample-elastic-beanstalk-prepare-source) to generate source code\. If successful, a directory named `my-web-app` is created with your source files\. -1. Follow steps 1 and 2 in [Create the source code](sample-elastic-beanstalk.md#sample-elastic-beanstalk-prepare-source) to generate source code\. If successful, a directory named `my-web-app` is created with your source files\. - -1. Create a file named `buildspec.yml` with the following contents\. Store the file in the ` (root directory name)/my-web-app` directory\. +1. Create a file named `buildspec.yml` with the following contents\. Store the file in the ` (root directory name)/my-web-app` directory\. ``` version: 0.2 @@ -82,27 +66,27 @@ base-directory: 'target/my-web-app' ``` - In the buildspec file: - + The `runtime-versions` section specifies that the project uses version 8 of the Java runtime\. - + The `- java -version` command displays the version of Java used by your project when it builds\. + In the buildspec file: + + The `runtime-versions` section specifies that the project uses version 8 of the Java runtime\. + + The `- java -version` command displays the version of Java used by your project when it builds\. - Your file structure should now look like this\. + Your file structure should now look like this\. ``` (root directory name) - -- my-web-app - |-- src - | `-- main - | |-- resources - | `-- webapp - | |-- WEB-INF - | | `-- web.xml - | `-- index.jsp - |-- buildspec.yml - `-- pom.xml + └── my-web-app + ├── src + │ ├── main + │ ├── resources + │ └── webapp + │ └── WEB-INF + │ └── web.xml + │ └── index.jsp + ├── buildspec.yml + └── pom.xml ``` -1. Upload the contents of the `my-web-app` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. +1. Upload the contents of the `my-web-app` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. **Important** Do not upload `(root directory name)` or `(root directory name)/my-web-app`, just the directories and files in `(root directory name)/my-web-app`\. If you are using an S3 input bucket, be sure to create a ZIP file that contains the directory structure and files, and then upload it to the input bucket\. Do not add `(root directory name)` or `(root directory name)/my-web-app` to the ZIP file, just the directories and files in `(root directory name)/my-web-app`\. @@ -116,11 +100,11 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains + For **Runtime\(s\)**, choose **Standard**\. + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. -1. Choose **Start build**\. +1. Choose **Start build**\. -1. On **Build configuration**, accept the defaults, and then choose **Start build**\. +1. On **Build configuration**, accept the defaults, and then choose **Start build**\. -1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following: +1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following: ``` [Container] Date Time Phase is DOWNLOAD_SOURCE @@ -140,7 +124,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains [Container] Date Time Running command for tool_path in "$JAVA_8_HOME"/bin/* "$JRE_8_HOME"/bin/*; ``` -1. Update the `runtime-versions` section with Java version 11: +1. Update the `runtime-versions` section with Java version 11: ``` install: @@ -148,7 +132,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains java: corretto11 ``` -1. After you save the change, run your build again and view the build output\. You should see that the installed version of Java is 11\. You should see output similar to the following: +1. After you save the change, run your build again and view the build output\. You should see that the installed version of Java is 11\. You should see output similar to the following: ``` [Container] Date Time Phase is DOWNLOAD_SOURCE @@ -169,25 +153,28 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains ## Specify a runtime dependency - This example shows how to specify a runtime and a dependency runtime\. For example, any supported Android runtime version is dependent on the Java runtime version 8\. For example, if you specify Android version 29 and use Amazon Linux 2 or Ubuntu, you can also specify Java version 8\. If you do not specify the dependent runtime, CodeBuild attempts to choose it for you\. +This example shows how to specify a runtime and a dependency runtime\. For example, any supported Android runtime version is dependent on the Java runtime version 8\. For example, if you specify Android version 29 and use Amazon Linux 2 or Ubuntu, you can also specify Java version 8\. If you do not specify the dependent runtime, CodeBuild attempts to choose it for you\. The build project in this example uses source code in the GitHub [AWS samples](https://github.com/aws-samples) repository\. The source code uses the Android version 28 runtime and the build project uses Amazon Linux 2, so the buildspec also specifies Java version 8\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. 1. Create a build project\. For more information, see [Create a build project \(console\)](create-project-console.md) and [Run a build \(console\)](run-build-console.md)\. Leave all settings at their default values, except for these settings\. - + For **Environment**: + + For **Source**: + For **Source provider**, choose **GitHub**\. + + If you have not previously connected your GitHub account, choose **Connect using OAuth** or **Connect with a GitHub personal access token ** and follow the instructions to connect \(or reconnect\) to GitHub and authorize access to AWS CodeBuild\. + For **Repository**, choose **Public repository**\. + For **Repository URL**, enter **https://github\.com/aws\-samples/aws\-mobile\-android\-notes\-tutorial**\. + + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. - + For **Runtime\(s\)**, choose **Standard**\. + + For **Runtime\(s\)**, choose **Standard**\. + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. -1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. +1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. -1. In **Build commands**, replace the placeholder text with the following: +1. In **Build commands**, replace the placeholder text with the following: ``` version: 0.2 @@ -205,15 +192,15 @@ The build project in this example uses source code in the GitHub [AWS samples](h - app/build/outputs/apk/app-debug.apk ``` - The `runtime-versions` section specifies both Android version 29 and Java version 8 runtimes\. + The `runtime-versions` section specifies both Android version 29 and Java version 8 runtimes\. -1. Choose **Create build project**\. +1. Choose **Create build project**\. -1. Choose **Start build**\. +1. Choose **Start build**\. -1. On **Build configuration**, accept the defaults, and then choose **Start build**\. +1. On **Build configuration**, accept the defaults, and then choose **Start build**\. -1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following\. It shows that Android version 29 and Java version 8 are installed: +1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following\. It shows that Android version 29 and Java version 8 are installed: ``` [Container] 2019/05/14 23:21:42 Entering phase DOWNLOAD_SOURCES @@ -226,13 +213,13 @@ The build project in this example uses source code in the GitHub [AWS samples](h ## Specify two runtimes - You can specify more than one runtime in the same CodeBuild build project\. This sample project uses two source files: one that uses the Go runtime and one that uses the Node\.js runtime\. +You can specify more than one runtime in the same CodeBuild build project\. This sample project uses two source files: one that uses the Go runtime and one that uses the Node\.js runtime\. -1. Create a directory named `my-source`\. +1. Create a directory named `my-source`\. -1. Inside the `my-source` directory, create a directory named `golang-app`\. +1. Inside the `my-source` directory, create a directory named `golang-app`\. -1. Create a file named `hello.go` with the following contents\. Store the file in the `golang-app` directory\. +1. Create a file named `hello.go` with the following contents\. Store the file in the `golang-app` directory\. ``` package main @@ -249,9 +236,9 @@ The build project in this example uses source code in the GitHub [AWS samples](h } ``` -1. Inside the `my-source` directory, create a directory named `nodejs-app`\. It should be at the same level as the `golang-app` directory\. +1. Inside the `my-source` directory, create a directory named `nodejs-app`\. It should be at the same level as the `golang-app` directory\. -1. Create a file named `index.js` with the following contents\. Store the file in the `nodejs-app` directory\. +1. Create a file named `index.js` with the following contents\. Store the file in the `nodejs-app` directory\. ``` console.log("hello world from nodejs"); @@ -263,7 +250,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h console.log("good bye from nodejs"); ``` -1. Create a file named `package.json` with the following contents\. Store the file in the `nodejs-app` directory\. +1. Create a file named `package.json` with the following contents\. Store the file in the `nodejs-app` directory\. ``` { @@ -279,7 +266,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h } ``` -1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `my-source` directory, at the same level as the `nodejs-app` and `golang-app` directories\. The `runtime-versions` section specifies the Node\.js version 10 and Go version 1\.13 runtimes\. +1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `my-source` directory, at the same level as the `nodejs-app` and `golang-app` directories\. The `runtime-versions` section specifies the Node\.js version 12 and Go version 1\.13 runtimes\. ``` version: 0.2 @@ -288,7 +275,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h install: runtime-versions: golang: 1.13 - nodejs: 10 + nodejs: 12 build: commands: - echo Building the Go code... @@ -310,16 +297,16 @@ The build project in this example uses source code in the GitHub [AWS samples](h - package.json ``` -1. Your file structure should now look like this\. +1. Your file structure should now look like this\. ``` - -- my-source - |-- golang-app - | -- hello.go - |-- nodejs.app - | -- index.js - | -- package.json - |-- buildspec.yml + my-source + ├── golang-app + │ └── hello.go + ├── nodejs.app + │ ├── index.js + │ └── package.json + └── buildspec.yml ``` 1. Upload the contents of the `my-source` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. @@ -333,27 +320,28 @@ The build project in this example uses source code in the GitHub [AWS samples](h + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. -1. Choose **Create build project**\. +1. Choose **Create build project**\. -1. Choose **Start build**\. +1. Choose **Start build**\. -1. On **Build configuration**, accept the defaults, and then choose **Start build**\. +1. On **Build configuration**, accept the defaults, and then choose **Start build**\. -1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following\. It shows output from the Go and Node\.js runtimes\. It also shows output from the Go and Node\.js applications\. +1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following\. It shows output from the Go and Node\.js runtimes\. It also shows output from the Go and Node\.js applications\. ``` [Container] Date Time Processing environment variables [Container] Date Time Selecting 'golang' runtime version '1.13' based on manual selections... - [Container] Date Time Selecting 'nodejs' runtime version '10' based on manual selections... + [Container] Date Time Selecting 'nodejs' runtime version '12' based on manual selections... [Container] Date Time Running command echo "Installing Go version 1.13 ..." - Installing Go version 1.12 ... + Installing Go version 1.13 ... - [Container] Date Time Running command echo "Installing Node.js version 10 ..." - Installing Node.js version 10 ... + [Container] Date Time Running command echo "Installing Node.js version 12 ..." + Installing Node.js version 12 ... - [Container] Date Time Running command n 10.15.3 + [Container] Date Time Running command n $NODE_12_VERSION + installed : v12.20.1 (with npm 6.14.10) [Container] Date Time Moving to directory /codebuild/output/src819694850/src [Container] Date Time Registering with agent diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index 6bcbf87..4b4f24a 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -17,7 +17,7 @@ If you use a reference and a commit ID to specify a version, the `DOWNLOAD_SOURCE` phase of your build is faster than if you provide the version only\. This is because when you add a reference, CodeBuild does not need to download the entire repository to find the commit\. + You can specify a source version with only a commit ID, such as `12345678901234567890123467890123456789`\. If you do this, CodeBuild must download the entire repository to find the version\. -+ You can specify a source version with a reference and a commit ID in this format: `refs/heads/branchname^{full-commit-SHA}` \(for example, `refs/heads/master^{12345678901234567890123467890123456789}`\)\. If you do this, CodeBuild downloads only the specified branch to find the version\. \. ++ You can specify a source version with a reference and a commit ID in this format: `refs/heads/branchname^{full-commit-SHA}` \(for example, `refs/heads/main^{12345678901234567890123467890123456789}`\)\. If you do this, CodeBuild downloads only the specified branch to find the version\. \. **Note** To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git clone depth** to a low number\. CodeBuild downloads fewer versions of your repository\. @@ -35,7 +35,7 @@ To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. 1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. @@ -81,7 +81,7 @@ To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git 1. Choose **Start build**\. -1. In **Source version**, enter **refs/heads/master^\{046e8b67481d53bdc86c3f6affdd5d1afae6d369\}**\. This is the same commit ID and a reference to a branch in the format `refs/heads/branchname^{full-commit-SHA}`\. +1. In **Source version**, enter **refs/heads/main^\{046e8b67481d53bdc86c3f6affdd5d1afae6d369\}**\. This is the same commit ID and a reference to a branch in the format `refs/heads/branchname^{full-commit-SHA}`\. 1. Choose **Start build**\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 95ff6a1..d07f03e 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -14,11 +14,12 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re + Create your test cases\. This sample is written with the assumption that you have test cases to include in your sample test report\. You specify the location of your test files in the buildspec file\. The following test report file formats are supported: - + Cucumber JSON - + JUnit XML - + NUnit XML - + TestNG XML - + Visual Studio TRX + + Cucumber JSON \(\.json\) + + JUnit XML \(\.xml\) + + NUnit XML \(\.xml\) + + NUnit3 XML \(\.xml\) + + TestNG XML \(\.xml\) + + Visual Studio TRX \(\.trx\) Create your test cases with any test framework that can create report files in one of these formats \(for example, Surefire JUnit plugin, TestNG, or Cucumber\)\. + Create an S3 bucket and make a note of its name\. For more information, see [How do I create an S3 bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon S3 User Guide*\. @@ -44,33 +45,31 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re ## Create a report group -1. Create a file named `CreateReportGroupInput.json`\. +1. Create a file named `CreateReportGroupInput.json`\. -1. Create a folder in your S3 bucket where your test results are exported\. +1. Create a folder in your S3 bucket where your test results are exported\. -1. Copy the following into `CreateReportGroupInput.json`\. For `bucket`, use the name of the S3 bucket\. For `path`, enter the path to the folder in your S3 bucket\. +1. Copy the following into `CreateReportGroupInput.json`\. For ``, use the name of the S3 bucket\. For ``, enter the path to the folder in your S3 bucket\. ``` { - "name": "report-name", + "name": "", "type": "TEST", "exportConfig": { "exportConfigType": "S3", "s3Destination": { - "bucket": "bucket-name", - "path": "path-to-folder", + "bucket": "", + "path": "", "packaging": "NONE" } } } ``` -1. Run the following command in the directory that contains `CreateReportGroupInput.json`\. For `region`, specify your AWS Region \(for example, `us-east-2`\)\. +1. Run the following command in the directory that contains `CreateReportGroupInput.json`\. ``` - aws codebuild create-report-group \ - --cli-input-json file://CreateReportGroupInput.json \ - --region your-region + aws codebuild create-report-group --cli-input-json file://CreateReportGroupInput.json ``` The output looks like the following\. Make a note of the ARN for the `reportGroup`\. You use it when you create a project that uses this report group\. @@ -78,14 +77,14 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re ``` { "reportGroup": { - "arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/report-name", - "name": "report-name", + "arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/", + "name": "", "type": "TEST", "exportConfig": { "exportConfigType": "S3", "s3Destination": { - "bucket": "s3-bucket-name", - "path": "folder-path", + "bucket": "", + "path": "", "packaging": "NONE", "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" } @@ -98,11 +97,11 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re ## Configure a project with a report group - To run a report, you first create a CodeBuild build project that is configured with your report group\. Test cases specified for your report group are run when you run a build\. +To run a report, you first create a CodeBuild build project that is configured with your report group\. Test cases specified for your report group are run when you run a build\. -1. Create a buildspec file named `buildspec.yml`\. +1. Create a buildspec file named `buildspec.yml`\. -1. Use the following YAML as a template for your `buildspec.yml` file\. Be sure to include the commands that run your tests\. In the `reports` section, specify the files that contain the results of your test cases\. These files store the test results you can access with CodeBuild\. They expire 30 days after they are created\. These files are different from the raw test case result files you export to an S3 bucket\. +1. Use the following YAML as a template for your `buildspec.yml` file\. Be sure to include the commands that run your tests\. In the `reports` section, specify the files that contain the results of your test cases\. These files store the test results you can access with CodeBuild\. They expire 30 days after they are created\. These files are different from the raw test case result files you export to an S3 bucket\. ``` version: 0.2 @@ -113,29 +112,29 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re build: commands: - echo Running tests - - enter commands to run your tests + - reports: - report-name-or-arn: #test file information + : #test file information files: - - 'test-result-files' - base-directory: 'optional-base-directory' + - '' + base-directory: '' discard-paths: false #do not remove file paths from test result files ``` **Note** - Instead of the ARN of an existing report group, you can also specify a name for a report group that has not been created\. If you specify a name instead of an ARN, CodeBuild creates a report group when it runs a build\. Its name contains your project name and the name you specify in the buildspec file, in this format: `project-name-report-group-name`\. For more information, see [Create a test report](report-create.md) and [Report group naming](test-report-group-naming.md)\. +Instead of the ARN of an existing report group, you can also specify a name for a report group that has not been created\. If you specify a name instead of an ARN, CodeBuild creates a report group when it runs a build\. Its name contains your project name and the name you specify in the buildspec file, in this format: `project-name-report-group-name`\. For more information, see [Create a test report](report-create.md) and [Report group naming](test-report-group-naming.md)\. -1. Create a file named `project.json`\. This file contains input for the create\-project command\. +1. Create a file named `project.json`\. This file contains input for the create\-project command\. -1. Copy the following JSON into `project.json`\. For `source`, enter the type and location of the repository that contains your source files\. For `serviceRole`, specify the ARN of the role you are using\. +1. Copy the following JSON into `project.json`\. For `source`, enter the type and location of the repository that contains your source files\. For `serviceRole`, specify the ARN of the role you are using\. ``` { "name": "test-report-project", "description": "sample-test-report-project", "source": { - "type": "your-repository-type", - "location": "https://github.com/your-repository/your-folder" + "type": "CODECOMMIT|CODEPIPELINE|GITHUB|S3|BITBUCKET|GITHUB_ENTERPRISE|NO_SOURCE", + "location": "" }, "artifacts": { "type": "NO_ARTIFACTS" @@ -148,42 +147,36 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "image": "aws/codebuild/standard:4.0", "computeType": "small" }, - "serviceRole": "arn:aws:iam:your-aws-account-id:role/service-role/your-role-name" + "serviceRole": "arn:aws:iam:::role/service-role/" } ``` -1. Run the following command in the directory that contains `project.json`\. This creates a project named `test-project`\. +1. Run the following command in the directory that contains `project.json`\. This creates a project named `test-project`\. ``` - aws codebuild create-project \ - --cli-input-json file://project.json \ - --region your-region + aws codebuild create-project --cli-input-json file://project.json ``` ## Run and view results of a report - In this section, you run a build of the project you created earlier\. During the build process, CodeBuild creates a report with the results of the test cases\. The report is contained in the report group you specified\. +In this section, you run a build of the project you created earlier\. During the build process, CodeBuild creates a report with the results of the test cases\. The report is contained in the report group you specified\. -1. To start a build, run the following command\. Make a note of the build ID that appears in the output\. Its format is `test-report>:build-id`\. +1. To start a build, run the following command\. `test-report-project` is the name of the build project created above\. Make a note of the build ID that appears in the output\. ``` - aws codebuild start-build --project-name "test-project" --region your-region + aws codebuild start-build --project-name test-report-project ``` -1. Run the following command to get information about your build, including the ARN of your report\. For `--ids`, specify your build ID\. Make a note of the report ARN in the output\. +1. Run the following command to get information about your build, including the ARN of your report\. For ``, specify your build ID\. Make a note of the report ARN in the `reportArns` property of the output\. ``` - aws codebuild batch-get-builds \ - --ids "build-id" \ - --region your-region + aws codebuild batch-get-builds --ids ``` -1. Run the following command to get details about your reports\. For `--report-group-arn`, specify your report ARN\. +1. Run the following command to get details about your report\. For ``, specify your report ARN\. ``` - aws codebuild batch-get-reports \ - --report-arns report-group-arn \ - --region your-region + aws codebuild batch-get-reports --report-arns ``` The output looks like the following\. This sample output shows how many of the tests were successful, failed, skipped, resulted in an error, or return an unknown status\. @@ -193,23 +186,23 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "reports": [ { "status": "FAILED", - "reportGroupArn": "report-group-arn", - "name": "report-group-name", + "reportGroupArn": "", + "name": "", "created": 1573324770.154, "exportConfig": { "exportConfigType": "S3", "s3Destination": { - "bucket": "your-s3-bucket", - "path": "path-to-your-report-results", + "bucket": "", + "path": "", "packaging": "NONE", - "encryptionKey": "encryption-key" + "encryptionKey": "" } }, "expired": 1575916770.0, "truncated": false, - "executionId": "arn:aws:codebuild:us-west-2:123456789012:build/name-of-build-project:2c254862-ddf6-4831-a53f-6839a73829c1", + "executionId": "arn:aws:codebuild:us-west-2:123456789012:build/:2c254862-ddf6-4831-a53f-6839a73829c1", "type": "TEST", - "arn": "report-arn", + "arn": "", "testSummary": { "durationInNanoSeconds": 6657770, "total": 11, @@ -227,13 +220,12 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re } ``` -1. Run the following command to list information about test cases for your report\. For `--report-arn`, specify the ARN of your report\. For the optional `--filter` parameter, you can specify one status result \(`SUCCEEDED`, `FAILED`, `SKIPPED`, `ERROR`, or `UNKNOWN`\)\. +1. Run the following command to list information about test cases for your report\. For ``, specify the ARN of your report\. For the optional `--filter` parameter, you can specify one status result \(`SUCCEEDED`, `FAILED`, `SKIPPED`, `ERROR`, or `UNKNOWN`\)\. ``` aws codebuild describe-test-cases \ - --report-arn report-arn \ - --filter status=SUCCEEDED|FAILED|SKIPPED|ERROR|UNKNOWN \ - --region your-region + --report-arn \ + --filter status=SUCCEEDED|FAILED|SKIPPED|ERROR|UNKNOWN ``` The output looks like the following\. @@ -245,21 +237,21 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "status": "FAILED", "name": "Test case 1", "expired": 1575916770.0, - "reportArn": "report-arn", + "reportArn": "", "prefix": "Cucumber tests for agent", "message": "A test message", "durationInNanoSeconds": 1540540, - "testRawDataPath": "path-to-output-report-files" + "testRawDataPath": "" }, { "status": "SUCCEEDED", "name": "Test case 2", "expired": 1575916770.0, - "reportArn": "report-arn", + "reportArn": "", "prefix": "Cucumber tests for agent", "message": "A test message", "durationInNanoSeconds": 1540540, - "testRawDataPath": "path-to-output-report-files" + "testRawDataPath": "" } ] } diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index 74c867a..355e436 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -1,6 +1,6 @@ # Microsoft Windows samples for CodeBuild -These samples use an AWS CodeBuild build environment running Microsoft Windows Server 2019, the \.NET Framework, and the \.NET Core SDK to build executables file out of code written in C\#, F\#, and Visual Basic\. +These samples use an AWS CodeBuild build environment running Microsoft Windows Server 2019, the \.NET Framework, and the \.NET Core SDK to build runtime files out of code written in F\# and Visual Basic\. **Important** Running these samples might result in charges to your AWS account\. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, and CloudWatch Logs\. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon S3 pricing](http://aws.amazon.com/s3/pricing), [AWS Key Management Service pricing](http://aws.amazon.com/kms/pricing), and [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing)\. @@ -14,7 +14,7 @@ Running these samples might result in charges to your AWS account\. These includ Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. If you are using an S3 input bucket, be sure to create a ZIP file that contains the files, and then upload it to the input bucket\. Do not add `(root directory name)` to the ZIP file, just the files inside of `(root directory name)`\. -1. Create a build project, run the build, and follow the steps in [Run AWS CodeBuild directly](how-to-run.md)\. +1. Create a build project\. The build project must use the `mcr.microsoft.com/dotnet/framework/sdk:4.8` image to build \.NET Framework projects\. If you use the AWS CLI to create the build project, the JSON\-formatted input to the `create-project` command might look similar to this\. \(Replace the placeholders with your own values\.\) @@ -33,7 +33,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains }, "environment": { "type": "WINDOWS_SERVER_2019_CONTAINER", - "image": "aws/codebuild/windows-base:2019-1.0", + "image": "mcr.microsoft.com/dotnet/framework/sdk:4.8", "computeType": "BUILD_GENERAL1_MEDIUM" }, "serviceRole": "arn:aws:iam::account-ID:role/role-name", @@ -41,264 +41,53 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains } ``` -1. To get the build output artifact, in your S3 output bucket, download the `windows-build-output-artifact.zip` file to your local computer or instance\. Extract the contents to get to the executable and other files\. - + The executable file for the C\# sample using the \.NET Framework, `CSharpHelloWorld.exe`, can be found in the `CSharpHelloWorld\bin\Debug` directory\. - + The executable file for the F\# sample using the \.NET Framework, `FSharpHelloWorld.exe`, can be found in the `FSharpHelloWorld\bin\Debug` directory\. - + The executable file for the Visual Basic sample using the \.NET Framework, `VBHelloWorld.exe`, can be found in the `VBHelloWorld\bin\Debug` directory\. - + The executable file for the C\# sample using \.NET Core, `HelloWorldSample.dll`, can be found in the `bin\Debug\netcoreapp3.1` directory\. +1. Run the build, and follow the steps in [Run CodeBuild directly](how-to-run.md)\. + +1. To get the build output artifact, in your S3 output bucket, download the `windows-build-output-artifact.zip` file to your local computer or instance\. Extract the contents to get to the runtime and other files\. + + The runtime file for the F\# sample using the \.NET Framework, `FSharpHelloWorld.exe`, can be found in the `FSharpHelloWorld\bin\Debug` directory\. + + The runtime file for the Visual Basic sample using the \.NET Framework, `VBHelloWorld.exe`, can be found in the `VBHelloWorld\bin\Debug` directory\. ## Directory structure These samples assume the following directory structures\. -### C\# and the \.NET Framework - -``` -(root directory name) - |-- buildspec.yml - |-- CSharpHelloWorld.sln - `-- CSharpHelloWorld - |-- App.config - |-- CSharpHelloWorld.csproj - |-- Program.cs - `-- Properties - `-- AssemblyInfo.cs -``` - ### F\# and the \.NET Framework ``` (root directory name) - |-- buildspec.yml - |-- FSharpHelloWorld.sln - `-- FSharpHelloWorld - |-- App.config - |-- AssemblyInfo.fs - |-- FSharpHelloWorld.fsproj - `-- Program.fs +├── buildspec.yml +├── FSharpHelloWorld.sln +└── FSharpHelloWorld + ├── App.config + ├── AssemblyInfo.fs + ├── FSharpHelloWorld.fsproj + └── Program.fs ``` ### Visual Basic and the \.NET Framework ``` (root directory name) - |-- buildspec.yml - |-- VBHelloWorld.sln - `-- VBHelloWorld - |-- App.config - |-- HelloWorld.vb - |-- VBHelloWorld.vbproj - `-- My Project - |-- Application.Designer.vb - |-- Application.myapp - |-- AssemblyInfo.vb - |-- Resources.Designer.vb - |-- Resources.resx - |-- Settings.Designer.vb - `-- Settings.settings -``` - -### C\# and \.NET Core - -``` -(root directory name) - |-- buildspec.yml - |-- HelloWorldSample.csproj - `-- Program.cs +├── buildspec.yml +├── VBHelloWorld.sln +└── VBHelloWorld + ├── App.config + ├── HelloWorld.vb + ├── VBHelloWorld.vbproj + └── My Project + ├── Application.Designer.vb + ├── Application.myapp + ├── AssemblyInfo.vb + ├── Resources.Designer.vb + ├── Resources.resx + ├── Settings.Designer.vb + └── Settings.settings ``` ## Files These samples use the following files\. -### C\# and the \.NET Framework - -`buildspec.yml` \(in `(root directory name)`\): - -``` -version: 0.2 - -env: - variables: - SOLUTION: .\CSharpHelloWorld.sln - PACKAGE_DIRECTORY: .\packages - DOTNET_FRAMEWORK: 4.8 - -phases: - build: - commands: - - '& "C:\ProgramData\chocolatey\bin\NuGet.exe" restore $env:SOLUTION -PackagesDirectory $env:PACKAGE_DIRECTORY' - - '& "C:\Program Files (x86)\MSBuild\14.0\Bin\MSBuild.exe" -p:FrameworkPathOverride="C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v$env:DOTNET_FRAMEWORK" $env:SOLUTION' -artifacts: - files: - - .\CSharpHelloWorld\bin\Debug\* -``` - -`CSharpHelloWorld.sln` \(in `(root directory name)`\): - -``` -Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio 14 -VisualStudioVersion = 14.0.25420.1 -MinimumVisualStudioVersion = 10.0.40219.1 -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CSharpHelloWorld", "CSharpHelloWorld\CSharpHelloWorld.csproj", "{2F8752D5-E628-4A38-AA7E-BC4B4E697CBB}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Release|Any CPU = Release|Any CPU - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {2F8752D5-E628-4A38-AA7E-BC4B4E697CBB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {2F8752D5-E628-4A38-AA7E-BC4B4E697CBB}.Debug|Any CPU.Build.0 = Debug|Any CPU - {2F8752D5-E628-4A38-AA7E-BC4B4E697CBB}.Release|Any CPU.ActiveCfg = Release|Any CPU - {2F8752D5-E628-4A38-AA7E-BC4B4E697CBB}.Release|Any CPU.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection -EndGlobal -``` - -`App.config` \(in `(root directory name)\CSharpHelloWorld`\): - -``` - - - - - - -``` - -`CSharpHelloWorld.csproj` \(in `(root directory name)\CSharpHelloWorld`\): - -``` - - - - - Debug - AnyCPU - {2F8752D5-E628-4A38-AA7E-BC4B4E697CBB} - Exe - Properties - CSharpHelloWorld - CSharpHelloWorld - v4.8 - 512 - true - - - AnyCPU - true - full - false - bin\Debug\ - DEBUG;TRACE - prompt - 4 - - - AnyCPU - pdbonly - true - bin\Release\ - TRACE - prompt - 4 - - - - - - - - - - - - - - - - - - - - - -``` - -`Program.cs` \(in `(root directory name)\CSharpHelloWorld`\): - -``` -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; - -namespace CSharpHelloWorld -{ - class Program - { - static void Main(string[] args) - { - System.Console.WriteLine("Hello World"); - System.Threading.Thread.Sleep(10); - } - } -} -``` - -`AssemblyInfo.cs` \(in `(root directory name)\CSharpHelloWorld\Properties`\): - -``` -using System.Reflection; -using System.Runtime.CompilerServices; -using System.Runtime.InteropServices; - -// General Information about an assembly is controlled through the following -// set of attributes. Change these attribute values to modify the information -// associated with an assembly. -[assembly: AssemblyTitle("CSharpHelloWorld")] -[assembly: AssemblyDescription("")] -[assembly: AssemblyConfiguration("")] -[assembly: AssemblyCompany("")] -[assembly: AssemblyProduct("CSharpHelloWorld")] -[assembly: AssemblyCopyright("Copyright © 2017")] -[assembly: AssemblyTrademark("")] -[assembly: AssemblyCulture("")] - -// Setting ComVisible to false makes the types in this assembly not visible -// to COM components. If you need to access a type in this assembly from -// COM, set the ComVisible attribute to true on that type. -[assembly: ComVisible(false)] - -// The following GUID is for the ID of the typelib if this project is exposed to COM -[assembly: Guid("2f8752d5-e628-4a38-aa7e-bc4b4e697cbb")] - -// Version information for an assembly consists of the following four values: -// -// Major Version -// Minor Version -// Build Number -// Revision -// -// You can specify all the values or you can default the Build and Revision Numbers -// by using the '*' as shown below: -// [assembly: AssemblyVersion("1.0.*")] -[assembly: AssemblyVersion("1.0.0.0")] -[assembly: AssemblyFileVersion("1.0.0.0")] -``` - ### F\# and the \.NET Framework `buildspec.yml` \(in `(root directory name)`\): @@ -315,8 +104,8 @@ env: phases: build: commands: - - '& "C:\ProgramData\chocolatey\bin\NuGet.exe" restore $env:SOLUTION -PackagesDirectory $env:PACKAGE_DIRECTORY' - - '& "C:\Program Files (x86)\MSBuild\14.0\Bin\MSBuild.exe" -p:FrameworkPathOverride="C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v$env:DOTNET_FRAMEWORK" $env:SOLUTION' + - '& nuget restore $env:SOLUTION -PackagesDirectory $env:PACKAGE_DIRECTORY' + - '& msbuild -p:FrameworkPathOverride="C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v$env:DOTNET_FRAMEWORK" $env:SOLUTION' artifacts: files: - .\FSharpHelloWorld\bin\Debug\* @@ -1039,49 +828,4 @@ End Namespace -``` - -### C\# and \.NET Core - -`buildspec.yml` \(in `(root directory name)` - -``` -version: 0.2 - -phases: - build: - commands: - - dotnet restore - - dotnet build -artifacts: - files: - - .\bin\Debug\netcoreapp3.1\* -``` - -`HelloWorldSample.csproj` \(in `(root directory name)` - -``` - - - Exe - netcoreapp3.1 - - -``` - -`Program.cs` \(in `(root directory name)` - -``` -using System; - -namespace HelloWorldSample -{ - public static class Program - { - public static void Main() - { - Console.WriteLine("Hello World!"); - } - } -} ``` \ No newline at end of file diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 0857140..e260b00 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -1,10 +1,10 @@ # Data encryption - Encryption is an important part of CodeBuild security\. Some encryption, such as for data in\-transit, is provided by default and does not require you to do anything\. Other encryption, such as for data at\-rest, you can configure when you create your project or build\. -+ **Encryption of data at\-rest** \- Build artifacts, such as a cache, logs, exported raw test report data files, and build results, are encrypted by default using *customer master keys* \(CMKs\) for Amazon S3 that are managed by the AWS Key Management Service\. If you do not want to use these CMKs, you must create and configure a customer\-managed CMK\. For more information [Creating KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) and [AWS Key Management Service concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) in the *AWS Key Management Service User Guide*\. - + You can store the identifier of the AWS KMS key that CodeBuild uses to encrypt the build output artifact in the `CODEBUILD_KMS_KEY_ID` environment variable\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md) - + You can specify a customer\-managed CMK when you create a build project\. For more information, see [Set the Encryption Key Using the Console](create-project-console.md#encryptionkey-console) and [Set the Encryption Key Using the CLI](create-project-cli.md#encryptionkey-cli)\. +Encryption is an important part of CodeBuild security\. Some encryption, such as for data in\-transit, is provided by default and does not require you to do anything\. Other encryption, such as for data at\-rest, you can configure when you create your project or build\. ++ **Encryption of data at\-rest** \- Build artifacts, such as a cache, logs, exported raw test report data files, and build results, are encrypted by default using AWS managed keys\. If you do not want to use these KMS keys, you must create and configure a customer managed key\. For more information [Creating KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) and [AWS Key Management Service concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) in the *AWS Key Management Service User Guide*\. + + You can store the identifier of the AWS KMS key that CodeBuild uses to encrypt the build output artifact in the `CODEBUILD_KMS_KEY_ID` environment variable\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md) + + You can specify a customer managed key when you create a build project\. For more information, see [Set the Encryption Key Using the Console](create-project-console.md#encryptionkey-console) and [Set the encryption key using the CLI](create-project-cli.md#cli.encryptionkey)\. - The Amazon Elastic Block Store volumes of your build fleet are encrypted by default using CMKs managed by AWS\. -+ **Encryption of data in\-transit** \- All communication between customers and CodeBuild and between CodeBuild and its downstream dependencies is protected using TLS connections that are signed using the Signature Version 4 signing process\. All CodeBuild endpoints use SHA\-256 certificates that are managed by AWS Certificate Manager Private Certificate Authority\. For more information, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) and [What is ACM PCA](https://docs.aws.amazon.com/acm-pca/latest/userguide/)\. -+ **Build artifact encryption** \- CodeBuild requires access to an AWS KMS CMK in order to encrypt its build output artifacts\. By default, CodeBuild uses an AWS Key Management Service CMK for Amazon S3 in your AWS account\. If you do not want to use this CMK, you must create and configure a customer\-managed CMK\. For more information [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file + The Amazon Elastic Block Store volumes of your build fleet are encrypted by default using AWS managed keys\. ++ **Encryption of data in\-transit** \- All communication between customers and CodeBuild and between CodeBuild and its downstream dependencies is protected using TLS connections that are signed using the Signature Version 4 signing process\. All CodeBuild endpoints use SHA\-256 certificates that are managed by AWS Certificate Manager Private Certificate Authority\. For more information, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) and [What is ACM PCA](https://docs.aws.amazon.com/acm-pca/latest/userguide/)\. ++ **Build artifact encryption** \- The CodeBuild service role associated with the build project requires access to a KMS key in order to encrypt its build output artifacts\. By default, CodeBuild uses an AWS managed key for Amazon S3 in your AWS account\. If you do not want to use this AWS managed key, you must create and configure a customer managed key\. For more information, see [Creating a customer managed key](setting-up.md#setting-up-kms) and [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS KMS Developer Guide*\. \ No newline at end of file diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index 495e7da..5e57830 100644 --- a/doc_source/security-key-management.md +++ b/doc_source/security-key-management.md @@ -1,7 +1,7 @@ # Key management - You can protect your content from unauthorized use through encryption\. Store your encryption keys in AWS Secrets Manager, and then give CodeBuild permission to obtain the encryption keys from your Secrets Manager account\. For more information, see [Create and configure an AWS KMS CMK for CodeBuild](setting-up.md#setting-up-kms), [Create a build project in AWS CodeBuild](create-project.md), [Run a build in AWS CodeBuild](run-build.md), and [Tutorial: Storing and retrieving a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html)\. +You can protect your content from unauthorized use through encryption\. Store your encryption keys in AWS Secrets Manager, and then give the CodeBuild service role associated with the build project permission to obtain the encryption keys from your Secrets Manager account\. For more information, see [Create and configure a customer managed key for CodeBuild](setting-up.md#setting-up-kms), [Create a build project in AWS CodeBuild](create-project.md), [Run a build in AWS CodeBuild](run-build.md), and [Tutorial: Storing and retrieving a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/tutorials_basic.html)\. - Use the `CODEBUILD_KMS_KEY` environment variable in a build command for your AWS KMS key\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. +Use the `CODEBUILD_KMS_KEY_ID` environment variable in a build command to obtain the AWS KMS key identifier\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. - You can use Secrets Manager to protect credentials to a private registry that stores a Docker image used for your runtime environment\. For more information, see [ Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md)\. \ No newline at end of file +You can use Secrets Manager to protect credentials to a private registry that stores a Docker image used for your runtime environment\. For more information, see [ Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md)\. \ No newline at end of file diff --git a/doc_source/security-traffic-privacy.md b/doc_source/security-traffic-privacy.md index 01ba121..691f960 100644 --- a/doc_source/security-traffic-privacy.md +++ b/doc_source/security-traffic-privacy.md @@ -1,3 +1,3 @@ # Traffic privacy - You can improve the security of your builds by configuring CodeBuild to use an interface VPC endpoint\. To do this, you do not need an internet gateway, NAT device, or virtual private gateway\. It also is not required to configure PrivateLink, though it is recommended\. For more information, see [Use VPC endpoints](use-vpc-endpoints-with-codebuild.md)\. For more information about PrivateLink and VPC endpoints, see [AWS PrivateLink](https://aws.amazon.com/privatelink/) and [Accessing AWS services through PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html#what-is-privatelink)\. \ No newline at end of file +You can improve the security of your builds by configuring CodeBuild to use an interface VPC endpoint\. To do this, you do not need an internet gateway, NAT device, or virtual private gateway\. It also is not required to configure PrivateLink, though it is recommended\. For more information, see [Use VPC endpoints](use-vpc-endpoints-with-codebuild.md)\. For more information about PrivateLink and VPC endpoints, see [AWS PrivateLink](https://aws.amazon.com/privatelink/) and [Accessing AWS services through PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html#what-is-privatelink)\. \ No newline at end of file diff --git a/doc_source/security.md b/doc_source/security.md index 6d42c9f..611c3d2 100644 --- a/doc_source/security.md +++ b/doc_source/security.md @@ -11,4 +11,5 @@ To learn how to secure your CodeBuild resources, see the following topics\. + [Identity and access management in AWS CodeBuild](auth-and-access-control.md) + [Compliance validation for AWS CodeBuild](codebuild-compliance-validation.md) + [Resilience in AWS CodeBuild](codebuild-disaster-recovery-resiliency.md) -+ [Infrastructure security in AWS CodeBuild](infrastructure-security.md) \ No newline at end of file ++ [Infrastructure security in AWS CodeBuild](infrastructure-security.md) ++ [Access your source provider in CodeBuild](access-tokens.md) \ No newline at end of file diff --git a/doc_source/sample-lambda.md b/doc_source/serverless-applications.md similarity index 64% rename from doc_source/sample-lambda.md rename to doc_source/serverless-applications.md index 36eb55c..0de8156 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/serverless-applications.md @@ -1,10 +1,10 @@ -# AWS Lambda sample for CodeBuild +# Use AWS CodeBuild with serverless applications The AWS Serverless Application Model \(AWS SAM\) is an open\-source framework for building serverless applications\. For more information, see the [AWS serverless application model](https://github.com/awslabs/serverless-application-model) repository on GitHub\. You can use AWS CodeBuild to package and deploy serverless applications that follow the AWS SAM standard\. For the deployment step, CodeBuild can use AWS CloudFormation\. To automate the building and deployment of serverless applications with CodeBuild and AWS CloudFormation, you can use AWS CodePipeline\. -For more information, see [Deploying Lambda\-based applications](https://docs.aws.amazon.com/lambda/latest/dg/deploying-lambda-apps.html) in the *AWS Lambda Developer Guide*\. To experiment with a serverless application sample that uses CodeBuild along with AWS Lambda, AWS CloudFormation, and CodePipeline, see [Automating deployment of Lambda\-based applications](https://docs.aws.amazon.com/lambda/latest/dg/automating-deployment.html) in the *AWS Lambda Developer Guide*\. +For more information, see [Deploying Serverless Applications](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-deploying.html) in the *AWS Serverless Application Model Developer Guide*\. ## Related resources + For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md index 1e2928c..2c74fa1 100644 --- a/doc_source/session-manager.md +++ b/doc_source/session-manager.md @@ -2,6 +2,9 @@ In AWS CodeBuild, you can pause a running build and then use AWS Systems Manager Session Manager to connect to the build container and view the state of the container\. +**Note** +This feature is not available in Windows environments\. + **Topics** + [Prerequisites](#ssm.prerequisites) + [Pause the build](#ssm-pause-build) @@ -16,7 +19,7 @@ To allow Session Manager to be used with the build session, you must enable sess If you are using a custom image for your build, do the following: - 1. Install the SSM Agent\. For more information, see [Manually install SSM Agent on EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html) in the AWS Systems Manager User Guide\. + 1. Install the SSM Agent\. For more information, see [Manually install SSM Agent on EC2 instances for Linux](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html) in the AWS Systems Manager User Guide\. The SSM Agent version must be 3\.0\.1295\.0 or later\. 1. Copy the file [https://github\.com/aws/aws\-codebuild\-docker\-images/blob/master/ubuntu/standard/4\.0/amazon\-ssm\-agent\.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/4.0/amazon-ssm-agent.json) to the `/etc/amazon/ssm/` directory in your image\. This enables Container Mode in the SSM agent\. + The CodeBuild service role must have the following SSM policy: @@ -34,7 +37,54 @@ To allow Session Manager to be used with the build session, you must enable sess } ``` - The CodeBuild console will automatically attach this policy to your service role when you enable session connection for the build\. Alternatively, you can attach this policy to your service role manually\. + You can have the CodeBuild console automatically attach this policy to your service role when you start the build\. Alternatively, you can attach this policy to your service role manually\. ++ If you have **Auditing and logging session activity** enabled in Systems Manager preferences, the CodeBuild service role must also have additional permissions\. The permissions are different, depending on where the logs are stored\. +CloudWatch Logs +If using CloudWatch Logs to store your logs, add the following permission to the CodeBuild service role: + + ``` + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "logs:DescribeLogGroups", + "Resource": "arn:aws:logs:::log-group:*:*" + }, + { + "Effect": "Allow", + "Action": [ + "logs:CreateLogStream", + "logs:PutLogEvents" + ], + "Resource": "arn:aws:logs:::log-group::*" + } + ] + } + ``` +Amazon S3 +If using Amazon S3 to store your logs, add the following permission to the CodeBuild service role: + + ``` + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:GetEncryptionConfiguration", + "s3:PutObject" + ], + "Resource": [ + "arn:aws:s3:::", + "arn:aws:s3:::/*" + ] + } + ] + } + ``` + + For more information, see [Auditing and logging session activity](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-logging-auditing.html) in the *AWS Systems Manager User Guide*\. ## Pause the build @@ -65,6 +115,8 @@ To allow Session Manager to be used with the build session, you must enable sess 1. In the **Environment** section, choose the **Enable session connection** option\. If this option is not selected, all of the codebuild\-breakpoint and codebuild\-resume commands are ignored\. +1. In the **Environment** section, choose the **Allow AWS CodeBuild to modify this service role so it can be used with this build project** option to allow the CodeBuild console to automatically attach the session manager policy to your service role\. If you have already added the session manager policy to your role, you do not need to select this option\. + 1. Make any other desired changes, and choose **Start build**\. 1. Monitor the build status in the console\. When the session is available, the **AWS Session Manager** link appears in the **Build status** section\. @@ -79,13 +131,13 @@ In a web browser, open the **AWS Session Manager** link to connect to the build AWS CLI Your local machine must have the Session Manager plugin installed for this procedure\. For more information, see [Install the Session Manager Plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) in the AWS Systems Manager User Guide\. -1. Call the batch\-get\-builds api with the build ID to get information about the build\. +1. Call the batch\-get\-builds api with the build ID to get information about the build, including the session target identifier\. The session target identifier property name varies depending on the output type of the `aws` command\. This is why `--output json` is added to the command\. ``` - aws codebuild batch-get-builds --ids --region + aws codebuild batch-get-builds --ids --region --output json ``` -1. Copy the `sessionTarget` property value\. +1. Copy the `sessionTarget` property value\. The `sessionTarget` property name can vary depending on the output type of the `aws` command\. This is why `--output json` is added to the command in the previous step\. 1. Use the following command to connect to the build container\. diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index 493b9c1..7987a75 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -1,13 +1,13 @@ # Advanced setup -If you follow the steps in [Getting started using the console](getting-started.md) to access AWS CodeBuild for the first time, you most likely do not need the information in this topic\. However, as you continue using CodeBuild, you might want to do things such as give IAM groups and users in your organization access to CodeBuild, modify existing service roles in IAM or customer master keys in AWS KMS to access CodeBuild, or set up the AWS CLI across your organization's workstations to access CodeBuild\. This topic describes how to complete the related setup steps\. +If you follow the steps in [Getting started using the console](getting-started.md) to access AWS CodeBuild for the first time, you most likely do not need the information in this topic\. However, as you continue using CodeBuild, you might want to do things such as give IAM groups and users in your organization access to CodeBuild, modify existing service roles in IAM or AWS KMS keys to access CodeBuild, or set up the AWS CLI across your organization's workstations to access CodeBuild\. This topic describes how to complete the related setup steps\. We assume you already have an AWS account\. However, if you do not already have one, go to [http://aws\.amazon\.com](http://aws.amazon.com), choose **Sign In to the Console**, and follow the online instructions\. **Topics** + [Add CodeBuild access permissions to an IAM group or IAM user](#setting-up-service-permissions-group) + [Create a CodeBuild service role](#setting-up-service-role) -+ [Create and configure an AWS KMS CMK for CodeBuild](#setting-up-kms) ++ [Create and configure a customer managed key for CodeBuild](#setting-up-kms) + [Install and configure the AWS CLI](#setting-up-cli) ## Add CodeBuild access permissions to an IAM group or IAM user @@ -64,13 +64,20 @@ For information about AWS root accounts and administrator IAM users, see [The Ac "Version": "2012-10-17", "Statement": [ { - "Sid": "CodeBuildDefaultPolicy", + "Sid": "CodeBuildAccessPolicy", + "Effect": "Allow", + "Action": [ + "codebuild:*" + ], + "Resource": "*" + }, + { + "Sid": "CodeBuildRolePolicy", "Effect": "Allow", "Action": [ - "codebuild:*", "iam:PassRole" ], - "Resource": "*" + "Resource": "arn:aws:iam::account-ID:role/role-name" }, { "Sid": "CloudWatchLogsAccessPolicy", @@ -105,7 +112,8 @@ For information about AWS root accounts and administrator IAM users, see [The Ac } ``` **Note** -This policy allows access to all CodeBuild actions and to a potentially large number of AWS resources\. To restrict permissions to specific CodeBuild actions, change the value of `codebuild:*` in the CodeBuild policy statement\. For more information, see [Identity and access management](auth-and-access-control.md)\. To restrict access to specific AWS resources, change the value of the `Resource` object\. For more information, see [Identity and access management](auth-and-access-control.md)\. +This policy allows access to all CodeBuild actions and to a potentially large number of AWS resources\. To restrict permissions to specific CodeBuild actions, change the value of `codebuild:*` in the CodeBuild policy statement\. For more information, see [Identity and access management](auth-and-access-control.md)\. To restrict access to specific AWS resources, change the value of the `Resource` object\. For more information, see [Identity and access management](auth-and-access-control.md)\. +The `CodeBuildRolePolicy` statement is required to allow a build project to be created or modified\. 1. In the navigation pane, choose **Groups** or **Users**\. @@ -117,7 +125,7 @@ This policy allows access to all CodeBuild actions and to a potentially large nu 1. For a group, on the **Attach Policy** page, select **CodeBuildAccessPolicy**, and then choose **Attach Policy**\. - For a user, on the **Add permisions** page, choose **Attach existing policies directly**\. Select **CodeBuildAccessPolicy**, choose **Next: Reivew**, and then choose **Add permissions**\. + For a user, on the **Add permissions** page, choose **Attach existing policies directly**\. Select **CodeBuildAccessPolicy**, choose **Next: Review**, and then choose **Add permissions**\. **To add CodeBuild access permissions to an IAM group or IAM user \(AWS CLI\)** @@ -159,11 +167,18 @@ This policy allows access to all CodeBuild actions and to a potentially large nu "Sid": "CodeBuildAccessPolicy", "Effect": "Allow", "Action": [ - "codebuild:*", - "iam:PassRole" + "codebuild:*" ], "Resource": "*" }, + { + "Sid": "CodeBuildRolePolicy", + "Effect": "Allow", + "Action": [ + "iam:PassRole" + ], + "Resource": "arn:aws:iam::account-ID:role/role-name" + }, { "Sid": "CloudWatchLogsAccessPolicy", "Effect": "Allow", @@ -197,7 +212,8 @@ This policy allows access to all CodeBuild actions and to a potentially large nu } ``` **Note** -This policy allows access to all CodeBuild actions and to a potentially large number of AWS resources\. To restrict permissions to specific CodeBuild actions, change the value of `codebuild:*` in the CodeBuild policy statement\. For more information, see [Identity and access management](auth-and-access-control.md)\. To restrict access to specific AWS resources, change the value of the related `Resource` object\. For more information, see [Identity and access management](auth-and-access-control.md) or the specific AWS service's security documentation\. +This policy allows access to all CodeBuild actions and to a potentially large number of AWS resources\. To restrict permissions to specific CodeBuild actions, change the value of `codebuild:*` in the CodeBuild policy statement\. For more information, see [Identity and access management](auth-and-access-control.md)\. To restrict access to specific AWS resources, change the value of the related `Resource` object\. For more information, see [Identity and access management](auth-and-access-control.md) or the specific AWS service's security documentation\. +The `CodeBuildRolePolicy` statement is required to allow a build project to be created or modified\. 1. Switch to the directory where you saved the file, and then run one of the following commands\. You can use different values for `CodeBuildGroupAccessPolicy` and `CodeBuildUserAccessPolicy`\. If you use different values, be sure to use them here\. @@ -219,14 +235,15 @@ This policy allows access to all CodeBuild actions and to a potentially large nu You need an AWS CodeBuild service role so that CodeBuild can interact with dependent AWS services on your behalf\. You can create a CodeBuild service role by using the CodeBuild or AWS CodePipeline consoles\. For information, see: + [Create a build project \(console\)](create-project-console.md) -+ [Create a pipeline that uses CodeBuild \(CodePipeline console\)](how-to-create-pipeline.md#how-to-create-pipeline-console) -+ [Add a CodeBuild build action to a pipeline \(CodePipeline console\)](how-to-create-pipeline.md#how-to-create-pipeline-add) -+ [Change a build project's settings \(console\)](change-project.md#change-project-console) ++ [Create a pipeline that uses CodeBuild \(CodePipeline console\)](how-to-create-pipeline-console.md) ++ [Add a CodeBuild build action to a pipeline \(CodePipeline console\)](how-to-create-pipeline-add.md) ++ [Change a build project's settings \(console\)](change-project-console.md) If you do not plan to use these consoles, this section describes how to create a CodeBuild service role with the IAM console or the AWS CLI\. -**Note** -The service role described on this page contains a policy that grants the minimum permissions required to use CodeBuild\. You might need to add additional permissions depending on your use case\. For example, if you want to use CodeBuild with Amazon Virtual Private Cloud, then the service role you create requires the permissions in the following policy: [Create a CodeBuild service role](#setting-up-service-role)\. +**Important** +CodeBuild uses the service role for all operations that are performed on your behalf\. If the role includes permissions that the user shouldn't have, you can unintentionally escalate a user's permissions\. Ensure that the role grants [least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege)\. +The service role described on this page contains a policy that grants the minimum permissions required to use CodeBuild\. You may need to add additional permissions, depending on your use case\. **To create a CodeBuild service role \(console\)** @@ -274,9 +291,7 @@ The service role described on this page contains a policy that grants the minimu "logs:CreateLogStream", "logs:PutLogEvents" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "CodeCommitPolicy", @@ -284,9 +299,7 @@ The service role described on this page contains a policy that grants the minimu "Action": [ "codecommit:GitPull" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3GetObjectPolicy", @@ -295,9 +308,7 @@ The service role described on this page contains a policy that grants the minimu "s3:GetObject", "s3:GetObjectVersion" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3PutObjectPolicy", @@ -305,9 +316,7 @@ The service role described on this page contains a policy that grants the minimu "Action": [ "s3:PutObject" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "ECRPullPolicy", @@ -317,9 +326,7 @@ The service role described on this page contains a policy that grants the minimu "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "ECRAuthPolicy", @@ -327,9 +334,7 @@ The service role described on this page contains a policy that grants the minimu "Action": [ "ecr:GetAuthorizationToken" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3BucketIdentity", @@ -338,8 +343,7 @@ The service role described on this page contains a policy that grants the minimu "s3:GetBucketAcl", "s3:GetBucketLocation" ], - "Resource": - "*" + "Resource": "*" } ] } @@ -398,9 +402,7 @@ If you use a different name, be sure to use it throughout this procedure\. "logs:CreateLogStream", "logs:PutLogEvents" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "CodeCommitPolicy", @@ -408,9 +410,7 @@ If you use a different name, be sure to use it throughout this procedure\. "Action": [ "codecommit:GitPull" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3GetObjectPolicy", @@ -419,9 +419,7 @@ If you use a different name, be sure to use it throughout this procedure\. "s3:GetObject", "s3:GetObjectVersion" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3PutObjectPolicy", @@ -429,9 +427,7 @@ If you use a different name, be sure to use it throughout this procedure\. "Action": [ "s3:PutObject" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3BucketIdentity", @@ -440,9 +436,7 @@ If you use a different name, be sure to use it throughout this procedure\. "s3:GetBucketAcl", "s3:GetBucketLocation" ], - "Resource": [ - "*" - ] + "Resource": "*" } ] } @@ -460,15 +454,15 @@ This policy contains statements that allow access to a potentially large number aws iam put-role-policy --role-name CodeBuildServiceRole --policy-name CodeBuildServiceRolePolicy --policy-document file://put-role-policy.json ``` -## Create and configure an AWS KMS CMK for CodeBuild +## Create and configure a customer managed key for CodeBuild -For AWS CodeBuild to encrypt its build output artifacts, it needs access to an AWS KMS customer master key \(CMK\)\. By default, CodeBuild uses the AWS\-managed CMK for Amazon S3 in your AWS account\. +For AWS CodeBuild to encrypt its build output artifacts, it needs access to a KMS key\. By default, CodeBuild uses the AWS managed key for Amazon S3 in your AWS account\. -If you do not want to use this CMK, you must create and configure a customer\-managed CMK yourself\. This section describes how to do this with the IAM console\. +If you do not want to use the AWS managed key, you must create and configure a customer managed key yourself\. This section describes how to do this with the IAM console\. -For information about CMKs, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) and [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS KMS Developer Guide*\. +For information about customer managed keys, see [AWS Key Management Service Concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) and [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS KMS Developer Guide*\. -To configure a CMK for use by CodeBuild, follow the instructions in the "How to Modify a Key Policy" section of [Modifying a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) in the *AWS KMS Developer Guide*\. Then add the following statements \(between *\#\#\# BEGIN ADDING STATEMENTS HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to the key policy\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statements\. Do not remove any statements, and do not type these ellipses into the key policy\. +To configure a customer managed key for use by CodeBuild, follow the instructions in the "How to Modify a Key Policy" section of [Modifying a Key Policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) in the *AWS KMS Developer Guide*\. Then add the following statements \(between *\#\#\# BEGIN ADDING STATEMENTS HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to the key policy\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statements\. Do not remove any statements, and do not type these ellipses into the key policy\. ``` { @@ -532,14 +526,14 @@ To configure a CMK for use by CodeBuild, follow the instructions in the "How to } ``` + *region\-ID* represents the ID of the AWS region where the Amazon S3 buckets associated with CodeBuild are located \(for example, `us-east-1`\)\. -+ *account\-ID* represents the ID of the of the AWS account that owns the CMK\. ++ *account\-ID* represents the ID of the of the AWS account that owns the customer managed key\. + *CodeBuild\-service\-role* represents the name of the CodeBuild service role you created or identified earlier in this topic\. **Note** -To create or configure a CMK through the IAM console, you must first sign in to the AWS Management Console by using one of the following: +To create or configure a customer managed key through the IAM console, you must first sign in to the AWS Management Console by using one of the following: Your AWS root account\. This is not recommended\. For more information, see [The Account Root User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) in the *IAM User Guide*\. An administrator IAM user in your AWS account\. For more information, see [Creating Your First IAM Admin User and Group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. -An IAM user in your AWS account with permission to create or modify the CMK\. For more information, see [Permissions Required to Use the AWS KMS Console](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html#console-permissions) in the *AWS KMS Developer Guide*\. +An IAM user in your AWS account with permission to create or modify the customer managed key\. For more information, see [Permissions Required to Use the AWS KMS Console](https://docs.aws.amazon.com/kms/latest/developerguide/iam-policies.html#console-permissions) in the *AWS KMS Developer Guide*\. ## Install and configure the AWS CLI diff --git a/doc_source/stop-batch-build.md b/doc_source/stop-batch-build.md new file mode 100644 index 0000000..70b8ccc --- /dev/null +++ b/doc_source/stop-batch-build.md @@ -0,0 +1,41 @@ +# Stop a batch build in AWS CodeBuild + +You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to stop a batch build in AWS CodeBuild\. + +**Topics** ++ [Stop a batch build \(console\)](#stop-batch-build-console) ++ [Stop a batch build \(AWS CLI\)](#stop-batch-build-cli) ++ [Stop a batch build \(AWS SDKs\)](#stop-batch-build-sdks) + +## Stop a batch build \(console\) + +1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. + +1. Do one of the following: + + If the ***build\-project\-name*:*build\-ID*** page is displayed, choose **Stop build**\. + + In the navigation pane, choose **Build history**\. In the list of builds, select the box for the build, and then choose **Stop build**\. + + In the navigation pane, choose **Build projects**\. In the list of build projects, in the **Name** column, choose the link for the build project's name\. In the list of builds, select the box for the build, and then choose **Stop build**\. + +**Note** +By default, only the most recent 100 builds or build projects are displayed\. To view more builds or build projects, choose the gear icon, and then choose a different value for **Builds per page** or **Projects per page** or use the back and forward arrows\. +If AWS CodeBuild cannot successfully stop a batch build \(for example, if the build process is already complete\), the **Stop build** button is disabled\. + +## Stop a batch build \(AWS CLI\) ++ Run the [https://docs.aws.amazon.com/cli/latest/reference/codebuild/stop-build-batch.html](https://docs.aws.amazon.com/cli/latest/reference/codebuild/stop-build-batch.html) command: + + ``` + aws codebuild stop-build-batch --id + ``` + + In the preceding command, replace the following placeholder: + + **: Required string\. The identifier of the batch build to stop\. To get a list of batch build identifiers, see the following topics: + + [View a list of batch build IDs \(AWS CLI\)](view-build-list.md#view-batch-build-list-cli) + + [View a list of batch build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-batch-builds-for-project-cli) + + If AWS CodeBuild successfully stops the batch build, the `buildBatchStatus` value in the `buildBatch` object in the output is `STOPPED`\. + + If CodeBuild cannot successfully stop the batch build \(for example, if the batch build is already complete\), the `buildBatchStatus` value in the `buildBatch` object in the output is the final build status \(for example, `SUCCEEDED`\)\. + +## Stop a batch build \(AWS SDKs\) + +For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file diff --git a/doc_source/test-permissions.md b/doc_source/test-permissions.md index 3882e67..a705ce6 100644 --- a/doc_source/test-permissions.md +++ b/doc_source/test-permissions.md @@ -9,16 +9,18 @@ ## Create a role for test reports - To run a test report, and to update a project to include test reports, your IAM role requires the following permissions\. These permissions are included in the predefined AWS managed policies\. If you want to add test reporting to an existing build project, you must add these permissions yourself\. -+ `CreateReportGroup` -+ `CreateReport` -+ `UpdateReport` -+ `BatchPutTestCases` +To run a test report, and to update a project to include test reports, your IAM role requires the following permissions\. These permissions are included in the predefined AWS managed policies\. If you want to add test reporting to an existing build project, you must add these permissions yourself\. ++ `CreateReportGroup` ++ `CreateReport` ++ `UpdateReport` ++ `BatchPutTestCases` + +To run a code coverage report, your IAM role must also include the `BatchPutCodeCoverages` permission\. **Note** - `BatchPutTestCases`, `CreateReport`, and `UpdateReport` are not public permissions\. You cannot call a corresponding AWS CLI command or SDK method for these permissions\. +`BatchPutTestCases`, `CreateReport`, `UpdateReport`, and `BatchPutCodeCoverages` are not public permissions\. You cannot call a corresponding AWS CLI command or SDK method for these permissions\. - To make sure you have these permissions, you can attach the following policy to your IAM role: +To make sure you have these permissions, you can attach the following policy to your IAM role: ``` { @@ -30,12 +32,13 @@ "codebuild:CreateReportGroup", "codebuild:CreateReport", "codebuild:UpdateReport", - "codebuild:BatchPutTestCases" + "codebuild:BatchPutTestCases", + "codebuild:BatchPutCodeCoverages" ] } ``` - We recommend that you restrict this policy to only those report groups you must use\. The following restricts permissions to only the report groups with the two ARNs in the policy: +We recommend that you restrict this policy to only those report groups you must use\. The following restricts permissions to only the report groups with the two ARNs in the policy: ``` { @@ -48,12 +51,13 @@ "codebuild:CreateReportGroup", "codebuild:CreateReport", "codebuild:UpdateReport", - "codebuild:BatchPutTestCases" + "codebuild:BatchPutTestCases", + "codebuild:BatchPutCodeCoverages" ] } ``` - The following restricts permissions to only report groups created by running builds of a project named `my-project`: +The following restricts permissions to only report groups created by running builds of a project named `my-project`: ``` { @@ -65,7 +69,8 @@ "codebuild:CreateReportGroup", "codebuild:CreateReport", "codebuild:UpdateReport", - "codebuild:BatchPutTestCases" + "codebuild:BatchPutTestCases", + "codebuild:BatchPutCodeCoverages" ] } ``` diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md index 034c32a..625ecd3 100644 --- a/doc_source/test-report-group-create-buildspec.md +++ b/doc_source/test-report-group-create-buildspec.md @@ -20,4 +20,5 @@ A report group created using the buildspec does not export raw test result files 1. In the `commands` section, specify the command to run your tests\. For more information, see [ Specify test commands ](report-group-test-case-commands.md)\. -1. Run the build\. When the build is complete, a new report group is created with a name that uses the format `project-name-report-group-name`\. For more information, see [Report group naming](test-report-group-naming.md)\. \ No newline at end of file +1. Run the build\. When the build is complete, a new report group is created with a name that uses the format `project-name-report-group-name`\. For more information, see [Report group naming](test-report-group-naming.md)\. + diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index 78e25f7..c2d8a83 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -1,53 +1,55 @@ # Create a report group \(CLI\) -**To create a test report** +**To create a report group** 1. Create a file named `CreateReportGroup.json`\. -1. Depending on your requirements, copy one of the following JSON code snippets into `CreateReportGroup.json`: +1. Depending on your requirements, copy one of the following JSON code snippets into `CreateReportGroup.json`: + Use the following JSON to specify that your test report group exports raw test result files to an Amazon S3 bucket\. ``` { - "name": "report-name", - "type": "TEST", - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "bucket-name", - "path": "path", - "packaging": "NONE | ZIP", - "encryptionDisabled": "false", - "encryptionKey": "your-key" - }, - "tags": [ - { - "key": "tag-key", - "value": "tag-value" - } - ] + "name": "", + "type": "TEST", + "exportConfig": { + "exportConfigType": "S3", + "s3Destination": { + "bucket": "", + "bucketOwner": "", + "path": "", + "packaging": "NONE | ZIP", + "encryptionDisabled": "false", + "encryptionKey": "" + }, + "tags": [ + { + "key": "tag-key", + "value": "tag-value" + } + ] + } } ``` - - Replace `bucket-name` with your S3 bucket name and `path` with the path in your S3 bucket to where you want to export the files\. If you want to compress the exported files, for `packaging`, specify `ZIP`\. Otherwise, specify `NONE`\. Use `encryptionDisabled` to specify whether to encrypt the exported files\. If you encrypt the exported files, enter your customer master key \(CMK\)\. For more information, see [Update a report group](report-group-export-settings.md)\. + + Replace ** with your Amazon S3 bucket name and ** with the path in your bucket to where you want to export the files\. + + If you want to compress the exported files, for `packaging`, specify `ZIP`\. Otherwise, specify `NONE`\. + + `bucketOwner` is optional and is only required if the Amazon S3 bucket is owned by an account other than the account running the build\. + + Use `encryptionDisabled` to specify whether to encrypt the exported files\. If you encrypt the exported files, enter your customer managed key\. For more information, see [Update a report group](report-group-export-settings.md)\. + Use the following JSON to specify that your test report does not export raw test files: ``` { - "name": "report-name", - "type": "TEST", + "name": "", + "type": "TEST", "exportConfig": { - "exportConfigType": "NO_EXPORT" + "exportConfigType": "NO_EXPORT" } } ``` **Note** The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. -1. Run the following command: +1. Run the following command: ``` - aws codebuild create-report-group \ - --cli-input-json file://CreateReportGroupInput.json \ - --region us-east-2 + aws codebuild create-report-group --cli-input-json file://CreateReportGroupInput.json ``` \ No newline at end of file diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index 85458cb..3c131b3 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -4,30 +4,32 @@ 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. -1. In the navigation pane, choose **Report groups**\. +1. In the navigation pane, choose **Report groups**\. 1. Choose **Create report group**\. 1. For **Report group name**, enter a name for your report group\. -1. \(Optional\) For **Tags**, enter the name and value of any tags that you want supporting AWS services to use\. Use **Add row** to add a tag\. You can add up to 50 tags\. +1. \(Optional\) For **Tags**, enter the name and value of any tags that you want supporting AWS services to use\. Use **Add row** to add a tag\. You can add up to 50 tags\. -1. If you want to upload the raw data of your test report results to an Amazon S3 bucket: +1. If you want to upload the raw data of your test report results to an Amazon S3 bucket: - 1. Select **Backup to Amazon S3**\. + 1. Select **Export to Amazon S3**\. 1. For **S3 bucket name**, enter the name of the S3 bucket\. + 1. \(Optional\) For **S3 bucket owner**, enter the AWS account identifier of the account that owns the S3 bucket\. This allows report data to be exported to an Amazon S3 bucket that is owned by an account other than the account running the build\. + 1. For **Path prefix**, enter the path in your S3 bucket where you want to upload your test results\. - 1. Select **Compress test result data in a zip file** to compress your raw test result data files\. + 1. Select **Compress test result data in a zip file** to compress your raw test result data files\. - 1. Expand **Additional configuration** to display encryption options\. Choose one of the following: - + **Default AWS managed key** to use a customer master key \(CMK\) for Amazon S3 that is managed by the AWS Key Management Service\. In CodeBuild, the default CMK is for Amazon S3 and uses the format `aws/S3`\. For more information, see [Customer managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) in the *AWS Key Management Service User Guide*\. This is the default encryption option\. - + **Choose a custom key** to use a CMK that you create and configure\. For **AWS KMS encryption key**, enter the ARN of your encryption key\. Its format is ` arn:aws:kms:region-id:aws-account-id:key/key-id`\. For more information, see [Creating KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*\. - + **Disable artifact encryption** to disable encryption\. You might choose this if you want to share your test results, or publish them to a static website\. \(A dynamic website can run code to decrypt test results\.\) + 1. Expand **Additional configuration** to display encryption options\. Choose one of the following: + + **Default AWS managed key** to use a AWS managed key for Amazon S3\. For more information, see [Customer managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) in the *AWS Key Management Service User Guide*\. This is the default encryption option\. + + **Choose a custom key** to use a customer managed key that you create and configure\. For **AWS KMS encryption key**, enter the ARN of your encryption key\. Its format is ` arn:aws:kms:: :key/ `\. For more information, see [Creating KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*\. + + **Disable artifact encryption** to disable encryption\. You might choose this if you want to share your test results, or publish them to a static website\. \(A dynamic website can run code to decrypt test results\.\) - For more information about encryption of data at rest, see [Data encryption](security-encryption.md)\. + For more information about encryption of data at rest, see [Data encryption](security-encryption.md)\. **Note** The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. diff --git a/doc_source/test-report-jasmine.md b/doc_source/test-report-jasmine.md index dfbd92a..5a98f23 100644 --- a/doc_source/test-report-jasmine.md +++ b/doc_source/test-report-jasmine.md @@ -3,7 +3,7 @@ The following procedure demonstrates how to set up test reporting in AWS CodeBuild with the [JasmineBDD testing framework](http://jasmine.github.io/)\. The procedure requires the following prerequisites: -+ You have an existing AWS CodeBuild project\. ++ You have an existing CodeBuild project\. + Your project is a Node\.js project that is set up to use the Jasmine testing framework\. Add the [https://www.npmjs.com/package/jasmine-reporters](https://www.npmjs.com/package/jasmine-reporters) package to the `devDependencies` section of your project's `package.json` file\. This package has a collection of JavaScript reporter classes that can be used with Jasmine\. @@ -12,7 +12,7 @@ Add the [https://www.npmjs.com/package/jasmine-reporters](https://www.npmjs.com/ npm install --save-dev jasmine-reporters ``` -If it's not already present, add the `test` script to your project's `package.json` file\. The `test` script ensures that Jasmine is called when npm test is executed\. +If it's not already present, add the `test` script to your project's `package.json` file\. The `test` script ensures that Jasmine is called when npm test is run\. ``` { @@ -22,7 +22,7 @@ If it's not already present, add the `test` script to your project's `package.js } ``` -AWS CodeBuild supports the following Jasmine test reporters: +CodeBuild supports the following Jasmine test reporters: JUnitXmlReporter Used to generate reports in the `JunitXml` format\. @@ -80,12 +80,12 @@ reports: jasmine_reports: files: - - file-format: JunitXml + file-format: JUNITXML base-directory: ``` If you are using the the `NunitXml` report format, change the `file-format` value to the following\. ``` - file-format: NunitXml + file-format: NUNITXML ``` \ No newline at end of file diff --git a/doc_source/test-report-jest.md b/doc_source/test-report-jest.md index 36e6e1e..53e2948 100644 --- a/doc_source/test-report-jest.md +++ b/doc_source/test-report-jest.md @@ -3,16 +3,16 @@ The following procedure demonstrates how to set up test reporting in AWS CodeBuild with the [Jest testing framework](https://jestjs.io/)\. The procedure requires the following prerequisites: -+ You have an existing AWS CodeBuild project\. ++ You have an existing CodeBuild project\. + Your project is a Node\.js project that is set up to use the Jest testing framework\. -Add the [https://www.npmjs.com/package/jest-junit](https://www.npmjs.com/package/jest-junit) package to the `devDependencies` section of your project's `package.json` file\. AWS CodeBuild uses this package to generate reports in the `JunitXml` format\. +Add the [https://www.npmjs.com/package/jest-junit](https://www.npmjs.com/package/jest-junit) package to the `devDependencies` section of your project's `package.json` file\. CodeBuild uses this package to generate reports in the `JunitXml` format\. ``` npm install --save-dev jest-junit ``` -If it's not already present, add the `test` script to your project's `package.json` file\. The `test` script ensures that Jest is called when npm test is executed\. +If it's not already present, add the `test` script to your project's `package.json` file\. The `test` script ensures that Jest is called when npm test is run\. ``` { @@ -54,6 +54,6 @@ reports: jest_reports: files: - - file-format: JunitXml + file-format: JUNITXML base-directory: ``` \ No newline at end of file diff --git a/doc_source/test-report-pytest.md b/doc_source/test-report-pytest.md index b4e6a4b..04b14ff 100644 --- a/doc_source/test-report-pytest.md +++ b/doc_source/test-report-pytest.md @@ -3,7 +3,7 @@ The following procedure demonstrates how to set up test reporting in AWS CodeBuild with the [pytest testing framework](https://docs.pytest.org/)\. The procedure requires the following prerequisites: -+ You have an existing AWS CodeBuild project\. ++ You have an existing CodeBuild project\. + Your project is a Python project that is set up to use the pytest testing framework\. Add the following entry to either the `build` or `post_build` phase of your `buildspec.yml` file\. This code automatically discovers tests in the current directory and exports the test reports to the file specified by **/**\. The report uses the `JunitXml` format\. @@ -32,5 +32,5 @@ reports: files: - base-directory: - file-format: JunitXml + file-format: JUNITXML ``` \ No newline at end of file diff --git a/doc_source/test-report-rspec.md b/doc_source/test-report-rspec.md index 86afeb9..a1e6e67 100644 --- a/doc_source/test-report-rspec.md +++ b/doc_source/test-report-rspec.md @@ -3,7 +3,7 @@ The following procedure demonstrates how to set up test reporting in AWS CodeBuild with the [RSpec testing framework](https://rspec.info/)\. The procedure requires the following prerequisites: -+ You have an existing AWS CodeBuild project\. ++ You have an existing CodeBuild project\. + Your project is a Ruby project that is set up to use the RSpec testing framework\. Add/update the following in your `buildspec.yml` file\. This code runs the tests in the ** directory and exports the test reports to the file specified by **/**\. The report uses the `JunitXml` format\. @@ -27,5 +27,5 @@ reports: files: - base-directory: - file-format: JunitXml + file-format: JUNITXML ``` \ No newline at end of file diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index b3ab5ca..07aa636 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -3,11 +3,15 @@ You can create reports in CodeBuild that contain details about tests that are run during builds\. You can create tests such as unit tests, configuration tests, and functional tests\. The following test report file formats are supported: -+ Cucumber JSON -+ JUnit XML -+ NUnit XML -+ TestNG XML -+ Visual Studio TRX ++ Cucumber JSON \(\.json\) ++ JUnit XML \(\.xml\) ++ NUnit XML \(\.xml\) ++ NUnit3 XML \(\.xml\) ++ TestNG XML \(\.xml\) ++ Visual Studio TRX \(\.trx\) + +**Note** + The latest supported version of `cucumber-js` is 7\.3\.2\. Create your test cases with any test framework that can create report files in one of these formats \(for example, Surefire JUnit plugin, TestNG, or Cucumber\)\. @@ -26,4 +30,5 @@ The CodeBuild service role specified in the project is used for permissions to u + [Working with reports](test-report.md) + [Working with test report permissions](test-permissions.md) + [View test reports](test-view-reports.md) -+ [Test reporting with test frameworks](test-framework-reporting.md) \ No newline at end of file ++ [Test reporting with test frameworks](test-framework-reporting.md) ++ [Code coverage reports](code-coverage-report.md) \ No newline at end of file diff --git a/doc_source/test-view-reports.md b/doc_source/test-view-reports.md index 0f585d6..9191cb0 100644 --- a/doc_source/test-view-reports.md +++ b/doc_source/test-view-reports.md @@ -41,6 +41,8 @@ ## View test reports in your AWS account + + **To view test reports in your AWS account** 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. diff --git a/doc_source/trigger-create.md b/doc_source/trigger-create.md index 0eefff9..8a028af 100644 --- a/doc_source/trigger-create.md +++ b/doc_source/trigger-create.md @@ -1,8 +1,11 @@ # Create AWS CodeBuild triggers - You can create a trigger on a project to schedule a build once every hour, day, or week\. You can also create a trigger using a custom rule with an Amazon CloudWatch cron expression\. For example, using a cron expression, you can schedule a build at a specific time every weekday\. +## Create AWS CodeBuild triggers \(console\) - You create a trigger after you create a project\. +You can create a trigger on a project to schedule a build once every hour, day, or week\. You can also create a trigger using a custom rule with an Amazon CloudWatch cron expression\. For example, using a cron expression, you can schedule a build at a specific time every weekday\. + +**Note** +It is not possible to start a batch build from a build trigger, an Amazon EventBridge event, or an AWS Step Functions task\. **To create a trigger** @@ -36,4 +39,8 @@ By default, the 100 most recent build projects are displayed\. To view more buil 1. \(Optional\) Specify a timeout between 5 minutes and 480 minutes \(8 hours\)\. This value specifies how long AWS CodeBuild attempts a build before it stops\. If **Hours** and **Minutes** are left blank, the default timeout value specified in the project is used\. -1. Choose **Create trigger**\. \ No newline at end of file +1. Choose **Create trigger**\. + +## Create AWS CodeBuild triggers programmatically + +CodeBuild uses Amazon EventBridge rules for build triggers\. You can use the EventBridge API to programmatically create build triggers for your CodeBuild projects\. See [Amazon EventBridge API Reference](https://docs.aws.amazon.com/eventbridge/latest/APIReference/) for more information\. \ No newline at end of file diff --git a/doc_source/triggers-edit.md b/doc_source/triggers-edit.md index ba32512..da3b8f3 100644 --- a/doc_source/triggers-edit.md +++ b/doc_source/triggers-edit.md @@ -1,6 +1,8 @@ # Edit AWS CodeBuild triggers - You can edit a trigger on a project to schedule a build once every hour, day, or week\. You can also edit a trigger to use a custom rule with an Amazon CloudWatch cron expression\. For example, using a cron expression, you can schedule a build at a specific time on every weekday\. For information about creating a trigger, see [Create AWS CodeBuild triggers](trigger-create.md)\. +## Edit AWS CodeBuild triggers \(console\) + +You can edit a trigger on a project to schedule a build once every hour, day, or week\. You can also edit a trigger to use a custom rule with an Amazon CloudWatch cron expression\. For example, using a cron expression, you can schedule a build at a specific time on every weekday\. For information about creating a trigger, see [Create AWS CodeBuild triggers](trigger-create.md)\. **To edit a trigger** @@ -25,4 +27,8 @@ By default, the 100 most recent build projects are displayed\. To view more buil 1. Select **Enable this trigger**\. **Note** -You can use the Amazon CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) to edit source version, timeout, and other options that are not available in AWS CodeBuild\. \ No newline at end of file +You can use the Amazon CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) to edit source version, timeout, and other options that are not available in AWS CodeBuild\. + +## Edit AWS CodeBuild triggers programmatically + +CodeBuild uses Amazon EventBridge rules for build triggers\. You can use the EventBridge API to programmatically edit the build triggers for your CodeBuild projects\. See [Amazon EventBridge API Reference](https://docs.aws.amazon.com/eventbridge/latest/APIReference/) for more information\. \ No newline at end of file diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 3767a93..3853910 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -9,14 +9,13 @@ Use the information in this topic to help you identify, diagnose, and address is + [Builds might fail when getting parameters from Amazon EC2 Parameter Store](#troubleshooting-parameter-store) + [Cannot access branch filter in the CodeBuild console](#troubleshooting-webhook-filter) + [Cannot view build success or failure](#no-status-when-build-triggered) -+ [Cannot view build success or failure](#no-status-when-build-triggered) -+ [Cannot find and select the base image of the Windows Server Core 2016 platform](#windows-image-not-available) ++ [Build status not reported to source provider](#build-status-not-reported) ++ [Cannot find and select the base image of the Windows Server Core 2019 platform](#windows-image-not-available) + [Earlier commands in buildspec files are not recognized by later commands](#troubleshooting-build-spec-commands) + [Error: "Access denied" when attempting to download cache](#troubleshooting-dependency-caching) + [Error: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image](#troubleshooting-unable-to-pull-image) + [Error: "Build container found dead before completing the build\. build container died because it was out of memory, or the Docker image is not supported\. ErrorCode: 500"](#windows-server-core-version) + [Error: "Cannot connect to the Docker daemon" when running a build](#troubleshooting-cannot-connect-to-docker-daemon) -+ [Error: "CodeBuild is experiencing an issue" when running a build](#troubleshooting-large-env-vars) + [Error: "CodeBuild is not authorized to perform: sts:AssumeRole" when creating or updating a build project](#troubleshooting-assume-role) + [Error: "Error calling GetBucketAcl: Either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl"](#troubleshooting-calling-bucket-error) + [Error: "Failed to upload artifacts: Invalid arn" when running a build](#troubleshooting-output-bucket-different-region) @@ -31,6 +30,10 @@ Use the information in this topic to help you identify, diagnose, and address is + [RequestError timeout error when running CodeBuild in a proxy server](#code-request-timeout-error) + [The bourne shell \(sh\) must exist in build images](#troubleshooting-sh-build-images) + [Warning: "Skipping install of runtimes\. runtime version selection is not supported by this build image" when running a build](#troubleshooting-skipping-all-runtimes-warning) ++ [Error: "Unable to verify JobWorker identity" when opening the CodeBuild console](#troubleshooting-unable-to-verify-jobworker) ++ [Build failed to start](#troubleshooting-build-failed-to-start) ++ [Accessing GitHub metadata in locally cached builds](#troubleshooting-github-metadata) ++ [AccessDenied: The bucket owner for the report group does not match the owner of the S3 bucket\.\.\.](#troubleshooting-bucket-owner) ## Apache Maven builds reference artifacts from the wrong repository @@ -162,7 +165,7 @@ pre_build: **Possible cause:** The branch filter option is deprecated\. It has been replaced by webhook filter groups, which provide more control over the webhook events that trigger a new build in CodeBuild\. -**Recommended solution:** To migrate a branch filter that you created before the introduction of webhook filters, create a webhook filter group with a `HEAD_REF` filter with the regular expression `^refs/heads/branchName$`\. For example, if your branch filter regular expression was `^branchName$`, then the updated regular expression you put in the `HEAD_REF` filter is `^refs/heads/branchName$`\. For more information, see [Filter Bitbucket webhook events \(console\)](sample-bitbucket-pull-request.md#sample-bitbucket-pull-request-filter-webhook-events-console) and [Filter GitHub webhook events \(console\)](sample-github-pull-request.md#sample-github-pull-request-filter-webhook-events-console)\. +**Recommended solution:** To migrate a branch filter that you created before the introduction of webhook filters, create a webhook filter group with a `HEAD_REF` filter with the regular expression `^refs/heads/branchName$`\. For example, if your branch filter regular expression was `^branchName$`, then the updated regular expression you put in the `HEAD_REF` filter is `^refs/heads/branchName$`\. For more information, see [Bitbucket webhook events](bitbucket-webhook.md) and [Filter GitHub webhook events \(console\)](github-webhook.md#github-webhook-events-console)\. ## Cannot view build success or failure @@ -170,27 +173,27 @@ pre_build: **Possible cause:** The option to report your build's status is not enabled\. -**Recommended solutions:** Enable **Report build status** when you create or update a CodeBuild project\. This option tells CodeBuild to report back the status when you trigger a build\. For more information, see [reportBuildStatus](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html#CodeBuild-Type-ProjectSource-reportBuildStatus)\. +**Recommended solutions:** Enable **Report build status** when you create or update a CodeBuild project\. This option tells CodeBuild to report back the status when you trigger a build\. For more information, see [reportBuildStatus](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html#CodeBuild-Type-ProjectSource-reportBuildStatus) in the *AWS CodeBuild API Reference*\. -## Cannot view build success or failure +## Build status not reported to source provider -**Issue:** You cannot see the success or failure of a retried build\. +**Issue:** After allowing build status reporting to a source provider, such as GitHub or Bitbucket, the build status is not updated\. -**Possible cause:** The option to report your build's status is not enabled\. +**Possible cause:** The user associated with the source provider does not have write access to the repo\. -**Recommended solutions:** Enable **Report build status** when you create or update a CodeBuild project\. This option tells CodeBuild to report back the status when you trigger a build\. For more information, see [reportBuildStatus](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html#CodeBuild-Type-ProjectSource-reportBuildStatus) in the *AWS CodeBuild API Reference*\. +**Recommended solutions:** To be able to report the build status to the source provider, the user associated with the source provider must have write access to the repo\. If the user does not have write access, the build status cannot be updated\. For more information, see [Source provider access](access-tokens.md)\. -## Cannot find and select the base image of the Windows Server Core 2016 platform +## Cannot find and select the base image of the Windows Server Core 2019 platform -**Issue:** You cannot find or select the base image of the Windows Server Core 2016 platform\. + **Issue:** You cannot find or select the base image of the Windows Server Core 2019 platform\. -**Possible cause:** You are using an AWS Region that does not support this image\. + **Possible cause:** You are using an AWS Region that does not support this image\. -**Recommended solutions:** Use one of the following AWS Regions where the base image of the Windows Server Core 2016 platform is supported: -+ US East \(N\. Virginia\) -+ US East \(Ohio\) -+ US East \(Ohio\) -+ US West \(N\. California\) + **Recommended solutions:** Use one of the following AWS Regions where the base image of the Windows Server Core 2019 platform is supported: ++ US East \(N\. Virginia\) ++ US East \(Ohio\) ++ US West \(Oregon\) ++ Europe \(Ireland\) ## Earlier commands in buildspec files are not recognized by later commands @@ -215,17 +218,20 @@ pre_build: **Issue:** When you try to run a build that uses a custom build image, the build fails with the error `BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE`\. - **Possible causes:** -+ The build image's overall uncompressed size is larger than the build environment compute type's available disk space\. To check your build image's size, use Docker to run the `docker images REPOSITORY:TAG` command\. For a list of available disk space by compute type, see [Build environment compute types](build-env-ref-compute-types.md)\. -+ AWS CodeBuild does not have permission to pull the build image from your Amazon Elastic Container Registry \(Amazon ECR\)\. -+ The Amazon ECR image you requested is not available in the AWS Region that your AWS account is using\. -+ You are using a private registry in a VPC that does not have public internet access\. CodeBuild cannot pull an image from a private IP address in a VPC\. For more information, see [ Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md)\. +***Possible cause:** The build image's overall uncompressed size is larger than the build environment compute type's available disk space\. To check your build image's size, use Docker to run the `docker images REPOSITORY:TAG` command\. For a list of available disk space by compute type, see [Build environment compute types](build-env-ref-compute-types.md)\.* +**Recommended solution:** Use a larger compute type with more available disk space, or reduce the size of your custom build image\. - **Recommended solutions:** -+ Use a larger compute type with more available disk space, or reduce the size of your custom build image\. -+ Update the permissions in your repository in Amazon ECR so that CodeBuild can pull your custom build image into the build environment\. For more information, see the [Amazon ECR sample](sample-ecr.md)\. -+ Use an Amazon ECR image that is in the same AWS Region as the one your AWS account is using\. -+ If you use a private registry in a VPC, make sure the VPC has public internet access\. +***Possible cause:** AWS CodeBuild does not have permission to pull the build image from your Amazon Elastic Container Registry \(Amazon ECR\)\.* +**Recommended solution:** Update the permissions in your repository in Amazon ECR so that CodeBuild can pull your custom build image into the build environment\. For more information, see the [Amazon ECR sample](sample-ecr.md)\. + +***Possible cause:** The Amazon ECR image you requested is not available in the AWS Region that your AWS account is using\. * +**Recommended solution:** Use an Amazon ECR image that is in the same AWS Region as the one your AWS account is using\. + +***Possible cause:** You are using a private registry in a VPC that does not have public internet access\. CodeBuild cannot pull an image from a private IP address in a VPC\. For more information, see [ Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md)\. * +**Recommended solution:** If you use a private registry in a VPC, make sure the VPC has public internet access\. + +***Possible cause:** If the error message contains "**toomanyrequests**", and the image is obtained from Docker Hub, this error means the Docker Hub pull limit has been reached\. * +**Recommended solution:** Use a Docker Hub private registry, or obtain your image from Amazon ECR\. For more information about using a private registry, see [ Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md)\. For more information about using Amazon ECR, see [Amazon ECR sample for CodeBuild ](sample-ecr.md)\. ## Error: "Build container found dead before completing the build\. build container died because it was out of memory, or the Docker image is not supported\. ErrorCode: 500" @@ -265,14 +271,6 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 1. Choose **Start build** to retry your build\. -## Error: "CodeBuild is experiencing an issue" when running a build - -**Issue:** When you try to run a build project, you receive this error during the build's `PROVISIONING` phase\. - -**Possible cause:** Your build is using environment variables that are too large for AWS CodeBuild\. CodeBuild can raise errors when the length of all environment variables \(all names and values added together\) reach a combined maximum of around 5,500 characters\. - -**Recommended solution:** Use Amazon EC2 Systems Manager Parameter Store to store large environment variables and then retrieve them from your buildspec file\. Amazon EC2 Systems Manager Parameter Store can store an individual environment variable \(name and value added together\) that is a combined 4,096 characters or less\. To store large environment variables, see [Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) and [Systems Manager Parameter Store Console Walkthrough](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console) in the *Amazon EC2 Systems Manager User Guide*\. To retrieve them, see the `parameter-store` mapping in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - ## Error: "CodeBuild is not authorized to perform: sts:AssumeRole" when creating or updating a build project **Issue:** When you try to create or update a build project, you receive the error `Code:InvalidInputException, Message:CodeBuild is not authorized to perform: sts:AssumeRole on arn:aws:iam::account-ID:role/service-role-name`\. @@ -290,7 +288,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo **Issue:** When you run a build, you receive an error about a change in ownership of an S3 bucket and `GetBucketAcl` permissions\. -**Possible cause:** You added the `s3:GetBucketACL` and `s3:GetBucketLocation` permissions to your IAM role\. These permissions secure your project's S3 bucket and ensure that only you can access it\. After you added these permissions, the owner of the S3 bucket changed\. +**Possible cause:** You added the `s3:GetBucketAcl` and `s3:GetBucketLocation` permissions to your IAM role\. These permissions secure your project's S3 bucket and ensure that only you can access it\. After you added these permissions, the owner of the S3 bucket changed\. **Recommended solution:** Verify you are an owner of the S3 bucket, and then add permissions to your IAM role again\. For more information, see [Secure access to S3 buckets](auth-and-access-control-iam-access-control-identity-based.md#secure-s3-buckets)\. @@ -346,6 +344,8 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u 1. Choose **Update environment**\. + + ## Error: "This build image requires selecting at least one runtime version\." **Issue:** When you run a build, the `DOWNLOAD_SOURCE` build phase fails with the error `YAML_FILE_ERROR: This build image requires selecting at least one runtime version`\. @@ -465,7 +465,7 @@ artifacts: 1. In your private subnet routing table, remove the rule you added that routes traffic destined for the internet to your proxy server\. For information, see [Creating a subnet in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet) in the *Amazon VPC User Guide*\. - 1. Create a private Amazon S3 endpoint and CloudWatch Logs endpoint and associate them with the private subnet of your Amazon VPC\. For information, see [VPC endpoint services \(AWS PrivateLink\)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) in the *Amazon VPC User Guide*\. + 1. Create a private Amazon S3 endpoint and CloudWatch Logs endpoint and associate them with the private subnet of your Amazon VPC\. For information, see [VPC endpoint services](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) in the *Amazon VPC User Guide*\. 1. Confirm **Enable Private DNS Name** in your Amazon VPC is selected\. For more information, see [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) in the *Amazon VPC User Guide*\. + If you do not use `ssl-bump` for an explicit proxy server, add a proxy configuration to your buildspec file using a `proxy` element\. For more information, see [ Run CodeBuild in an explicit proxy server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server) and [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. @@ -494,4 +494,44 @@ artifacts: **Possible cause:** Your build does not use version 1\.0 or later of the Amazon Linux 2 \(AL2\) standard image, or version 2\.0 or later of the Ubuntu standard image, and a runtime is specified in a `runtime-versions` section in your buildspec file\. -**Recommended solution:** Be sure your buildspec file does not contain a `runtime-versions` section\. The `runtime-versions` section is only required if you use the Amazon Linux 2 \(AL2\) standard image or later or the Ubuntu standard image version 2\.0 or later\. \ No newline at end of file +**Recommended solution:** Be sure your buildspec file does not contain a `runtime-versions` section\. The `runtime-versions` section is only required if you use the Amazon Linux 2 \(AL2\) standard image or later or the Ubuntu standard image version 2\.0 or later\. + +## Error: "Unable to verify JobWorker identity" when opening the CodeBuild console + +**Issue:** When you open the CodeBuild console, an "Unable to verify JobWorker identity" error message is displayed\. + +**Possible cause:** The IAM role that is used for console access has a tag with `jobId` as the key\. This tag key is reserved for CodeBuild and will cause this error if it is present\. + +**Recommended solution:** Change any custom IAM role tags that have the key `jobId` to have a different key, such as `jobIdentifier`\. + +## Build failed to start + +**Issue:** When starting a build, you receive a **Build failed to start** error message\. + +**Possible cause:** The number of concurrent builds has been reached\. + +**Recommended solutions:** Wait until other builds are complete, or increase the concurrrent build limit for the project, and start the build again\. For more information, see [Project configuration](create-project-console.md#create-project-console-project-config)\. + +## Accessing GitHub metadata in locally cached builds + +**Issue:** In some cases, the \.git directory in a cached build is a text file and not a directory\. + +**Possible causes:** When local source caching is enabled for a build, CodeBuild creates a gitlink for the `.git` directory\. This means that the `.git` directory is actually a text file containing the path to the directory\. + +**Recommended solutions:** In all cases, use the following command to obtain the Git metadata directory\. This command will work no matter the format of `.git`: + +``` +git rev-parse --git-dir +``` + +## AccessDenied: The bucket owner for the report group does not match the owner of the S3 bucket\.\.\. + +**Issue:** When uploading test data to an Amazon S3 bucket, CodeBuild is unable to write the test data to the bucket\. + +**Possible causes:** ++ The account specified for the report group bucket owner does not match the owner of the Amazon S3 bucket\. ++ The service role does not have write access to the bucket\. + +**Recommended solutions:** ++ Change the report group bucket owner to match the owner of the Amazon S3 bucket\. ++ Modify the service role to allow write access to the Amazon S3 bucket\. \ No newline at end of file diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md index ef42efb..257c344 100644 --- a/doc_source/update-report-group-cli.md +++ b/doc_source/update-report-group-cli.md @@ -28,11 +28,11 @@ } ``` -1. Enter the ARN of your report group in the `arn` line \(for example, `"arn":"arn:aws:codebuild:region:123456789012:report-group/report-group-1")`\. +1. Enter the ARN of your report group in the `arn` line \(for example, `"arn":"arn:aws:codebuild:region:123456789012:report-group/report-group-1")`\. -1. Update `UpdateReportGroupInput.json` with the updates you want to apply to your report group\. - + If you want to update your report group to export raw test result files to an S3 bucket, update the `exportConfig` section\. Replace `bucket-name` with your S3 bucket name and `path` with the path in your S3 bucket that you want to export the files to\. If you want to compress the exported files, for `packaging`, specify `ZIP`\. Otherwise, specify `NONE`\. Use `encryptionDisabled` to specify whether to encrypt the exported files\. If you encrypt the exported files, enter your customer master key \(CMK\)\. - + If you want to update your report group so that it does not export raw test result files to an S3 bucket, update the `exportConfig` section with the following JSON: +1. Update `UpdateReportGroupInput.json` with the updates you want to apply to your report group\. + + If you want to update your report group to export raw test result files to an S3 bucket, update the `exportConfig` section\. Replace `bucket-name` with your S3 bucket name and `path` with the path in your S3 bucket that you want to export the files to\. If you want to compress the exported files, for `packaging`, specify `ZIP`\. Otherwise, specify `NONE`\. Use `encryptionDisabled` to specify whether to encrypt the exported files\. If you encrypt the exported files, enter your customer managed key\. + + If you want to update your report group so that it does not export raw test result files to an S3 bucket, update the `exportConfig` section with the following JSON: ``` { @@ -41,7 +41,7 @@ } } ``` - + If you want to update the report group's tags, update the `tags` section\. You can change, add, or remove tags\. If you want to remove all tags, update it with the following JSON: + + If you want to update the report group's tags, update the `tags` section\. You can change, add, or remove tags\. If you want to remove all tags, update it with the following JSON: ``` "tags": [] @@ -50,6 +50,6 @@ 1. Run the following command: ``` - aws codebuild upate-report-group \ + aws codebuild update-report-group \ --cli-input-json file://UpdateReportGroupInput.json ``` \ No newline at end of file diff --git a/doc_source/update-report-group-console.md b/doc_source/update-report-group-console.md index 9fb9985..abe5f6c 100644 --- a/doc_source/update-report-group-console.md +++ b/doc_source/update-report-group-console.md @@ -16,9 +16,9 @@ 1. For **Path prefix**, enter the path in your S3 bucket where you want to upload your test results\. - 1. Select **Compress test result data in a zip file** to compress your raw test result data files\. + 1. Select **Compress test result data in a zip file** to compress your raw test result data files\. - 1. Expand **Additional configuration** to display encryption options\. Choose one of the following: - + **Default AWS managed key** to use a customer master key \(CMK\) for Amazon S3 that is managed by the AWS Key Management Service\. In CodeBuild, the default CMK is for Amazon S3 and uses the format `aws/S3`\. For more information, see [Customer managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) in the *AWS Key Management Service User Guide*\. This is the default encryption option\. - + **Choose a custom key** to use a CMK that you create and configure\. For **AWS KMS encryption key**, enter the ARN of your encryption key\. Its format is ` arn:aws:kms:region-id:aws-account-id:key/key-id`\. For more information, see [Creating KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*\. - + **Disable artifact encryption** to disable encryption\. You might choose this option if you want to share your test results or publish them to a static website\. \(A dynamic website can run code to decrypt test results\.\) \ No newline at end of file + 1. Expand **Additional configuration** to display encryption options\. Choose one of the following: + + **Default AWS managed key** to use a AWS managed key for Amazon S3\. For more information, see [Customer managed CMKs](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) in the *AWS Key Management Service User Guide*\. This is the default encryption option\. + + **Choose a custom key** to use a customer managed key that you create and configure\. For **AWS KMS encryption key**, enter the ARN of your encryption key\. Its format is ` arn:aws:kms:: :key/ `\. For more information, see [Creating KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*\. + + **Disable artifact encryption** to disable encryption\. You might choose this if you want to share your test results, or publish them to a static website\. \(A dynamic website can run code to decrypt test results\.\) \ No newline at end of file diff --git a/doc_source/use-case-based-samples.md b/doc_source/use-case-based-samples.md index c4cd209..799b6b1 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -2,9 +2,6 @@ You can use these use case\-based samples to experiment with AWS CodeBuild: -[ Access token sample ](sample-access-tokens.md) -Shows how to use access tokens in CodeBuild to connect to GitHub and Bitbucket\. - [Amazon ECR sample](sample-ecr.md) Uses a Docker image in an Amazon ECR repository to use Apache Maven to produce a single JAR file\. @@ -14,7 +11,7 @@ Shows how to configure a buildspec file so that a CodeBuild project mounts and b [AWS CodeDeploy sample](sample-codedeploy.md) Uses Apache Maven to produce a single JAR file\. Uses CodeDeploy to deploy the JAR file to an Amazon Linux instance\. You can also use CodePipeline to build and deploy the sample\. -[ AWS CodePipeline integration with multiple input sources and output artifacts sample ](sample-pipeline-multi-input-output.md) +[ AWS CodePipeline integration with batch builds sample AWS CodePipeline integration with multiple input sources and output artifacts sample ](sample-pipeline-multi-input-output.md) Shows how to use AWS CodePipeline to create a build with multiple input sources and multiple output artifacts\. [AWS Config sample](how-to-integrate-config.md) @@ -23,9 +20,6 @@ Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and [AWS Elastic Beanstalk sample](sample-elastic-beanstalk.md) Uses Apache Maven to produce a single WAR file\. Uses Elastic Beanstalk to deploy the WAR file to an Elastic Beanstalk instance\. -[AWS Lambda sample](sample-lambda.md) -Uses CodeBuild, Lambda, AWS CloudFormation, and CodePipeline to build and deploy a serverless application that follows the AWS Serverless Application Model \(AWS SAM\) standard\. - [Bitbucket pull request and webhook filter sample](sample-bitbucket-pull-request.md) Uses CodeBuild with Bitbucket as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 9ac2176..076cecd 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -1,63 +1,148 @@ -# Test and debug locally with the AWS CodeBuild agent +# Run builds locally with the AWS CodeBuild agent - This topic provides information about how to run the AWS CodeBuild agent and subscribe to notifications about new versions of the agent\. +You can use the AWS CodeBuild agent to run CodeBuild builds on a local machine\. There are agents available for x86\_64 and ARM platforms\. -## Test and debug on a local machine with the CodeBuild agent +You can also subscribe to receive notifications when new versions of the agent are published\. - You can use the AWS CodeBuild agent to test and debug builds on a local machine\. +## Prerequisites -**To use the agent** +Before you begin, you need to do the following: ++ Install Git on your local machine\. ++ Install and set up [Docker](https://www.docker.com/) on your local machine\. -1. Download the [codebuild\.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) script\. +## Set up the build image -1. Run the script and specify your container images and output directory: +You only need to set up the build image the first time you run the agent, or when the image has changed\. + +**To set up the build image** + +1. If you want to use a curated Amazon Linux 2 image, you can pull it from the CodeBuild public Amazon ECR repository at [https://gallery\.ecr\.aws/codebuild/amazonlinux2\-x86\_64\-standard](https://gallery.ecr.aws/codebuild/amazonlinux2-x86_64-standard) with the following command: ``` - codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] + $ docker pull public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:3.0 ``` - The CodeBuild agent is available from [https://hub\.docker\.com/r/amazon/aws\-codebuild\-local/](https://hub.docker.com/r/amazon/aws-codebuild-local/)\. Its Secure Hash Algorithm \(SHA\) signature is `78f5c1a205604c39cd8c797fd8447f590428c0908ba1fbdbd3dcf8712af5e325`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + Alternatively, if you want to use another Linux image, perform the following steps: -``` -docker inspect amazon/aws-codebuild-local -``` + 1. Clone the CodeBuild image repo: -## Receive notifications for new CodeBuild agent versions + ``` + $ git clone https://github.com/aws/aws-codebuild-docker-images.git + ``` + + 1. Change to the image directory\. For this example, use the `aws/codebuild/standard:5.0` image: + + ``` + $ cd aws-codebuild-docker-images/ubuntu/standard/5.0 + ``` + + 1. Build the image\. This will take several minutes\. + + ``` + $ docker build -t aws/codebuild/standard:5.0 . + ``` + +1. Download the agent\. + + To download the x86\_64 version of the agent, run the following command: + + ``` + $ docker pull public.ecr.aws/codebuild/local-builds:latest + ``` - You can subscribe to Amazon SNS notifications so you know when new versions of the AWS CodeBuild agent are released\. Follow the steps in this procedure to subscribe to these notifications\. + To download the ARM version of the agent, run the following command: -**To subscribe to the CodeBuild agent notifications** + ``` + $ docker pull public.ecr.aws/codebuild/local-builds:aarch64 + ``` -1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home)\. +1. The CodeBuild agent is available from [https://gallery\.ecr\.aws/codebuild/local\-builds](https://gallery.ecr.aws/codebuild/local-builds)\. -1. In the navigation bar, if it's not already selected, change the AWS Region to **US East \(N\. Virginia\)**\. You must select this AWS Region because the Amazon SNS notifications that you are subscribing to are created in this Region\. + The Secure Hash Algorithm \(SHA\) signature for the x86\_64 version of the agent is: -1. In the navigation pane, choose **Subscriptions**\. + ``` + sha256:fdfff9470520c53dcd522606a3cc2b5df195ae8a5546697b08249b48175f45ed + ``` -1. Choose **Create subscription**\. + The SHA signature for the ARM version of the agent is: -1. In **Create subscription**: + ``` + sha256:5480b70cf48435e276c21789c61280cfada24e17701ede6386e5d82088bc41ca + ``` - For **Topic ARN**, use the following Amazon Resource Name \(ARN\): + You can use the SHA to identify the version of the agent\. To see the agent's SHA signature, run the following command and look for the SHA under `RepoDigests`: ``` - arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates + $ docker inspect public.ecr.aws/codebuild/local-builds:latest + ``` + +## Run the CodeBuild agent + +**To run the CodeBuild agent** + +1. Change to the directory that contains your build project source\. + +1. Download the [codebuild\_build\.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) script: + ``` + $ wget https://raw.githubusercontent.com/aws/aws-codebuild-docker-images/master/local_builds/codebuild_build.sh + $ chmod +x codebuild_build.sh + ``` + +1. Run the `codebuild_build.sh` script and specify your container image and the output directory\. + + To run an x86\_64 build, run the following command: + + ``` + $ ./codebuild_build.sh -i -a + ``` + + To run an ARM build, run the following command: + + ``` + $ ./codebuild_build.sh -i -a -l public.ecr.aws/codebuild/local-builds:aarch64 + ``` + + Replace ** with the name of the container image, such as `aws/codebuild/standard:5.0` or `public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:3.0`\. + + The script launches the build image and runs the build on the project in the current directory\. To specify the location of the build project, add the `-s ` option to the script command\. + +## Receive notifications for new CodeBuild agent versions + +You can subscribe to Amazon SNS notifications so you will be notified when new versions of the AWS CodeBuild agent are released\. + +**To subscribe to CodeBuild agent notifications** + +1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home)\. + +1. In the navigation bar, if it's not already selected, change the AWS Region to **US East \(N\. Virginia\)**\. You must select this AWS Region because the Amazon SNS notifications that you are subscribing to are created in this Region\. + +1. In the navigation pane, choose **Subscriptions**\. + +1. Choose **Create subscription**\. + +1. In **Create subscription**, do the following: + + 1. For **Topic ARN**, use the following Amazon Resource Name \(ARN\): + + ``` + arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates + ``` - For **Protocol**, choose **Email** or **SMS**\. + 1. For **Protocol**, choose **Email** or **SMS**\. - For **Endpoint**, choose where \(email or SMS\) to receive the notifications\. Enter an email or address or phone number, including area code\. + 1. For **Endpoint**, choose where \(email or SMS\) to receive the notifications\. Enter an email or address or phone number, including area code\. - Choose **Create subscription**\. + 1. Choose **Create subscription**\. - If you choose **Email**, you receive an email asking you to confirm your subscription\. Follow the directions in the email to complete your subscription\. + 1. Choose **Email** to receive an email asking you to confirm your subscription\. Follow the directions in the email to complete your subscription\. - If you no longer want to receive these notifications, follow the steps in this procedure to unsubscribe\. + If you no longer want to receive these notifications, use the following procedure to unsubscribe\. **To unsubscribe from CodeBuild agent notifications** -1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home)\. +1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home)\. -1. In the navigation pane, choose **Subscriptions**\. +1. In the navigation pane, choose **Subscriptions**\. -1. Select the subscription and from **Actions**, choose **Delete subscriptions**\. When you are prompted to confirm, choose **Delete**\. \ No newline at end of file +1. Select the subscription and from **Actions**, choose **Delete subscriptions**\. When you are prompted to confirm, choose **Delete**\. \ No newline at end of file diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index da4f2ae..b4ead5c 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -7,7 +7,7 @@ There are two primary use cases for running CodeBuild in a proxy server: + It lets you specify the URLs that instances in the proxy server can access and the URLs to which the proxy server denies access\. You can use CodeBuild with two types of proxy servers\. For both, the proxy server runs in a public subnet and CodeBuild runs in a private subnet\. -+ **Explicit proxy**: If you use an explicit proxy server, you must configure `NO_PROXY`, `HTTP_PROXY`, and `HTTPS_PROXY` environment variables in CodeBuild at the project level\. For more information, see [Change a build project's settings in AWS CodeBuild ](change-project.md) and [Create a build project in AWS CodeBuild](create-project.md)\. ++ **Explicit proxy**: If you use an explicit proxy server, you must configure `NO_PROXY`, `HTTP_PROXY`, and `HTTPS_PROXY` environment variables in CodeBuild at the project level\. For more information, see [Change a build project's settings in AWS CodeBuild](change-project.md) and [Create a build project in AWS CodeBuild](create-project.md)\. + **Transparent proxy**: If you use a transparent proxy server, no special configuration is required\. **Topics** @@ -142,7 +142,7 @@ sudo cat squid.key squid.crt | sudo tee squid.pem ssl_bump splice step3 allowed_https_sites ssl_bump terminate step2 all ``` - + After you save `squid.conf`, execute the following: + + After you save `squid.conf`, run the following command: ``` sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3130 @@ -169,7 +169,7 @@ For more information, see [Explicit proxy server sample `squid.conf` file](#use- ### Create a CodeBuild project - To run AWS CodeBuild with your explicit proxy server, set its `HTTP_PROXY` and `HTTPS_PROXY` environment variables with the private IP address of the EC2 instance you created for your proxy server and port 3128 at the project level\. The private IP address looks like `http://your-ec2-private-ip-address:3128`\. For more information, see [Create a build project in AWS CodeBuild](create-project.md) and [Change a build project's settings in AWS CodeBuild ](change-project.md)\. + To run AWS CodeBuild with your explicit proxy server, set its `HTTP_PROXY` and `HTTPS_PROXY` environment variables with the private IP address of the EC2 instance you created for your proxy server and port 3128 at the project level\. The private IP address looks like `http://your-ec2-private-ip-address:3128`\. For more information, see [Create a build project in AWS CodeBuild](create-project.md) and [Change a build project's settings in AWS CodeBuild](change-project.md)\. Use the following command to view the Squid proxy access log: @@ -183,10 +183,10 @@ sudo tail -f /var/log/squid/access.log ``` acl localnet src 10.0.0.0/16 #Only allow requests from within the VPC - # add all URLS to be whitelisted for download source and commands to be executed in build environment + # add all URLS to be whitelisted for download source and commands to be run in build environment acl allowed_sites dstdomain .github.amrom.workers.dev #Allows to download source from github acl allowed_sites dstdomain .bitbucket.com #Allows to download source from bitbucket - acl allowed_sites dstdomain ppa.launchpad.net #Allows to execute apt-get in build environment + acl allowed_sites dstdomain ppa.launchpad.net #Allows to run apt-get in build environment acl download_src dstdom_regex .*\.amazonaws\.com #Allows to download source from S3 or CodeCommit acl SSL_ports port 443 acl Safe_ports port 80 # http @@ -306,7 +306,9 @@ sudo tail -f /var/log/squid/access.log ## Run a package manager and other tools in a proxy server -**To execute a tool, such as a package manager, in a proxy server** + + +**To run a tool, such as a package manager, in a proxy server** 1. Add the tool to the allow list in your proxy server by adding statements to your `squid.conf` file\. @@ -316,12 +318,12 @@ sudo tail -f /var/log/squid/access.log **To run `apt-get` in a proxy server** -1. Add the following statements to your `squid.conf` file to add `apt-get` to an allow list in your proxy server\. The first three lines allow `apt-get` to execute in the build environment\. +1. Add the following statements to your `squid.conf` file to add `apt-get` to an allow list in your proxy server\. The first three lines allow `apt-get` to run in the build environment\. ``` - acl allowed_sites dstdomain ppa.launchpad.net # Required for apt-get to execute in the build environment - acl apt_get dstdom_regex .*\.launchpad.net # Required for CodeBuild to execute apt-get in the build environment - acl apt_get dstdom_regex .*\.ubuntu.com # Required for CodeBuild to execute apt-get in the build environment + acl allowed_sites dstdomain ppa.launchpad.net # Required for apt-get to run in the build environment + acl apt_get dstdom_regex .*\.launchpad.net # Required for CodeBuild to run apt-get in the build environment + acl apt_get dstdom_regex .*\.ubuntu.com # Required for CodeBuild to run apt-get in the build environment http_access allow localnet allowed_sites http_access allow localnet apt_get ``` @@ -337,7 +339,7 @@ sudo tail -f /var/log/squid/access.log 1. Add the following to your `squid.conf` file to add `curl` to an allow list in your build environment\. ``` - acl allowed_sites dstdomain ppa.launchpad.net # Required to execute apt-get in the build environment + acl allowed_sites dstdomain ppa.launchpad.net # Required to run apt-get in the build environment acl allowed_sites dstdomain google.com # Required for access to a webiste. This example uses www.google.com. http_access allow localnet allowed_sites http_access allow localnet apt_get @@ -354,7 +356,7 @@ sudo tail -f /var/log/squid/access.log 1. Add the following to your `squid.conf` file to add `maven` to an allow list in your build environment\. ``` - acl allowed_sites dstdomain ppa.launchpad.net # Required to execute apt-get in the build environment + acl allowed_sites dstdomain ppa.launchpad.net # Required to run apt-get in the build environment acl maven dstdom_regex .*\.maven.org # Allows access to the maven repository in the build environment http_access allow localnet allowed_sites http_access allow localnet maven diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index 3411440..7fefd42 100644 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ b/doc_source/use-vpc-endpoints-with-codebuild.md @@ -1,6 +1,6 @@ # Use VPC endpoints - You can improve the security of your builds by configuring AWS CodeBuild to use an interface VPC endpoint\. Interface endpoints are powered by PrivateLink, a technology that you can use to privately access Amazon EC2 and CodeBuild by using private IP addresses\. PrivateLink restricts all network traffic between your managed instances, CodeBuild, and Amazon EC2 to the Amazon network\. \(Managed instances don't have access to the internet\.\) Also, you don't need an internet gateway, NAT device, or virtual private gateway\. You are not required to configure PrivateLink, but it's recommended\. For more information about PrivateLink and VPC endpoints, see [Accessing AWS services through PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/how-it-works.html#what-is-privatelink) in the *Amazon VPC User Guide*\. +You can improve the security of your builds by configuring AWS CodeBuild to use an interface VPC endpoint\. Interface endpoints are powered by PrivateLink, a technology that you can use to privately access Amazon EC2 and CodeBuild by using private IP addresses\. PrivateLink restricts all network traffic between your managed instances, CodeBuild, and Amazon EC2 to the Amazon network\. \(Managed instances don't have access to the internet\.\) Also, you don't need an internet gateway, NAT device, or virtual private gateway\. You are not required to configure PrivateLink, but it's recommended\. For more information about PrivateLink and VPC endpoints, see [Accessing services through AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/userguide/how-it-works.html#what-is-privatelink) in the *Amazon VPC User Guide*\. ## Before you create VPC endpoints diff --git a/doc_source/view-build-details.md b/doc_source/view-build-details.md index 6e9cc6b..5305ff6 100644 --- a/doc_source/view-build-details.md +++ b/doc_source/view-build-details.md @@ -49,7 +49,11 @@ For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS S Builds in AWS CodeBuild proceed in phases: + + ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/build-phases.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + **Important** The `UPLOAD_ARTIFACTS` phase is always attempted, even if the `BUILD` phase fails\. \ No newline at end of file diff --git a/doc_source/view-build-list.md b/doc_source/view-build-list.md index 8006ed0..5d862f1 100644 --- a/doc_source/view-build-list.md +++ b/doc_source/view-build-list.md @@ -5,6 +5,7 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of bu **Topics** + [View a list of build IDs \(console\)](#view-build-list-console) + [View a list of build IDs \(AWS CLI\)](#view-build-list-cli) ++ [View a list of batch build IDs \(AWS CLI\)](#view-batch-build-list-cli) + [View a list of build IDs \(AWS SDKs\)](#view-build-list-sdks) ## View a list of build IDs \(console\) @@ -58,7 +59,59 @@ For more information about using the AWS CLI with CodeBuild, see the [Command li ``` { - "ids": [ + "ids": [ + "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE", + "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE", + ... The full list of build IDs has been omitted for brevity ... + "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE" + ] + } + ``` + +## View a list of batch build IDs \(AWS CLI\) + +For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md)\. ++ Run the list\-build\-batches command: + + ``` + aws codebuild list-build-batches --sort-order sort-order --next-token next-token + ``` + + In the preceding command, replace the following placeholders: + + *sort\-order*: Optional string used to indicate how to list the batch build IDs\. Valid values include `ASCENDING` and `DESCENDING`\. + + *next\-token*: Optional string\. During a previous run, if there were more than 100 items in the list, only the first 100 items are returned, along with a unique string called *next token*\. To get the next batch of items in the list, run this command again, adding the next token to the call\. To get all of the items in the list, keep running this command with each subsequent next token, until no more next tokens are returned\. + + For example, if you run this command: + + ``` + aws codebuild list-build-batches --sort-order ASCENDING + ``` + + A result similar to the following might appear in the output: + + ``` + { + "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", + "ids": [ + "codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE" + "codebuild-demo-project:84a7f3d1-d40e-4956-b4cf-7a9d4EXAMPLE" + ... The full list of build IDs has been omitted for brevity ... + "codebuild-demo-project:931d0b72-bf6f-4040-a472-5c707EXAMPLE" + ] + } + ``` + + If you run this command again: + + ``` + aws codebuild list-build-batches --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA== + ``` + + A result similar to the following might appear in the output: + + ``` + { + "ids": [ "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE", "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE", ... The full list of build IDs has been omitted for brevity ... diff --git a/doc_source/view-builds-for-project.md b/doc_source/view-builds-for-project.md index 759b585..13502f2 100644 --- a/doc_source/view-builds-for-project.md +++ b/doc_source/view-builds-for-project.md @@ -5,6 +5,7 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of bu **Topics** + [View a list of build IDs for a build project \(console\)](#view-builds-for-project-console) + [View a list of build IDs for a build project \(AWS CLI\)](#view-builds-for-project-cli) ++ [View a list of batch build IDs for a build project \(AWS CLI\)](#view-batch-builds-for-project-cli) + [View a list of build IDs for a build project \(AWS SDKs\)](#view-builds-for-project-sdks) ## View a list of build IDs for a build project \(console\) @@ -70,6 +71,60 @@ You might see a result like the following in the output: } ``` +## View a list of batch build IDs for a build project \(AWS CLI\) + +For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. + +Run the list\-build\-batches\-for\-project command, as follows: + +``` +aws codebuild list-build-batches-for-project --project-name project-name --sort-order sort-order --next-token next-token +``` + +In the preceding command, replace the following placeholders: ++ *project\-name*: Required string used to indicate the name of the build project to list builds IDs for\. To get a list of build projects, see [View a list of build project names \(AWS CLI\)](view-project-list.md#view-project-list-cli)\. ++ *sort\-order*: Optional string used to indicate how to list the build IDs\. Valid values include `ASCENDING` and `DESCENDING`\. ++ *next\-token*: Optional string\. During a previous run, if there were more than 100 items in the list, only the first 100 items are returned, along with a unique string called *next token*\. To get the next batch of items in the list, run this command again, adding the next token to the call\. To get all of the items in the list, keep running this command with each subsequent next token that is returned, until no more next tokens are returned\. + +For example, if you run this command similar to this: + +``` +aws codebuild list-build-batches-for-project --project-name codebuild-demo-project --sort-order ASCENDING +``` + +A result like the following might appear in the output: + +``` +{ + "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", + "ids": [ + "codebuild-demo-project:9b175d16-66fd-4e71-93a0-50a08EXAMPLE" + "codebuild-demo-project:a9d1bd09-18a2-456b-8a36-7d65aEXAMPLE" + ... The full list of build IDs has been omitted for brevity ... + "codebuild-demo-project:fe70d102-c04f-421a-9cfa-2dc15EXAMPLE" + ] +} +``` + +If you run this command again: + +``` +aws codebuild list-build-batches-for-project --project-name codebuild-demo-project --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA== +``` + +You might see a result like the following in the output: + +``` +{ + "ids": [ + "codebuild-demo-project:98253670-7a8a-4546-b908-dc890EXAMPLE" + "codebuild-demo-project:ad5405b2-1ab3-44df-ae2d-fba84EXAMPLE" + ... The full list of build IDs has been omitted for brevity ... + "codebuild-demo-project:f721a282-380f-4b08-850a-e0ac1EXAMPLE" + ] +} +``` + ## View a list of build IDs for a build project \(AWS SDKs\) For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. \ No newline at end of file diff --git a/doc_source/view-project-details.md b/doc_source/view-project-details.md index 4738c9f..f25e255 100644 --- a/doc_source/view-project-details.md +++ b/doc_source/view-project-details.md @@ -21,6 +21,8 @@ By default, only the 10 most recent build projects are displayed\. To view more ## View a build project's details \(AWS CLI\) + + Run the batch\-get\-projects command: ``` @@ -60,6 +62,49 @@ A result similar to the following might appear in the output\. Ellipses \(`...`\ In the preceding output, the `projectsNotFound` array lists any build project names that were specified, but not found\. The `projects` array lists details for each build project where information was found\. Build project details have been omitted from the preceding output for brevity\. For more information, see the output of [Create a build project \(AWS CLI\)](create-project-cli.md)\. +The batch\-get\-projects command does not support filtering for certain property values, but you can write a script that enumerates the properties for a project\. For example, the following Linux shell script enumerates the projects in the current region for the current account, and prints the image used by each project\. + +``` +#!/usr/bin/sh + +# This script enumerates all of the projects for the current account +# in the current region and prints out the image that each project is using. + +imageName="" + +function getImageName(){ + local environmentValues=(${1//$'\t'/ }) + imageName=${environmentValues[1]} +} + +function processProjectInfo() { + local projectInfo=$1 + + while IFS=$'\t' read -r section value; do + if [[ "$section" == *"ENVIRONMENT"* ]]; then + getImageName "$value" + fi + done <<< "$projectInfo" +} + +# Get the list of projects. +projectList=$(aws codebuild list-projects --output=text) + +for projectName in $projectList +do + if [[ "$projectName" != *"PROJECTS"* ]]; then + echo "===============================================" + + # Get the detailed information for the project. + projectInfo=$(aws codebuild batch-get-projects --output=text --names "$projectName") + + processProjectInfo "$projectInfo" + + printf 'Project "%s" has image "%s"\n' "$projectName" "$imageName" + fi +done +``` + For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. ## View a build project's details \(AWS SDKs\) diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index 7f49830..09024d3 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -5,6 +5,9 @@ Typically, AWS CodeBuild cannot access resources in a VPC\. To enable access, yo **Note** VPC connectivity from CodeBuild is not supported in Windows\. +**Note** +If you configure a VPC, [local caching](build-caching.md#caching-local) is not supported\. Starting 02/28/22, your VPC build will take longer since a new Amazon EC2 instance will be used for each build\. + **Topics** + [Use cases](#use-cases) + [Allowing Amazon VPC access in your CodeBuild projects](#enabling-vpc-access-in-projects) @@ -33,8 +36,12 @@ Include these settings in your VPC configuration: + For **Subnets**, choose a private subnet with NAT translation that includes or has routes to the resources used by CodeBuild\. + For **Security Groups**, choose the security groups that CodeBuild uses to allow access to resources in the VPCs\. + + To use the console to create a build project, see [Create a build project \(console\)](create-project-console.md)\. When you create or change your CodeBuild project, in **VPC**, choose your VPC ID, subnets, and security groups\. + + To use the AWS CLI to create a build project, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. If you are using the AWS CLI with CodeBuild, the service role used by CodeBuild to interact with services on behalf of the IAM user must have a policy attached\. For information, see [Allow CodeBuild access to AWS services required to create a VPC network interface](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-vpc-network-interface)\. The *vpcConfig* object should include your *vpcId*, *securityGroupIds*, and *subnets*\. @@ -61,9 +68,9 @@ Replace `us-east-1` with your Region\. ## Best practices for VPCs Use this checklist when you set up a VPC to work with CodeBuild\. -+ Set up your VPC with public and private subnets and a NAT gateway\. For more information, see [VPC with public and private subnets \(NAT\)](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html) in the *Amazon VPC User Guide*\. ++ Set up your VPC with public and private subnets, and a NAT gateway\. The NAT gateway must reside in a public subnet\. For more information, see [VPC with public and private subnets \(NAT\)](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html) in the *Amazon VPC User Guide*\. **Important** -You need a NAT gateway or NAT instance to use CodeBuild with your VPC so that CodeBuild can reach public endpoints \(for example, to execute CLI commands when running builds\)\. You cannot use the internet gateway instead of a NAT gateway or a NAT instance because CodeBuild does not support assigning Elastic IP addresses to the network interfaces that it creates, and auto\-assigning a public IP address is not supported by Amazon EC2 for any network interfaces created outside of Amazon EC2 instance launches\. +You need a NAT gateway or NAT instance to use CodeBuild with your VPC so that CodeBuild can reach public endpoints \(for example, to run CLI commands when running builds\)\. You cannot use the internet gateway instead of a NAT gateway or a NAT instance because CodeBuild does not support assigning Elastic IP addresses to the network interfaces that it creates, and auto\-assigning a public IP address is not supported by Amazon EC2 for any network interfaces created outside of Amazon EC2 instance launches\. + Include multiple Availability Zones with your VPC\. + Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. CodeBuild does not have specific requirements for outbound traffic, but you must allow access to any Internet resources required for your build, such as GitHub or Amazon S3\. diff --git a/doc_source/webhooks.md b/doc_source/webhooks.md new file mode 100644 index 0000000..ce0752b --- /dev/null +++ b/doc_source/webhooks.md @@ -0,0 +1,24 @@ +# Using webhooks with AWS CodeBuild + +AWS CodeBuild supports webhook integration with GitHub, GitHub Enterprise Server, and Bitbucket\. + +**Topics** ++ [Best practices for using webhooks with AWS CodeBuild](#webhook-best-practices) ++ [Bitbucket webhook events](bitbucket-webhook.md) ++ [GitHub webhook events](github-webhook.md) + +## Best practices for using webhooks with AWS CodeBuild + +For projects that use public repositories to setup webhooks, we recommend the following options: + +Setup `ACTOR_ACCOUNT_ID` filters +Add `ACTOR_ACCOUNT_ID` filters to your project’s webhook filter groups to specify which users can trigger a build\. Every webhook event delivered to CodeBuild comes with sender information that specifies the actor's identifier\. CodeBuild will filter the webhooks based on the regular expression pattern provided in the filters\. You can specify the specific users that are allowed to trigger builds with this filter\. For more information, see [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. + +Setup `FILE_PATH` filters +Add `FILE_PATH` filters to your project’s webhook filter groups to include or exclude the files that can trigger a build when changed\. For example, you can deny build requests for changes to the `buildspec.yml` file using a regular expression pattern such as `^buildspec.yml$`, along with the `excludeMatchedPattern` property\. For more information, see [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. + +Scope down the permissions for your build IAM role +Builds triggered by a webhook use the IAM service role specified in the project\. We recommend setting the permissions in the service role to the minimum set of permissions required to run the build\. For example, in a test and deploy scenario, create one project for testing and another project for deployment\. The testing project accepts webhook builds from the repository, but provides no write permissions to your resources\. The deployment project provides write permissions to your resources, and the webhook filter is configured to only allow trusted users to trigger builds\. + +Use an inline or an Amazon S3 stored buildspec +If you define your buildspec inline within the project itself, or store the buildspec file in an Amazon S3 bucket, the buildspec file is only visible to the project owner\. This prevents pull requests from making code changes to the buildspec file and triggering unwanted builds\. For more information, see [ProjectSource\.buildspec](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ProjectSource.html#CodeBuild-Type-ProjectSource-buildspec) in the *CodeBuild API Reference*\. \ No newline at end of file diff --git a/doc_source/welcome.md b/doc_source/welcome.md index 552b8a1..d9b2e98 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -1,33 +1,37 @@ # What is AWS CodeBuild? +## + AWS CodeBuild is a fully managed build service in the cloud\. CodeBuild compiles your source code, runs unit tests, and produces artifacts that are ready to deploy\. CodeBuild eliminates the need to provision, manage, and scale your own build servers\. It provides prepackaged build environments for popular programming languages and build tools such as Apache Maven, Gradle, and more\. You can also customize build environments in CodeBuild to use your own build tools\. CodeBuild scales automatically to meet peak build requests\. CodeBuild provides these benefits: -+ **Fully managed** – CodeBuild eliminates the need to set up, patch, update, and manage your own build servers\. -+ **On demand** – CodeBuild scales on demand to meet your build needs\. You pay only for the number of build minutes you consume\. -+ **Out of the box** – CodeBuild provides preconfigured build environments for the most popular programming languages\. All you need to do is point to your build script to start your first build\. - -For more information, see [AWS CodeBuild](https://aws.amazon.com/codebuild/)\. ++ **Fully managed** – CodeBuild eliminates the need to set up, patch, update, and manage your own build servers\. ++ **On demand** – CodeBuild scales on demand to meet your build needs\. You pay only for the number of build minutes you consume\. ++ **Out of the box** – CodeBuild provides preconfigured build environments for the most popular programming languages\. All you need to do is point to your build script to start your first build\. -**Topics** -+ [How to run CodeBuild](#welcome-quick-look) -+ [Pricing for CodeBuild](#welcome-pricing) -+ [How do I get started with CodeBuild?](#welcome-getting-started) -+ [AWS CodeBuild concepts](concepts.md) +For more information, see [AWS CodeBuild](https://aws.amazon.com/codebuild/)\. ## How to run CodeBuild You can use the AWS CodeBuild or AWS CodePipeline console to run CodeBuild\. You can also automate the running of CodeBuild by using the AWS Command Line Interface \(AWS CLI\) or the AWS SDKs\. + + ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/overview.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + + To run CodeBuild by using the CodeBuild console, AWS CLI, or AWS SDKs, see [Run AWS CodeBuild directly](how-to-run.md)\. As the following diagram shows, you can add CodeBuild as a build or test action to the build or test stage of a pipeline in AWS CodePipeline\. AWS CodePipeline is a continuous delivery service that you can use to model, visualize, and automate the steps required to release your code\. This includes building your code\. A *pipeline* is a workflow construct that describes how code changes go through a release process\. + + ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pipeline.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) -To use CodePipeline to create a pipeline and then add a CodeBuild build or test action, see [Use AWS CodePipeline with AWS CodeBuild](how-to-create-pipeline.md)\. For more information about CodePipeline, see the [AWS CodePipeline User Guide](https://docs.aws.amazon.com/codepipeline/latest/userguide/)\. + + +To use CodePipeline to create a pipeline and then add a CodeBuild build or test action, see [Use CodePipeline with CodeBuild](how-to-create-pipeline.md)\. For more information about CodePipeline, see the [AWS CodePipeline User Guide](https://docs.aws.amazon.com/codepipeline/latest/userguide/)\. The CodeBuild console also provides a way to quickly search for your resources, such as repositories, build projects, deployment applications, and pipelines\. Choose **Go to resource** or press the `/` key, and then enter the name of the resource\. Any matches appear in the list\. Searches are case insensitive\. You only see resources that you have permissions to view\. For more information, see [Viewing resources in the console](console-resources.md)\. diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 48df157..21a1fb5 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -12,7 +12,10 @@ You can perform these tasks when working with build projects: + [Build caching in AWS CodeBuild](build-caching.md) + [Create AWS CodeBuild triggers](trigger-create.md) + [Edit AWS CodeBuild triggers](triggers-edit.md) ++ [Using webhooks with AWS CodeBuild](webhooks.md) + [Change a build project's settings in AWS CodeBuild](change-project.md) + [Delete a build project in AWS CodeBuild](delete-project.md) + [Working with shared projects](project-sharing.md) -+ [Tagging projects in AWS CodeBuild](how-to-tag-project.md) \ No newline at end of file ++ [Tagging projects in AWS CodeBuild](how-to-tag-project.md) ++ [Batch builds in AWS CodeBuild](batch-build.md) ++ [Public build projects in AWS CodeBuild](public-builds.md) \ No newline at end of file