From a80282e5f8b7f4a9a9ef33a0dd12cffbe5eac7b2 Mon Sep 17 00:00:00 2001 From: Zhen Li Date: Wed, 4 Sep 2019 13:20:13 -0700 Subject: [PATCH 001/156] Update using proxy server guide --- doc_source/troubleshooting.md | 15 ++++++++++++++- doc_source/use-proxy-server.md | 20 +++++++++++++++++--- 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index af475c8..3ade0e0 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -437,11 +437,12 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u ## RequestError timeout error when running CodeBuild in a proxy server - **Issue:** You receive an error similar to `RequestError: send request failed caused by: Post https://logs..amazonaws.com/: dial tcp 52.46.158.105:443: i/o timeout` from CloudWatch Logs\. + **Issue:** You receive an error similar to `RequestError: send request failed caused by: Post https://logs..amazonaws.com/: dial tcp 52.46.158.105:443: i/o timeout` from CloudWatch Logs or `Error uploading artifacts: RequestError: send request failed caused by: Put https://.s3..amazonaws.com/*: dial tcp 52.219.96.208:443: connect: connection refused` from Amazon S3\. **Possible causes:** + `ssl-bump` is not configured properly\. + Your organization's security policy does not allow you to use `ssl_bump`\. ++ Proxy configuration is not added to the buildspec file\. **Recommended solutions:** + Make sure `ssl-bump` is configured properly\. If you use Squid for your proxy server, see [ Configure Squid as an Explicit Proxy Server](use-proxy-server.md#use-proxy-server-explicit-squid-configure)\. @@ -452,6 +453,18 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u 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)\. 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)\. ++ You need to add proxy configuration to your buildspec file if you do not use `ssl-bump`: + + ``` + version: 0.2 + proxy: + upload-artifacts: yes + logs: yes + phases: + build: + commands: + - command + ``` ## Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index 16a4a9d..29a1872 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -124,8 +124,9 @@ sudo cat squid.key squid.crt | sudo tee squid.pem http_access allow localnet allowed_sites http_access allow localnet download_src ``` -+ Before the `http_access deny all` statement, insert the following statements\. They allow CodeBuild to access CloudWatch and Amazon S3\. Access to CloudWatch is required so that CodeBuild can create CloudWatch logs\. Access to Amazon S3 is required for uploading artifacts and Amazon S3 caching\. - + ++ For allowing CodeBuild to upload logs and artifacts. There are two methods: + +1. Before the `http_access deny all` statement, insert the following statements\. They allow CodeBuild to access CloudWatch and Amazon S3\. Access to CloudWatch is required so that CodeBuild can create CloudWatch logs\. Access to Amazon S3 is required for uploading artifacts and Amazon S3 caching\. ``` https_port 3130 cert=/etc/squid/ssl/squid.pem ssl-bump intercept @@ -140,13 +141,26 @@ 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`, execute the following: ``` sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3130 sudo service squid restart ``` +1. Add proxy configuration to your buildspec file\. + + ``` + version: 0.2 + proxy: + upload-artifacts: yes + logs: yes + phases: + build: + commands: + - command + ``` + **Note** If you receive a RequestError timeout error, see [ RequestError timeout error when running CodeBuild in a proxy server](troubleshooting.md#code-request-timeout-error)\. From c6330e23655292aa4146dfc0d7c9178cc5143dca Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Fri, 6 Sep 2019 18:12:11 +0000 Subject: [PATCH 002/156] Periodic update - September 6, 2019 --- doc_source/build-env-ref-available.md | 2 +- doc_source/build-env-ref-env-vars.md | 1 + doc_source/build-spec-ref.md | 13 +++- doc_source/create-project.md | 4 +- doc_source/getting-started.md | 10 +-- doc_source/history.md | 2 +- doc_source/how-to-create-pipeline.md | 6 +- doc_source/run-build.md | 2 +- doc_source/sample-bitbucket-pull-request.md | 2 +- doc_source/sample-build-badges.md | 2 +- doc_source/sample-build-notifications.md | 2 +- .../sample-buildspec-artifact-naming.md | 2 +- doc_source/sample-codedeploy.md | 2 +- .../sample-disable-artifact-encryption.md | 2 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-efs.md | 6 +- doc_source/sample-elastic-beanstalk.md | 60 +++++++-------- doc_source/sample-github-enterprise.md | 2 +- doc_source/sample-github-pull-request.md | 2 +- doc_source/sample-lambda.md | 2 +- doc_source/sample-runtime-versions.md | 20 ++--- doc_source/sample-source-version.md | 4 +- doc_source/troubleshooting.md | 15 ++-- doc_source/use-proxy-server.md | 73 ++++++++++--------- doc_source/vpc-support.md | 2 +- 27 files changed, 130 insertions(+), 118 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 96fb3d7..b4498d7 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -36,7 +36,7 @@ AWS CodeBuild manages the following Docker images that are available in the Code | --- | --- | --- | | dotnet | 2\.1 | 2\.2 | | golang | 1\.11 | 1\.12 | -| nodejs | 9\.16 | 10\.16 | +| nodejs | 9\.11 | 10\.16 | | java | openjdk8 | openjdk11 | | php | 7\.2 | 7\.3 | | python | 3\.6 | 3\.7 | diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 083ac29..4a154c1 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -28,6 +28,7 @@ If you use a secondary source, the environment variable for its directory path i + `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, 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`\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index b7ee331..9e91e49 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -45,6 +45,10 @@ env: key: "value" key: "value" git-credential-helper: yes + +proxy: + upload-artifacts: yes + logs: yes phases: install: @@ -134,6 +138,9 @@ The value in the start build operation call takes highest precedence\. You can a 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. The value in the build spec declaration takes lowest precedence\. + `git-credential-helper`: Optional mapping\. Represents whether CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used; otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. ++ `proxy`: Optional sequence\. Represents settings if you run your build in an explicit proxy server\. For more information, see [](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. + + `upload-artifacts`: Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default setting is `no`\. + + `logs`: Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch Logs\. The default setting is `no`\. + `phases`: Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. **Note** In build spec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use build spec version 0\.1, we recommend the approaches in [Shells and Commands in Build Environments](build-env-ref-cmd.md)\. @@ -178,7 +185,7 @@ Commands in some build phases might not be run if commands in earlier build phas When you specify build output artifact locations, CodeBuild can locate the original build location in the build environment\. You do not have to prepend your build artifact output locations with the path to the original build location or specify `./` or similar\. If you want to know the path to this location, you can run a command such as `echo $CODEBUILD_SRC_DIR` during a build\. The location for each build environment might be slightly different\. + `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 **Use the name specified in the buildspec file** when you create or update a project\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. + + 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.md#create-project-console)\. You can specify a name in the build spec file that is calculated at build time\. The name specified in a build spec 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/)\. @@ -207,7 +214,7 @@ Commands in some build phases might not be run if commands in earlier build phas artifacts: files: - '**/*' - name: myname-$(AWS_REGION) + 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\. @@ -221,7 +228,7 @@ Commands in some build phases might not be run if commands in earlier build phas artifacts: files: - '**/*' - name: $(AWS_REGION)-$(date +%Y-%m-%d) + name: $AWS_REGION-$(date +%Y-%m-%d) ``` + `discard-paths`: Optional mapping\. Represents whether paths to files in the build output artifact are discarded\. `yes` if paths are discarded; otherwise, `no` or not specified \(the default\)\. For example, if a path to a file in the build output artifact would be `com/mycompany/app/HelloWorld.java`, then specifying `yes` would shorten this path to simply `HelloWorld.java`\. + `base-directory`: Optional mapping\. Represents one or more top\-level directories, relative to the original build location, that CodeBuild uses to determine which files and subdirectories to include in the build output artifact\. Valid values include: diff --git a/doc_source/create-project.md b/doc_source/create-project.md index c3ca173..4cc6267 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -17,7 +17,7 @@ Answer the questions in [Plan a Build](planning.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. If a CodeBuild information page is displayed, choose **Create project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**\. @@ -122,7 +122,7 @@ The value in the build spec declaration takes lowest precedence\. + 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 Amazon 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 **Use the name specified in the buildspec file** 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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 [Build Spec 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + If you do not want your build artifacts encrypted, select **Remove artifacts encryption**\. diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index 7f5ac82..09753a5 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -163,7 +163,7 @@ version: 0.2 phases: install: runtime-versions: - java: openjdk11 + java: corretto11 pre_build: commands: - echo Nothing to do in the pre_build phase... @@ -255,7 +255,7 @@ You can work with CodeBuild in several ways: through the CodeBuild console, AWS 1. In the AWS region selector, choose a region that supports CodeBuild\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the "Regions and Endpoints" topic in the *Amazon Web Services General Reference*\. -1. If a CodeBuild information page is displayed, choose **Create project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**, for **Project name**, enter a name for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across each AWS account\. If you use a different name, be sure to use it throughout this walkthrough\. **Note** @@ -272,11 +272,11 @@ An IAM user in your AWS account with the AWS managed policies named **AWSCodeBui 1. In **Environment**, for **Environment image**, leave **Managed image** selected\. -1. For **Operating system**, choose **Ubuntu**\. +1. For **Operating system**, choose **Amazon Linux 2**\. 1. For **Runtime\(s\)**, choose **Standard**\. -1. For **Image**, choose **aws/codebuild/standard:2\.0**\. +1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. 1. In **Service role**, leave **New service role** selected, and leave **Role name** unchanged\. @@ -408,7 +408,7 @@ You can use the [CodeBuild console](#getting-started-run-build-console) or [AWS 1. In the list of build projects, choose **codebuild\-demo\-project**, and then choose **Start build**\. -1. On the **Start new build** page, choose **Start build**\. +1. On the **Start build** page, choose **Start build**\. 1. Skip ahead to [Step 7: View Summarized Build Information](#getting-started-monitor-build)\. diff --git a/doc_source/history.md b/doc_source/history.md index f891f91..6a03412 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **August 16, 2019 ++ **Latest documentation update: **September 6, 2019 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 0ceeaa3..7b05912 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -133,7 +133,7 @@ If you enable webhooks for an AWS CodeBuild project, and the project is used as 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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\. @@ -423,7 +423,7 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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\. @@ -562,7 +562,7 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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\. diff --git a/doc_source/run-build.md b/doc_source/run-build.md index a8f81ce..96c1b68 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -51,7 +51,7 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll 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 build spec file to override any name specified in the console, select **Use the name specified in the buildspec file**\. The name in a build spec 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + If you want a name specified in the build spec file to override any name specified in the console, select **Enable semantic versioning**\. The name in a build spec 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 [Build Spec 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 Amazon S3 bucket for your output artifacts\. diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index ca65fbb..2194a03 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -21,7 +21,7 @@ This sample shows you how to create a pull request using a Bitbucket repository\ 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**, for **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\. diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index de30dc4..046845f 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -6,7 +6,7 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**, for **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\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 8ce4ee8..57fff56 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-buildspec-artifact-naming.md b/doc_source/sample-buildspec-artifact-naming.md index b1f037b..701cc41 100644 --- a/doc_source/sample-buildspec-artifact-naming.md +++ b/doc_source/sample-buildspec-artifact-naming.md @@ -7,7 +7,7 @@ If you want to override the artifact name you entered in the console with a name in the buildspec file, do the following: 1. Set your build project to override the artifact name with a name in the buildspec file\. - + If you use the console to create your build project, select **Use the name specified in the buildspec file**\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. + + If you use the console to create your build project, select **Enable semantic versioning**\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. + If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON\-formatted file passed to `create-project`\. For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. + If you use the AWS CodeBuild API, set the `overrideArtifactName` flag on the `ProjectArtifacts` object when a project is created or updated or a build is started\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 9e47a4a..d1cea37 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index 360429f..a190c4d 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -6,7 +6,7 @@ 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**, for **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\. diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index bbd111f..65b336e 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w11aac11c41c32c17) ++ [Related Resources](#w13aac11c41c32c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 7e4b1fc..b4747fa 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w11aac11c41c17c23) ++ [Related Resources](#w13aac11c41c17c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index b06c4d1..d1cbcc4 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 1a46cd4..544cc6f 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -66,11 +66,11 @@ 1. From **Environment image**, choose **Managed image**\. -1. From **Operating system**, choose **Ubuntu**\. +1. From **Operating system**, choose **Amazon Linux 2**\. -1. From **Runtime**, choose **Standard**\. +1. From **Runtime\(s\)**, choose **Standard**\. -1. From **Runtime version** choose **aws/codebuild/standard:2\.0** \. +1. From **Runtime version** choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. 1. Select **Privileged**\. diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index eb72b8d..0c6ce12 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -32,6 +32,14 @@ In this section, you use Maven to produce the source code\. Later on, you use AW `-- 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\. + + ``` + container_commands: + fix_path: + command: "unzip my-web-app.war 2>&1 > /var/log/my_last_deploy.log" + ``` + After you run Maven, continue with one of the following scenarios: + [Scenario A: Run AWS CodeBuild Manually and Deploy to Elastic Beanstalk Manually](#sample-elastic-beanstalk-manual) + [Scenario B: Use CodePipeline to Run AWS CodeBuild and Deploy to Elastic Beanstalk](#sample-elastic-beanstalk-codepipeline) @@ -45,14 +53,6 @@ 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 build spec file to the code in [Create the Source Code](#sample-elastic-beanstalk-prepare-source)\. You then upload the source code to an Amazon S3 input bucket or an AWS CodeCommit or GitHub repository \. -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\. - - ``` - container_commands: - fix_path: - command: "unzip my-web-app.war 2>&1 > /var/log/my_last_deploy.log" - ``` - 1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. ``` @@ -61,7 +61,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f phases: install: runtime-versions: - java: openjdk11 + java: corretto11 post_build: commands: - mvn package @@ -90,10 +90,10 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f `-- pom.xml ``` -1. Upload the contents of the `my-web-app` directory to an Amazon S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. +1. Upload the contents of the `my-web-app` directory to an Amazon 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 Amazon 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`\. + If you are using an Amazon 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)\. ### Step A2: Create the Build Project and Run the Build @@ -108,10 +108,12 @@ In this step, you use the AWS CodeBuild console to create a build project and th 1. Create a build project and then run a build\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. - + For **Operating system**, choose **Ubuntu**\. + + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. + For **Artifacts**: + + For **Type**, choose **Amazon S3**\. + + For **Bucket name**, enter the name of an Amazon S3 bucket\. + For **Name**, enter a build output file name that's easy for you to remember\. Include the `.zip` extension\. + For **Artifacts packaging**, choose **Zip**\. @@ -147,13 +149,15 @@ In this step, you create and add a build spec file to the code you created in [C phases: install: runtime-versions: - java: openjdk11 + java: corretto11 post_build: commands: - mvn package + - mv target/my-web-app.war my-web-app.war artifacts: files: - - '**/*' + - my-web-app.war + - .ebextensions/**/* base-directory: 'target/my-web-app' ``` @@ -162,6 +166,8 @@ In this step, you create and add a build spec file to the code you created in [C ``` (root directory name) `-- my-web-app + |-- .ebextensions + | `-- fix-path.config |-- src | `-- main | |-- resources @@ -176,7 +182,7 @@ In this step, you create and add a build spec file to the code you created in [C 1. Upload this contents of the `my-web-app` directory to an Amazon 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 Amazon 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`\. + If you are using an Amazon 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)\. ### Step B2: Create a build project @@ -187,10 +193,12 @@ In this step, you create an AWS CodeBuild build project to use with your pipelin 1. Create a build project\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. - + For **Operating system**, choose **Ubuntu**\. + + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. + For **Artifacts**: + + For **Type**, choose **Amazon S3**\. + + For **Bucket name**, enter the name of an Amazon S3 bucket\. + For **Name**, enter a build output file name that's easy for you to remember\. Include the `.zip` extension\. + For **Artifacts packaging**, choose **Zip**\. @@ -215,8 +223,8 @@ In this step, you use the CodePipeline console to create a pipeline\. After you Use the AWS region selector to choose a region that supports CodeBuild and, if you're storing the source code in an Amazon S3 input bucket, choose the region where your input bucket is stored\. 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\. - + For **Step 3: Add build stage**, for **Build provider**, choose CodeBuild\. For **Project name**, choose the build project you just created\. - + For **Step 4: Add deploy stage**, for **Deployment provider**, choose **AWS Elastic Beanstalk**\. + + 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\. + For **Environment name**, choose the environment you just created\. @@ -234,14 +242,6 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f 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 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\. - - ``` - container_commands: - fix_path: - command: "unzip my-web-app.war 2>&1 > /var/log/my_last_deploy.log" - ``` - 1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. ``` @@ -250,7 +250,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f phases: install: runtime-versions: - java: openjdk11 + java: corretto11 post_build: commands: - mvn package @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 403a6a5..d769c21 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -46,7 +46,7 @@ This bucket must be in the same AWS region as your builds\. For example, if you 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**, for **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\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 5c098cd..7b76ed1 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -9,7 +9,7 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 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 project**\. Otherwise, on the navigation pane, expand **Build**, and then choose **Build projects**\. +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**\. diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index 416e018..cd3f697 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index ea93458..c92d44f 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -1,6 +1,6 @@ # Runtime Versions in Buildspec File Sample for CodeBuild - If you use the Ubuntu standard image version 2\.0, you must specify at least one runtime and its version 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\. + 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 must specify at least one runtime and its version 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\. **Note** If you use Docker in your build container, then your build must run in privileged mode\. For more information, see [Run a Build in CodeBuild](run-build.md) and [Create a Build Project in CodeBuild](create-project.md)\. @@ -114,9 +114,9 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 1. Create a build project\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. - + For **Operating system**, choose **Ubuntu**\. - + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/standard:2\.0**\. + + For **Operating system**, choose **Amazon Linux 2**\. + + For **Runtime\(s\)**, choose **Standard**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. 1. Choose **Start build**\. @@ -164,7 +164,9 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co ## Specify a Runtime Dependency - You might use a runtime that is dependent on another runtime\. For example, the Android runtime version 28 is dependent on the Java runtime version 8\. If you specify Android version 28, you must also specify Java version 8\. This example shows how to specify a runtime and a dependency runtime\. The build project uses source code in the GitHub [AWS Samples](https://github.com/aws-samples) repository\. The source code uses the Android version 28 runtime, so it must also specify Java version 8\. + This example shows how to specify a runtime and a dependency runtime\. For example, the Android runtime version 28 is dependent on the Java or Corretto runtime version 8\. If you specify Android version 28 and use Amazon Linux 2, you must also specify Corretto version 8\. If you specify Android version 28 and use Ubuntu, you must also specify Java version 8\. + + 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 must also specify Corretto 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)\. @@ -189,7 +191,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co install: runtime-versions: android: 28 - java: openjdk8 + java: corretto8 build: commands: - ./gradlew assembleDebug @@ -206,7 +208,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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 28 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 28 and Corretto version 8 are installed: ``` [Container] 2019/05/14 23:21:42 Entering phase INSTALL @@ -324,9 +326,9 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 1. Create a build project\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. - + For **Operating system**, choose **Ubuntu**\. + + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. 1. Choose **Create build project**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index 570fecf..b46e276 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -35,9 +35,9 @@ To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git + For **Repository URL**, enter **https://github\.com/aws/aws\-sdk\-ruby\.git**\. + In **Environment**: + For **Environment image**, choose **Managed image**\. - + For **Operating system**, choose **Ubuntu**\. + + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. - + For **Image**, choose **aws/codebuild/standard:2\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. 1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 3ade0e0..c73c400 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -49,7 +49,7 @@ Use the information in this topic to help you identify, diagnose, and address is **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\." -**Possible cause:** Your build uses version 2\.0 or later of the Ubuntu standard image and a runtime is not specified in the buildspec file\. +**Possible cause:** Your build uses 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 not specified in the buildspec file\. **Recommended solution:** If you use the `aws/codebuild/standard:2.0` CodeBuild managed image, you must specify a runtime version in the `runtime-versions` section of the buildspec file\. For example, you might use the following buildspec file for a project that uses PHP: @@ -101,9 +101,9 @@ artifacts: **Issue:** When you run a build, the build log contains the warning, "Skipping install of runtimes\. Runtime version selection is not supported by this build image\." -**Possible cause:** Your build does not use version 2\.0 or later of the Ubuntu standard image and a runtime is specified in a `runtime-versions` section in your buildspec file\. +**Possible cause:** Your build does not use version 1\.0 or later of the Amazon Linux \(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 Ubuntu standard image version 2\.0 or higher\. +**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 \(AL2\) standard image or later or the Ubuntu standard image version 2\.0 or later\. ## Error: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build @@ -437,12 +437,14 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u ## RequestError timeout error when running CodeBuild in a proxy server - **Issue:** You receive an error similar to `RequestError: send request failed caused by: Post https://logs..amazonaws.com/: dial tcp 52.46.158.105:443: i/o timeout` from CloudWatch Logs or `Error uploading artifacts: RequestError: send request failed caused by: Put https://.s3..amazonaws.com/*: dial tcp 52.219.96.208:443: connect: connection refused` from Amazon S3\. + **Issue:** You receive a `RequestError` error similar to one of the following: ++ `RequestError: send request failed caused by: Post https://logs..amazonaws.com/: dial tcp 52.46.158.105:443: i/o timeout` from CloudWatch Logs\. ++ `Error uploading artifacts: RequestError: send request failed caused by: Put https://your-bucket.s3.your-aws-region.amazonaws.com/*: dial tcp 52.219.96.208:443: connect: connection refused` from Amazon S3\. **Possible causes:** + `ssl-bump` is not configured properly\. + Your organization's security policy does not allow you to use `ssl_bump`\. -+ Proxy configuration is not added to the buildspec file\. ++ Your buildspec file does not have proxy settings specified using a `proxy` element\. **Recommended solutions:** + Make sure `ssl-bump` is configured properly\. If you use Squid for your proxy server, see [ Configure Squid as an Explicit Proxy Server](use-proxy-server.md#use-proxy-server-explicit-squid-configure)\. @@ -453,7 +455,7 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u 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)\. 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)\. -+ You need to add proxy configuration to your buildspec file if you do not use `ssl-bump`: ++ 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. ``` version: 0.2 @@ -463,7 +465,6 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u phases: build: commands: - - command ``` ## Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index 29a1872..c82a027 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -124,42 +124,43 @@ sudo cat squid.key squid.crt | sudo tee squid.pem http_access allow localnet allowed_sites http_access allow localnet download_src ``` -+ For allowing CodeBuild to upload logs and artifacts. There are two methods: - -1. Before the `http_access deny all` statement, insert the following statements\. They allow CodeBuild to access CloudWatch and Amazon S3\. Access to CloudWatch is required so that CodeBuild can create CloudWatch logs\. Access to Amazon S3 is required for uploading artifacts and Amazon S3 caching\. - - ``` - https_port 3130 cert=/etc/squid/ssl/squid.pem ssl-bump intercept - acl SSL_port port 443 - http_access allow SSL_port - acl allowed_https_sites ssl::server_name .amazonaws.com - acl step1 at_step SslBump1 - acl step2 at_step SslBump2 - acl step3 at_step SslBump3 - ssl_bump peek step1 all - ssl_bump peek step2 allowed_https_sites - ssl_bump splice step3 allowed_https_sites - ssl_bump terminate step2 all - ``` - After you save `squid.conf`, execute the following: - - ``` - sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3130 - sudo service squid restart - ``` - -1. Add proxy configuration to your buildspec file\. - - ``` - version: 0.2 - proxy: - upload-artifacts: yes - logs: yes - phases: - build: - commands: - - command - ``` ++ If you want your build to upload logs and artifacts, do one of the following: + + 1. Before the `http_access deny all` statement, insert the following statements\. They allow CodeBuild to access CloudWatch and Amazon S3\. Access to CloudWatch is required so that CodeBuild can create CloudWatch logs\. Access to Amazon S3 is required for uploading artifacts and Amazon S3 caching\. + + + + ``` + https_port 3130 cert=/etc/squid/ssl/squid.pem ssl-bump intercept + acl SSL_port port 443 + http_access allow SSL_port + acl allowed_https_sites ssl::server_name .amazonaws.com + acl step1 at_step SslBump1 + acl step2 at_step SslBump2 + acl step3 at_step SslBump3 + ssl_bump peek step1 all + ssl_bump peek step2 allowed_https_sites + ssl_bump splice step3 allowed_https_sites + ssl_bump terminate step2 all + ``` + + After you save `squid.conf`, execute the following: + + ``` + sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3130 + sudo service squid restart + ``` + + 1. Add `proxy` to your buildspec file\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + ``` + version: 0.2 + proxy: + upload-artifacts: yes + logs: yes + phases: + build: + commands: + - command + ``` **Note** If you receive a RequestError timeout error, see [ RequestError timeout error when running CodeBuild in a proxy server](troubleshooting.md#code-request-timeout-error)\. diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index 8d1e6a1..f626b2b 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -84,7 +84,7 @@ The following are some guidelines to assist you when troubleshooting a common Co 1. [Make sure that the route table for your public subnet points to the internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Route_Tables.html#route-tables-internet-gateway)\. -1. [Make sure that your network ACLs allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_ACLs.html#ACLRules)\. +1. [Make sure that your network ACLs allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_SecurityGroups.html#SecurityGroupRules)\. 1. [Make sure that your security groups allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_SecurityGroups.html#SecurityGroupRules)\. From cfda4f67be8b3e6b906448fb6d5149ffb7b23de2 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Tue, 24 Sep 2019 16:49:37 +0000 Subject: [PATCH 003/156] Periodic update, Sept 24, 2019 --- .../auth-and-access-control-using-tags.md | 61 +++++++++++++++++++ doc_source/build-env-ref-env-vars.md | 2 +- doc_source/build-spec-ref.md | 10 +-- doc_source/history.md | 2 +- doc_source/index.md | 1 + doc_source/monitoring-builds.md | 2 +- doc_source/sample-build-notifications.md | 2 +- doc_source/sample-codedeploy.md | 4 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-lambda.md | 2 +- 13 files changed, 81 insertions(+), 17 deletions(-) create mode 100644 doc_source/auth-and-access-control-using-tags.md diff --git a/doc_source/auth-and-access-control-using-tags.md b/doc_source/auth-and-access-control-using-tags.md new file mode 100644 index 0000000..427179c --- /dev/null +++ b/doc_source/auth-and-access-control-using-tags.md @@ -0,0 +1,61 @@ +# Using Tags to Control Access to CodeBuild Resources + +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 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)\. + +**Example 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\. + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Deny", + "Action": [ + "codebuild:BatchGetProjects" + ], + "Resource": "*", + "Condition": { + "ForAnyValue:StringEquals": { + "aws:ResourceTag/Environment": "Production" + } + } + } + ] +} +``` + +**Example 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 + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Deny", + "Action": [ + "codebuild:CreateProject" + ], + "Resource": "*", + "Condition": { + "ForAnyValue:StringEquals": { + "aws:RequestTag/Environment": "Production" + } + } + }, + { + "Effect": "Deny", + "Action": [ + "codebuild:UpdateProject" + ], + "Resource": "*", + "Condition": { + "ForAnyValue:StringEquals": { + "aws:TagKeys": ["Environment"] + } + } + } + ] +} +``` \ No newline at end of file diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 4a154c1..99c10ec 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -24,7 +24,7 @@ For a GitHub or GitHub Enterprise build that is triggered by a webhook pull requ + `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\. ++ `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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 9e91e49..ad2f18c 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -137,10 +137,12 @@ If an environment variable with the same name is defined in multiple places, the 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 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. The value in the build spec declaration takes lowest precedence\. - + `git-credential-helper`: Optional mapping\. Represents whether CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used; otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. -+ `proxy`: Optional sequence\. Represents settings if you run your build in an explicit proxy server\. For more information, see [](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. - + `upload-artifacts`: Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default setting is `no`\. - + `logs`: Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch Logs\. The default setting is `no`\. + + `git-credential-helper`: Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. +**Note** + `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. ++ `proxy`: Optional sequence\. Used to represent settings if you run your build in an explicit proxy server\. For more information, see [ Run CodeBuild in an Explicit Proxy Server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. + + `upload-artifacts`: Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default is `no`\. + + `logs`: Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch logs\. The default is `no`\. + `phases`: Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. **Note** In build spec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use build spec version 0\.1, we recommend the approaches in [Shells and Commands in Build Environments](build-env-ref-cmd.md)\. diff --git a/doc_source/history.md b/doc_source/history.md index 6a03412..4f84fce 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **September 6, 2019 ++ **Latest documentation update: **September 18, 2019 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/index.md b/doc_source/index.md index e5187d0..e9fb8fc 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -83,6 +83,7 @@ Amazon's trademarks and trade dress may not be used in + [Overview of Managing Access Permissions to Your CodeBuild Resources](auth-and-access-control-iam-access-control-identity-based.md) + [Using Identity-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) + [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md) + + [Using Tags to Control Access to CodeBuild Resources](auth-and-access-control-using-tags.md) + [Viewing Resources in the Console](console-resources.md) + [Logging and Monitoring in AWS CodeBuild](security-incident-response.md) + [Logging CodeBuild API Calls with AWS CloudTrail](cloudtrail.md) diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index 03f90a0..9bce333 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.md @@ -48,4 +48,4 @@ + `FailedBuild`\. You can create an alarm that is triggered when a certain number of failed builds are detected within a predetermined number of seconds\. In CloudWatch you specify the number of seconds and how many faild builds trigger an alarm\. + `Duration`\. You can create an alarm that is triggered when a build takes longer than expected\. You specify how many seconds must elapse after a build is started and before a build is completed before the alarm is triggered\. - For infomration about how to create alarms for CodeBuild metrics, see [Monitoring Builds with CloudWatch Alarms](monitoring-alarms.md)\. For more information about alarms, see [ Creating Amazon CloudWatch Alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)\. \ No newline at end of file + For information about how to create alarms for CodeBuild metrics, see [Monitoring Builds with CloudWatch Alarms](monitoring-alarms.md)\. For more information about alarms, see [ Creating Amazon CloudWatch Alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)\. \ No newline at end of file diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 57fff56..f7311b3 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index d1cea37..ae4f32f 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -46,7 +46,7 @@ To run this sample: phases: install: runtime-versions: - java: openjdk8 + java: corretto8 build: commands: - echo Build started on `date` @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 65b336e..051e967 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w13aac11c41c32c17) ++ [Related Resources](#w16aac11c41c32c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index b4747fa..f38c1b9 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w13aac11c41c17c23) ++ [Related Resources](#w16aac11c41c17c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index d1cbcc4..9aace41 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 0c6ce12..671171c 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index cd3f697..0c577f2 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file From 08cfea4e31201a9d3b2d9230fc14a6dfe930122f Mon Sep 17 00:00:00 2001 From: Steven Braverman Date: Wed, 25 Sep 2019 10:37:32 -0700 Subject: [PATCH 004/156] removes characters '.2' from within yaml file causing issues --- doc_source/sample-windows.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index 3321eaa..4d3a14f 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -516,7 +516,7 @@ 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'.2 + - '& "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: - .\VBHelloWorld\bin\Debug\* @@ -1084,4 +1084,4 @@ namespace HelloWorldSample } } } -``` \ No newline at end of file +``` From 373862cf306e22044a55ea53fb9780ba173cd662 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Mon, 30 Sep 2019 17:53:12 +0000 Subject: [PATCH 005/156] Periodic update - September 30, 2019 --- doc_source/history.md | 2 +- doc_source/sample-runtime-versions.md | 2 +- doc_source/sample-windows.md | 2 +- doc_source/vpc-support.md | 3 +++ 4 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc_source/history.md b/doc_source/history.md index 4f84fce..4b8ed48 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **September 18, 2019 ++ **Latest documentation update: **September 30, 2019 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index c92d44f..c99d086 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -1,6 +1,6 @@ # 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 must specify at least one runtime and its version 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\. + 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 must specify at least one runtime and its version 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, then your build must run in privileged mode\. For more information, see [Run a Build in CodeBuild](run-build.md) and [Create a Build Project in CodeBuild](create-project.md)\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index 4d3a14f..aaab7e8 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -1084,4 +1084,4 @@ namespace HelloWorldSample } } } -``` +``` \ No newline at end of file diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index f626b2b..b55e300 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -2,6 +2,9 @@ Typically, resources in an VPC are not accessible by AWS CodeBuild\. To enable access, you must provide additional VPC\-specific configuration information as part of your CodeBuild project configuration\. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs\. VPC\-enabled builds are then able to access resources inside your VPC\. For more information about setting up a VPC in Amazon VPC, see the [VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Introduction.html)\. +**Note** + VPC connectivity from CodeBuild is not supported in Windows\. + **Topics** + [Use Cases](#use-cases) + [Enabling Amazon VPC Access in Your CodeBuild Projects](#enabling-vpc-access-in-projects) From 4107f807838cae43a0cdfbe544393ddd515c5450 Mon Sep 17 00:00:00 2001 From: BengalBrony Date: Thu, 3 Oct 2019 15:29:23 -0500 Subject: [PATCH 006/156] Fix typo in word 'artifact' changed 'arifact' to 'artifact' --- doc_source/build-spec-ref.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index ad2f18c..4eeba8c 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -191,7 +191,7 @@ Commands in some build phases might not be run if commands in earlier build phas You can specify a name in the build spec file that is calculated at build time\. The name specified in a build spec 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 arifact name appended with the date the artifact is created\. + This is an example of an artifact name appended with the date the artifact is created\. ``` version: 0.2 @@ -423,4 +423,4 @@ The following table lists the build spec versions and the changes between versio | 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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From 9375175ac5d3bbf7ec8d138f1f6d8fa504e9a08e Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Thu, 3 Oct 2019 20:56:08 +0000 Subject: [PATCH 007/156] Periodic update - October 3, 2019 --- doc_source/build-env-ref-available.md | 6 ++--- doc_source/build-spec-ref.md | 18 +++++++------- doc_source/history.md | 3 ++- doc_source/sample-ecr.md | 2 +- doc_source/sample-runtime-versions.md | 34 +++++++++++++-------------- 5 files changed, 31 insertions(+), 32 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index b4498d7..552045a 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -18,13 +18,13 @@ AWS CodeBuild manages the following Docker images that are available in the Code | Runtime name | Version/versions | How to specify in the buildspec file | | --- | --- | --- | -| android | 28 | android: 28 | +| android | 28, 29 | android: 28, android: 29 | | docker | 18 | docker: 18 | | dotnet | 2\.2 | dotnet: 2\.2 | -| golang | 1\.12 | golang: 1\.12 | +| golang | 1\.12, 1\.13 | golang: 1\.12, golang: 1\.13 | | nodejs | 8, 10 | nodejs: 8, nodejs: 10 | | java \(Ubuntu only\) | openjdk8, openjdk11 | java: openjdk8, java: openjdk11 | -| corretto \(Amazon Linux 2 only\) | corretto8, corretto11 | java: corretto8, java: corretto11 | +| java \(Amazon Linux 2 only\) | corretto8, corretto11 | java: corretto8, java: corretto11 | | php | 7\.3 | php: 7\.3 | | python | 3\.7 | python: 3\.7 | | ruby | 2\.6 | ruby: 2\.6 | diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 4eeba8c..09f4385 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -150,22 +150,22 @@ In build spec version 0\.1, CodeBuild runs each command in a separate instance o The allowed build phase names are: + `install`: Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. - + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, the following specifies that version 8 of `openjdk`, version 28 of `android`, and a version contained in an environment variable of `ruby` is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. -**Note** - 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\." + + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 1\.0, then the following specifies that version 8 of Java, version 29 of Android, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. ``` phases: install: runtime-versions: - java: openjdk8 - android: 28 + java: corretto8 + android: 29 ruby: "$MY_RUBY_VAR" ``` - + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, `android` version 28 requires version 8 of `openjdk`\. If `android: 28` is specified, and `openjdk: 8` is not, the build fails\. - + If two specified runtimes conflict, the build fails\. For example, `android: 8` and `java: openjdk11` conflict, so if both are specified, the build fails\. - + The following runtimes can be specified\. + + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, if you use any supported version of `android`, then version 8 of Java is required\. If you use the Ubuntu standard image 2\.0, you specify this using `java: openkdk8`\. If you use the Amazon Linux 2 standard image 1\.0, you specify this using `java: corretto8`\. + + 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\. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) +**Note** + 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\." + `commands`: Required sequence unless you specify `runtime-versions`\. Optional if you specify `runtime-versions`\. 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\. + `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\. + `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\. @@ -423,4 +423,4 @@ The following table lists the build spec versions and the changes between versio | 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/history.md b/doc_source/history.md index 4b8ed48..7e2ce3d 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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: **September 30, 2019 ++ **Latest documentation update: **Octorber 3, 2019 | Change | Description | Date | | --- |--- |--- | +| [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 [Build Spec 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 | diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 9aace41..6ef13c8 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -152,7 +152,7 @@ version: 0.2 phases: install: runtime-versions: - golang: 1.12 + golang: 1.13 build: commands: - echo Build started on `date` diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index c99d086..62995cb 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -7,8 +7,8 @@ ## 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 Corretto versions 8 and 11: -+ A `runtime-versions` section that specifies version 8 of Corretto \(Amazon Linux 2 only\): + 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: ``` phases: @@ -16,7 +16,7 @@ runtime-versions: java: corretto8 ``` -+ A `runtime-versions` section that specifies version 11 of Corretto \(Amazon Linux 2 only\): ++ A `runtime-versions` section that specifies version 11 of Java if you use the Amazon Linux 2 standard image: ``` phases: @@ -24,9 +24,7 @@ runtime-versions: java: corretto11 ``` - -The following examples show how to specify Java versions 8 and 10: -+ A `runtime-versions` section that specifies version 8 of Java \(Ubuntu only\): ++ A `runtime-versions` section that specifies version 8 of Java if you use the Ubuntu standard image 2\.0: ``` phases: @@ -34,7 +32,7 @@ The following examples show how to specify Java versions 8 and 10: runtime-versions: java: openjdk8 ``` -+ A `runtime-versions` section that specifies version 11 of Java \(Ubuntu only\): ++ A `runtime-versions` section that specifies version 11 of Java if you use the Ubuntu standard image 2\.0: ``` phases: @@ -43,7 +41,7 @@ The following examples show how to specify Java versions 8 and 10: java: openjdk11 ``` - The following examples show how you to specify different versions of Node\.js: + 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 1\.0: + A `runtime-versions` section that specifies Node\.js version 8: ``` @@ -73,7 +71,7 @@ The following examples show how to specify Java versions 8 and 10: phases: install: runtime-versions: - java: openjdk8 + java: corretto8 build: commands: - java -version @@ -143,7 +141,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co ``` install: runtime-versions: - java: openjdk11 + 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: @@ -164,9 +162,9 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co ## Specify a Runtime Dependency - This example shows how to specify a runtime and a dependency runtime\. For example, the Android runtime version 28 is dependent on the Java or Corretto runtime version 8\. If you specify Android version 28 and use Amazon Linux 2, you must also specify Corretto version 8\. If you specify Android version 28 and use Ubuntu, you must also specify Java version 8\. + 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 must also specify Java version 8\. - 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 must also specify Corretto version 8\. + 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 must also specify 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)\. @@ -190,7 +188,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co phases: install: runtime-versions: - android: 28 + android: 29 java: corretto8 build: commands: @@ -200,7 +198,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co - app/build/outputs/apk/app-debug.apk ``` - The `runtime-versions` section specifies both Android version 28 and Java version 8 runtimes\. + The `runtime-versions` section specifies both Android version 29 and Java version 8 runtimes\. 1. Choose **Create build project**\. @@ -208,12 +206,12 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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 28 and Corretto 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 INSTALL - [Container] Date Time Running command echo "Installing Android version 28 ..." - Installing Android version 28 ... + [Container] Date Time Running command echo "Installing Android version 29 ..." + Installing Android version 29 ... [Container] Date Time Running command echo "Installing Java version 8 ..." Installing Java version 8 ... @@ -282,7 +280,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co phases: install: runtime-versions: - golang: 1.12 + golang: 1.13 nodejs: 10 build: commands: From 31980577350084ad6725843b5c092cedda825d31 Mon Sep 17 00:00:00 2001 From: Marek Barczyk Date: Tue, 15 Oct 2019 21:48:58 +0200 Subject: [PATCH 008/156] Typo in java runtime name --- doc_source/build-spec-ref.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 09f4385..3f21756 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -160,7 +160,7 @@ In build spec version 0\.1, CodeBuild runs each command in a separate instance o android: 29 ruby: "$MY_RUBY_VAR" ``` - + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, if you use any supported version of `android`, then version 8 of Java is required\. If you use the Ubuntu standard image 2\.0, you specify this using `java: openkdk8`\. If you use the Amazon Linux 2 standard image 1\.0, you specify this using `java: corretto8`\. + + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, if you use any supported version of `android`, then version 8 of Java is required\. If you use the Ubuntu standard image 2\.0, you specify this using `java: openjdk8`\. If you use the Amazon Linux 2 standard image 1\.0, you specify this using `java: corretto8`\. + 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\. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) From 47eb16c4384ec20ecf7896f28f829c5f4f095493 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Thu, 17 Oct 2019 20:05:26 +0000 Subject: [PATCH 009/156] Periodic update - Oct 17, 2019 --- doc_source/build-caching.md | 6 +++--- doc_source/build-env-ref-available.md | 2 +- doc_source/cloudformation-vpc-template.md | 2 +- doc_source/history.md | 2 +- doc_source/sample-efs.md | 2 +- doc_source/troubleshooting.md | 2 ++ 6 files changed, 9 insertions(+), 7 deletions(-) diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 3142863..85b31c3 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -40,17 +40,17 @@ Docker layer cache mode is available for the Linux environment only\. If you cho + To specify a source cache: ``` - --cache type=Local,mode=[LOCAL_SOURCE_CACHE] + --cache type=LOCAL,mode=[LOCAL_SOURCE_CACHE] ``` + To specify a Docker layer cache: ``` - --cache type=Local,mode=[LOCAL_DOCKER_LAYER_CACHE] + --cache type=LOCAL,mode=[LOCAL_DOCKER_LAYER_CACHE] ``` + To specify a custom cache: ``` - --cache type=Local,mode=[LOCAL_CUSTOM_CACHE] + --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE] ``` For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 552045a..b8637c2 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -35,7 +35,7 @@ AWS CodeBuild manages the following Docker images that are available in the Code | Runtime name | Version in `windows-base:1.0` | Version in `windows-base:2.0` | | --- | --- | --- | | dotnet | 2\.1 | 2\.2 | -| golang | 1\.11 | 1\.12 | +| golang | 1\.11 | 1\.13 | | nodejs | 9\.11 | 10\.16 | | java | openjdk8 | openjdk11 | | php | 7\.2 | 7\.3 | diff --git a/doc_source/cloudformation-vpc-template.md b/doc_source/cloudformation-vpc-template.md index b54783e..4228b2b 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 an Amazon VPC to use the AWS CodeBuild VPC feature\. It is available for download from [https://s3.amazonaws.com/codebuild-cloudformation-templates-public/vpc_cloudformation_template.yml](https://s3.amazonaws.com/codebuild-cloudformation-templates-public/vpc_cloudformation_template.yml)\. +The following is an AWS CloudFormation YAML template for configuring an Amazon VPC to use the AWS CodeBuild VPC feature\. ``` Description: This template deploys a VPC, with a pair of public and private subnets spread diff --git a/doc_source/history.md b/doc_source/history.md index 7e2ce3d..80e5a20 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **Octorber 3, 2019 ++ **Latest documentation update: **Octorber 17, 2019 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 544cc6f..6b08cce 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -18,7 +18,7 @@ Create your Amazon VPC with an AWS CloudFormation template\. -1. Follow the instructions here, [AWS CloudFormation VPC Template](cloudformation-vpc-template.md), to use AWS CloudFormation to create an Amazon VPC\. If you are already familiar with AWS CloudFormation, you can go directly to the AWS CloudFormation console to create a stack using the template available for download from [https://s3.amazonaws.com/codebuild-cloudformation-templates-public/vpc_cloudformation_template.yml](https://s3.amazonaws.com/codebuild-cloudformation-templates-public/vpc_cloudformation_template.yml)\. For more information, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide//Welcome.html)\. +1. Follow the instructions here, [AWS CloudFormation VPC Template](cloudformation-vpc-template.md), to use AWS CloudFormation to create an Amazon VPC\. For more information, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide//Welcome.html)\. **Note** The Amazon VPC created by this AWS CloudFormation template has two private subnets and two public subnets\. You must only use private subnets when you use AWS CodeBuild to mount Amazon EFS\. If you use one of the public subnets, the build fails\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index c73c400..7b52c02 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -264,11 +264,13 @@ artifacts: + 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 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)\. **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 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\. ## Builds Might Fail When File Names Have Non\-U\.S\. English Characters From c4522e42876b8cf7a62e769c88ff18c3695feec6 Mon Sep 17 00:00:00 2001 From: Subin Mathew Date: Sat, 19 Oct 2019 07:44:15 -0700 Subject: [PATCH 010/156] Update build-env-ref-available.md Aligning with the supported images in https://github.com/aws/aws-codebuild-docker-images#image-maintenance --- doc_source/build-env-ref-available.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index b8637c2..7f4e7fa 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -8,7 +8,6 @@ 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:1\.0 | [al2/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/1.0) | -| Ubuntu 18\.04 | aws/codebuild/standard:1\.0 | [ubuntu/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/1.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:1\.0 | N/A | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | @@ -54,4 +53,4 @@ CodeBuild frequently updates the list of Docker images\. To get the most current ``` 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)\. From 8b85964fbadeccbbe023057c532ed37f296798f2 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Mon, 21 Oct 2019 17:09:59 +0000 Subject: [PATCH 011/156] Periodic update - October 21, 2019 --- doc_source/build-env-ref-available.md | 2 +- doc_source/history.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 7f4e7fa..21e8715 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -53,4 +53,4 @@ CodeBuild frequently updates the list of Docker images\. To get the most current ``` 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)\. ++ 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 diff --git a/doc_source/history.md b/doc_source/history.md index 80e5a20..5ed45ec 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **Octorber 17, 2019 ++ **Latest documentation update: **Octorber 21, 2019 | Change | Description | Date | | --- |--- |--- | From 2434eda0081678feb30675e14abff6ea5c8ba1e9 Mon Sep 17 00:00:00 2001 From: Volkan Paksoy <12112743+volkanpaksoy@users.noreply.github.com> Date: Tue, 5 Nov 2019 05:19:17 +0000 Subject: [PATCH 012/156] Update build-caching.md Fixed typo ("tranfer") --- doc_source/build-caching.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 85b31c3..bbf4cc7 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -11,7 +11,7 @@ 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 tranfer over your network, which can affect build performance\. + 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\. ## Local Caching @@ -101,4 +101,4 @@ CodeBuildProject: - LOCAL_SOURCE_CACHE ``` -For more information, see [Create a Build Project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. \ No newline at end of file +For more information, see [Create a Build Project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. From 7dc51da36cc52d9f6f4bb224315d4a0be75e5149 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Thu, 7 Nov 2019 00:05:50 +0000 Subject: [PATCH 013/156] Periodic update - Nov 6, 2019. Includes support for build numbers, exporting environment variables, AWS Secrets Manager integration, and notification rules. --- ...ntrol-iam-identity-based-access-control.md | 123 ++++++++++++++++++ doc_source/build-caching.md | 2 +- doc_source/build-env-ref-compute-types.md | 2 +- doc_source/build-env-ref-env-vars.md | 3 +- doc_source/build-spec-ref.md | 22 ++++ doc_source/change-project.md | 35 +++-- doc_source/cloudformation-vpc-template.md | 6 +- doc_source/create-project.md | 62 +++++---- doc_source/getting-started.md | 3 + doc_source/history.md | 4 +- doc_source/how-to-create-pipeline.md | 18 +-- doc_source/index.md | 1 + doc_source/sample-bitbucket-pull-request.md | 2 +- doc_source/sample-build-badges.md | 14 +- doc_source/sample-build-notifications.md | 2 +- doc_source/sample-codedeploy.md | 2 +- .../sample-disable-artifact-encryption.md | 10 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-github-enterprise.md | 14 +- doc_source/sample-github-pull-request.md | 14 +- doc_source/sample-lambda.md | 2 +- doc_source/security-encryption.md | 2 +- doc_source/working-with-build-projects.md | 1 + 26 files changed, 268 insertions(+), 88 deletions(-) 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 e242db5..54e802b 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 @@ -9,6 +9,7 @@ We recommend that you first review the introductory topics that explain the basi + [Permissions Required to Use the CodeBuild Console](#console-permissions) + [Permissions Required for the CodeBuild Console to Connect to Source Providers](#console-policies) + [AWS Managed \(Predefined\) Policies for CodeBuild](#managed-policies) ++ [CodeBuild Managed Policies and Notifications](#notifications-permissions) + [Customer\-Managed Policy Examples](#customer-managed-policies) The following shows an example of a permissions policy that allows a user to get information about build projects only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: @@ -67,6 +68,128 @@ To create and manage CodeBuild service roles, you must also attach the AWS manag You can also create your own custom IAM policies to allow permissions for CodeBuild actions and resources\. You can attach these custom policies to the IAM users or groups that require those permissions\. +## CodeBuild Managed Policies and Notifications + +CodeBuild supports notifications, which can notify users of important changes to build projects\. Managed policies for CodeBuild include policy statements for notification functionality\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html)\. + +### Permissions Related to Notifications in Full Access Managed Policies + +The `AWSCodeBuildFullAccess` managed policy includes the following statements to allow full access to notifications\. Users with this managed policy applied can also create and manage Amazon SNS topics for notifications, subscribe and unsubscribe users to topics, and list topics to choose as targets for notification rules\. + +``` + { + "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: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" + ], + "Resource": "*" + } +``` + +### Permissions Related to Notifications in Read\-Only Managed Policies + +The `AWSCodeBuildReadOnlyAccess` managed policy includes the following statements to allow read\-only access to notifications\. Users with this managed policy applied can view notifications for resources, but cannot create, manage, or subscribe to them\. + +``` + { + "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" + ], + "Resource": "*" + } +``` + +### Permissions Related to Notifications in Other Managed Policies + +The `AWSCodeBuildDeveloperAccess` managed policy includes the following statements to allow users to create, edit, and subscribe to notifications\. Users cannot delete notification rules or manage tags for resources\. + +``` + { + "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:ListTargets", + "codestar-notifications:ListTagsforResource" + ], + "Resource": "*" + }, + { + "Sid": "SNSTopicListAccess", + "Effect": "Allow", + "Action": [ + "sns:ListTopics" + ], + "Resource": "*" + } +``` + +For more information about IAM and notifications, see [Identity and Access Management for AWS CodeStar Notifications](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security-iam.html)\. + ## Customer\-Managed Policy Examples In this section, you can find example user policies that grant permissions for AWS CodeBuild actions\. These policies work when you are using the CodeBuild API, AWS SDKs, or AWS CLI\. When you are using the console, you must grant additional permissions specific to the console\. For information, see [Permissions Required to Use the CodeBuild Console](#console-permissions)\. diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index bbf4cc7..e2c9950 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -101,4 +101,4 @@ CodeBuildProject: - LOCAL_SOURCE_CACHE ``` -For more information, see [Create a Build Project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. +For more information, see [Create a Build Project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. \ 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 db2733f..8b2de41 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -12,7 +12,7 @@ AWS CodeBuild provides build environments with the following available memory, v | build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | Linux, Windows | **Note** -For custom build environment images, CodeBuild supports Docker images up to 20 GB uncompressed in Linux and 50 GB uncompressed in Windows, regardless of the compute type\. To check your build image's size, use Docker to run the `docker images REPOSITORY:TAG` command\. +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.md#create-project-console) or [Change a Build Project's Settings \(Console\)](change-project.md#change-project-console)\. diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 99c10ec..8827527 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -6,6 +6,7 @@ AWS CodeBuild provides several environment variables that you can use in your bu + `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`\)\. @@ -16,7 +17,7 @@ AWS CodeBuild provides several environment variables that you can use in your bu + 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 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, and Bitbucket it is the commit ID, branch name, or tag name associated with the version of the source code to be built\. **Note** diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 3f21756..9c8f504 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -44,6 +44,11 @@ env: parameter-store: key: "value" key: "value" + exported-variables: + - variable + - variable + secrets-manager: + key: secret-id:json-key:version-stage:version-id git-credential-helper: yes proxy: @@ -137,6 +142,23 @@ If an environment variable with the same name is defined in multiple places, the 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 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. The value in the build spec declaration takes lowest precedence\. + + `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\. + + `verstion-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*\. + + `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\. +**Note** + 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 + Environment variables that start with `AWS_`\. + `git-credential-helper`: Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. **Note** `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. diff --git a/doc_source/change-project.md b/doc_source/change-project.md index b1df62e..2beb814 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -17,7 +17,7 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to change a build pr + 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 in **Description**\. +1. To change the project's description, in **Project configuration**, choose **Edit**, and then enter a description\. Choose **Update configuration**\. @@ -50,23 +50,32 @@ When you use the console to create or update a build project, you can create a C 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 row** to add an environment variable\. Choose the delete \(**X**\) button next to an environment variable you no longer want to use\. +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\. For **Type**, choose **Parameter Store**\. 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 Store**\. For **Name**, enter `LOGIN_PASSWORD`\. For **Value**, enter `/CodeBuild/dockerLoginPassword`\. + 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** -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 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 **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 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 **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/`\. -If you choose **Create a service role in your account**, the created service role includes permission to decrypt all parameters under the `/CodeBuild/` namespace in the Amazon EC2 Systems Manager 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 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 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 automatically\. 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, its value is determined as follows: +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 build spec declaration takes lowest precedence\. + If you use Secrets Manager, then 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 automatically\. 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. + 1. To change information about tags for this build project, in **Additional configuration**, for **Tags**, change the values of **Name** and **Value**\. Use **Add row** to add a tag\. You can add up to 50 tags\. Choose the delete \(**X**\) icon next to a tag you no longer want to use\. 1. Choose **Update environment**\. @@ -79,7 +88,7 @@ The value in the build spec declaration takes lowest precedence\. 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 master key \(CMK\), in **Additional configuration**, change the value for **Encryption key**\. +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\. @@ -87,9 +96,9 @@ If you leave **Encryption key** blank, CodeBuild uses the AWS\-managed CMK for A + 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 Amazon 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 that enables you to store the cache under the same directory in a bucket\. + + \(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 "/" to the end of **Path prefix**\. +Do not append a forward slash \(/\) to the end of **Path prefix**\. 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 build spec file, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. @@ -112,7 +121,7 @@ Do not append "/" to the end of **Path prefix**\. ## Change a Build Project's Settings \(AWS CLI\) -For more information about using the AWS CLI with AWS CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +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: @@ -124,7 +133,7 @@ For more information about using the AWS CLI with AWS CodeBuild, see the [Comman **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\-projectcommand again\. +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 diff --git a/doc_source/cloudformation-vpc-template.md b/doc_source/cloudformation-vpc-template.md index 4228b2b..a5f8ada 100644 --- a/doc_source/cloudformation-vpc-template.md +++ b/doc_source/cloudformation-vpc-template.md @@ -6,13 +6,13 @@ The following is an AWS CloudFormation YAML template for configuring an Amazon V ``` Description: This template deploys a VPC, with a pair of public and private subnets spread - across two Availability Zones. It deploys an Internet Gateway, with a default - route on the public subnets. It deploys a pair of NAT Gateways (one in each AZ), + across two Availability Zones. It deploys an internet gateway, with a default + route on the public subnets. It deploys a pair of NAT gateways (one in each AZ), and default routes for them in the private subnets. Parameters: EnvironmentName: - Description: An environment name that will be prefixed to resource names + Description: An environment name that is prefixed to resource names Type: String VpcCIDR: diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 4cc6267..9b6f6a0 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -23,9 +23,7 @@ Answer the questions in [Plan a Build](planning.md)\. 1. In **Project configuration**: - On the **Create build project** page, in **Project configuration**, for **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\. - - In **Description**, enter an optional description for your project\. + 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\. 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** @@ -55,8 +53,8 @@ CodeBuild does not support Bitbucket Server\. 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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**, then 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, and then enter the Amazon Resource Name \(ARN\) of the credentials for your private Docker image\. The credentials must be created by AWS Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) + + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) \(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\. @@ -66,8 +64,8 @@ CodeBuild does not support Bitbucket Server\. ``` In **Service role**, do one of the following: - + If you do not have a CodeBuild service role, choose **New service role**\. In **Role name**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -95,12 +93,14 @@ IMAGE\_TAG 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\. 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`\. + 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** -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 parameter**, and then follow the instructions in the dialog box\. \(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 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, then CodeBuild includes this action in the default service role for your build project automatically\. However, if you chose **Existing service role**, then 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**, 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/`\. -If you choose **Create a service role in your account**, the created service role includes permission to decrypt all parameters under the `/CodeBuild/` namespace in the Amazon EC2 Systems Manager 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 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 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 automatically\. 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: @@ -108,6 +108,13 @@ 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 build spec declaration takes lowest precedence\. + If you use Secrets Manager, then 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 automatically\. 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 created 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: @@ -140,7 +147,7 @@ The value in the build spec declaration takes lowest precedence\. Expand **Additional configuration**\. \(Optional\) For **Encryption key**, do one of the following: - + To use the AWS\-managed customer master key \(CMK\) for Amazon S3 in your account to encrypt the build output artifacts, leave **Encryption key** blank\. This is the default\. + + 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: @@ -418,15 +425,15 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re ``` aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region us-east-1 ``` -**Note** -If you are using a region other than us\-east\-1, be sure to use it when you run the command\. + + If you are using a region other than `us-east-1`, be sure to use it when you run the command\. + *securityGroupIds*: Required value\. 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 ``` -**Note** -If you are using a region other than us\-east\-1, be sure to use it when you run the command\. + + If you are using a region other than `us-east-1`, be sure to use it when you run the command\. + For the required `environment` object, information about this project's build environment settings\. These settings include: + *environment\-type*: Required value\. The type of build environment\. Valid values are `LINUX_CONTAINER` and `WINDOWS_CONTAINER`\. + *image*: Required value\. 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:2.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)\. @@ -436,16 +443,27 @@ If you are using a region other than us\-east\-1, be sure to use it when you run 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 *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\. For *environmentVariable\-name*, for that stored parameter, set an identifier for CodeBuild to reference\. For *environmentVariable\-value*, set the parameter's name as stored in Amazon EC2 Systems Manager 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`\. + 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** -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 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 **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`\. +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 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 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 automatically\. 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 build spec 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** +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 automatically\. 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 created 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`\. @@ -466,7 +484,7 @@ The value in the build spec declaration takes lowest precedence\. ``` + *badgeEnabled*: Optional value\. 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 value\. 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 value\. The alias or ARN of the AWS KMS customer master key \(CMK\) CodeBuild uses 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\. + + *encryptionKey*: Optional value\. The alias or ARN of the AWS KMS customer managed key \(CMK\) CodeBuild uses 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 that contains a `key` and `value` value of *tag\-key* and *tag\-value*\. For an example, see [To create the build project \(AWS CLI\)](getting-started.md#getting-started-create-build-project-cli)\. diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index 09753a5..560d1e2 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -428,6 +428,7 @@ You can use the [CodeBuild console](#getting-started-run-build-console) or [AWS { "build": { "buildComplete": false, + "buildNumber": 1, "initiator": "user-name", "artifacts": { "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip" @@ -454,6 +455,7 @@ You can use the [CodeBuild console](#getting-started-run-build-console) or [AWS ``` + `build` represents information about this build\. + `buildComplete` represents whether the build was completed \(`true`\); otherwise, `false`\. + + `buildNumber` represents the build number for the CodeBuild build project\. The first build is number 1\. For each build run, `buildNumber` is incremented by 1\. + `initiator` represents the entity that started the build\. + `artifacts` represents information about the build output, including its location\. + `projectName` represents the name of the build project\. @@ -514,6 +516,7 @@ If successful, data similar to this appears in the output\. "builds": [ { "buildComplete": true, + "buildNumber": 1, "phases": [ { "phaseStatus": "SUCCEEDED", diff --git a/doc_source/history.md b/doc_source/history.md index 5ed45ec..34fca3a 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,12 @@ 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: **Octorber 21, 2019 ++ **Latest documentation update: **November 6, 2019 | Change | Description | Date | | --- |--- |--- | +| [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-specc) and [Secrets Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#secrets-manager-build-spec) in [Build Spec 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-acb.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 [Build Spec 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 | diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 7b05912..b041d40 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -152,8 +152,8 @@ If you enable webhooks for an AWS CodeBuild project, and the project is used as ``` 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -165,7 +165,7 @@ When you use the console to create or update a build project, you can create a C 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 using the CodeBuild console and AWS CLI\. +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: @@ -442,8 +442,8 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui ``` 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -455,7 +455,7 @@ When you use the console to create or update a build project, you can create a C 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 using the CodeBuild console and AWS CLI\. +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: @@ -581,8 +581,8 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui ``` 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -594,7 +594,7 @@ When you use the console to create or update a build project, you can create a C 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 using the CodeBuild console and AWS CLI\. +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: diff --git a/doc_source/index.md b/doc_source/index.md index e9fb8fc..52ae0bb 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -60,6 +60,7 @@ Amazon's trademarks and trade dress may not be used in + [Working with Build Projects and Builds in CodeBuild](builds-projects-and-builds.md) + [Working with Build Projects](working-with-build-projects.md) + [Create a Build Project in CodeBuild](create-project.md) + + [Create a Notification Rule](notification-rule-create.md) + [View a List of Build Project Names in CodeBuild](view-project-list.md) + [View a Build Project's Details in CodeBuild](view-project-details.md) + [Build Caching in CodeBuild](build-caching.md) diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 2194a03..32151aa 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -23,7 +23,7 @@ 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**, for **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. 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**, 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/) diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 046845f..044de22 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**, for **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. 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**, for **Source provider**, choose the source code provider type, and then do one of the following: + If you chose **Amazon S3**, then for **Bucket**, choose the name of the input bucket that contains the source code\. For **S3 object key**, enter the name of the ZIP file that contains the source code\. @@ -22,12 +22,12 @@ 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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**, then 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, and then enter the Amazon Resource Name \(ARN\) of the credentials for your private Docker image\. The credentials must be created by AWS Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) + + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -38,11 +38,11 @@ When you use the console to create or update a build project, you can create a C For more information, see the [Build Spec 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**\. + + If you do not want to create build output artifacts, choose **No artifacts**\. + To store the build output in an Amazon 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, 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. 1. Expand **Additional configuration** and set options as appropriate\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index f7311b3..6663743 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index ae4f32f..56f39d7 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index a190c4d..f21027d 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**, for **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. 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**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub, and then choose **Authorize**\. @@ -19,12 +19,12 @@ 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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**, then 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, and then enter the Amazon Resource Name \(ARN\) of the credentials for your private Docker image\. The credentials must be created by AWS Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) + + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 051e967..317f91d 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w16aac11c41c32c17) ++ [Related Resources](#w26aac11c41c32c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index f38c1b9..642d8cb 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w16aac11c41c17c23) ++ [Related Resources](#w26aac11c41c17c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 6ef13c8..b168db1 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 671171c..3d9db5a 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index d769c21..0515177 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**, for **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. 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**, 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 repository\. @@ -66,12 +66,12 @@ 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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**, then 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, and then enter the Amazon Resource Name \(ARN\) of the credentials for your private Docker image\. The credentials must be created by AWS Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) + + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -93,11 +93,11 @@ When you use the console to create or update a build project, you can create a C For more information, see the [Build Spec 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**\. + + If you do not want to create build output artifacts, choose **No artifacts**\. + To store the build output in an Amazon 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, 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. 1. Expand **Additional configuration**\. In **Cache type**, do one of the following: + If you do not want to use a cache, choose **No cache**\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 7b76ed1..48eaf31 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -15,7 +15,7 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 1. In **Project configuration**: - On the **Create build project** page, in **Project configuration**, for **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**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub and then choose **Authorize**\. @@ -31,12 +31,12 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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**, then 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, and then enter the Amazon Resource Name \(ARN\) of the credentials for your private Docker image\. The credentials must be created by AWS Secrets Manager\. For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) + + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) 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**, accept the default name or enter your own\. - + If you have a CodeBuild service role, choose **Existing service role**\. In **Role name**, choose the service role\. + + 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\. @@ -47,11 +47,11 @@ When you use the console to create or update a build project, you can create a C For more information, see the [Build Spec 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**\. + + If you do not want to create build output artifacts, choose **No artifacts**\. + To store the build output in an Amazon 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, 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. 1. Expand **Additional configuration** and set options as appropriate\. diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index 0c577f2..8602f79 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 2ebbea1..6568e89 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -7,4 +7,4 @@ 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 SSL 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 acccount\. If you do not want to use this CMK, 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)\. \ No newline at end of file ++ **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 KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 1242606..bbd58e9 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -6,6 +6,7 @@ You can perform these tasks when working with build projects: **Topics** + [Create a Build Project in CodeBuild](create-project.md) ++ [Create a Notification Rule](notification-rule-create.md) + [View a List of Build Project Names in CodeBuild](view-project-list.md) + [View a Build Project's Details in CodeBuild](view-project-details.md) + [Build Caching in CodeBuild](build-caching.md) From 81292cd27098ce50c50b371b978fb8931c87dd41 Mon Sep 17 00:00:00 2001 From: Michael Anckaert Date: Wed, 13 Nov 2019 12:54:58 +0100 Subject: [PATCH 014/156] Fixed typo in build-spec-ref --- doc_source/build-spec-ref.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 9c8f504..1d59c9c 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -147,7 +147,7 @@ The value in the build spec declaration takes lowest precedence\. `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\. - + `verstion-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-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*\. @@ -445,4 +445,4 @@ The following table lists the build spec versions and the changes between versio | 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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From d773959869a959410b83c874ebbcbd14c010ad26 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Tue, 19 Nov 2019 19:27:26 +0000 Subject: [PATCH 015/156] Periodic update, Nov 19, 2019. Includes documentation for newly supported 2xlarge container type, and newly supported Arm and Linux GPU environment types. --- doc_source/build-caching.md | 9 ++- doc_source/build-env-ref-available.md | 4 + doc_source/build-env-ref-compute-types.md | 28 +++++-- doc_source/build-spec-ref.md | 2 +- doc_source/change-project.md | 20 +++-- doc_source/create-project.md | 32 ++++---- doc_source/history.md | 5 +- doc_source/notification-rule-create.md | 80 +++++++++++++++++++ doc_source/sample-build-badges.md | 6 +- doc_source/sample-build-notifications.md | 2 +- doc_source/sample-codedeploy.md | 2 +- .../sample-disable-artifact-encryption.md | 6 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-github-enterprise.md | 17 ++-- doc_source/sample-github-pull-request.md | 8 +- doc_source/sample-lambda.md | 2 +- 19 files changed, 171 insertions(+), 64 deletions(-) create mode 100644 doc_source/notification-rule-create.md diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index e2c9950..67825a1 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -21,12 +21,15 @@ Docker layer cache mode is available for the Linux environment only\. If you cho **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 should consider the security implications before you use a Docker layer cache\. + 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 are overriden if a source item has the same name\. Directories are specified using cache paths in the buildspec file\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. +**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)\. + **Topics** + [Specify Local Caching \(CLI\)](#caching-local-cli) + [Specify Local Caching \(Console\)](#caching-local-console) @@ -57,7 +60,7 @@ For more information, see [Create a Build Project \(AWS CLI\)](create-project.md ### Specify Local Caching \(Console\) -You specify a cache in the **Artifacts** section of the console\. For ** Cache type**, choose **Amazon S3** or **Local**\. If you choose **Local**, choose one or more of the three local cache options\. The following shows how to choose a local cache\. +You specify a cache in the **Artifacts** section of the console\. For **Cache type**, choose **Amazon S3** or **Local**\. If you choose **Local**, choose one or more of the three local cache options\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) @@ -65,7 +68,7 @@ For more information, see [Create a Build Project \(Console\)](create-project.md ### Specify Local Caching \(AWS CloudFormation\) - If you use AWS CloudFormation to specify a local cache, on the `Cache` property, for `Type`, you 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: diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 21e8715..9d3f11f 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -8,6 +8,7 @@ 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:1\.0 | [al2/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/1.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.00 ) | | 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:1\.0 | N/A | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | @@ -28,6 +29,9 @@ AWS CodeBuild manages the following Docker images that are available in the Code | python | 3\.7 | python: 3\.7 | | ruby | 2\.6 | ruby: 2\.6 | +**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\. diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index 8b2de41..bbc92d3 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -3,13 +3,31 @@ 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 | Operating system | +| Compute type | computeType value | Memory | vCPUs | Disk space | Environment type | | --- | --- | --- | --- | --- | --- | -| build\.general1\.small | BUILD\_GENERAL1\_SMALL | 3 GB | 2 | 64 GB | Linux | -| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | Linux, Windows | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | Linux, Windows | +| 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 | + +**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\), EU \(Ireland\), EU \(London\), EU \(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\), EU \(Ireland\), Asia Pacific \(Mumbai\), Asia Pacific \(Tokyo\), Asia Pacific \(Sydney\), and EU \(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\), EU \(Stockholm\), EU \(Ireland\), EU \(London\), EU \(Paris\), EU \(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\. + + +**Operating system: Windows** + +| Compute type | computeType value | Memory | vCPUs | Disk space | Environment type | +| --- | --- | --- | --- | --- | --- | +| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | WINDOWS\_CONTAINER | +| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | WINDOWS\_CONTAINER | **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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 1d59c9c..7f22b24 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -445,4 +445,4 @@ The following table lists the build spec versions and the changes between versio | 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/change-project.md b/doc_source/change-project.md index 2beb814..ec93a7a 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -58,8 +58,8 @@ When you use the console to create or update a build project, you can create a C 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 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 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 automatically\. However, if you chose **Existing service role**, you must include this action to your service role separately\. +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`\. @@ -69,12 +69,12 @@ 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 build spec declaration takes lowest precedence\. - If you use Secrets Manager, then 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, 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 automatically\. 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, 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. +If you choose **New service role**, the created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. 1. To change information about tags for this build project, in **Additional configuration**, for **Tags**, change the values of **Name** and **Value**\. Use **Add row** to add a tag\. You can add up to 50 tags\. Choose the delete \(**X**\) icon next to a tag you no longer want to use\. @@ -92,23 +92,21 @@ If you choose **New service role** the created service role includes permission **Important** If you leave **Encryption key** blank, CodeBuild uses the AWS\-managed CMK for Amazon S3 in your AWS account instead\. -1. To change information about the cache, expand **Additional configuration**\. In **Cache type**, do one of the following: +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 build spec file, see [Build Spec 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 Amazon 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\. + + \(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**\. - 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 build spec file, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. - 1. To change your log settings, in **Logs**, select or clear **CloudWatch logs** and **S3 logs**\. - If you enable **CloudWatch 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 enable **S3 logs**: + 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\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 9b6f6a0..f2ea65d 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -52,9 +52,9 @@ CodeBuild does not support Bitbucket Server\. 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) + + 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/) \(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\. @@ -97,8 +97,8 @@ IMAGE\_TAG 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 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 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 automatically\. However, if you chose **Existing service role**, you must include this action to your service role separately\. +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`\. @@ -111,9 +111,9 @@ The value in the build spec declaration takes lowest precedence\. If you use Secrets Manager, then 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 automatically\. 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, 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. +If you choose **New service role**, the created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. 1. In **Buildspec**: @@ -157,9 +157,9 @@ If you choose **New service role** the created service role includes permission + \(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\. +**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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build Caching in CodeBuild](build-caching.md)\. @@ -388,7 +388,7 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + *cache\-location*: Required value only if you set *CacheType* to `S3`\. If you specified Amazon S3 for *CacheType*, this is the ARN of the Amazon S3 bucket and the path prefix\. For example, if your Amazon 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 value 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** -`LOCAL_DOCKER_LAYER_CACHE` mode is available for Linux only\. If you choose it, your project must run in privileged mode\. +**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 value\. Valid values are `ENABLED` or `DISABLED`\. If its value is `ENABLED` then 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)\. + *group\-name*: The name of the CloudWatch Logs group\. @@ -435,9 +435,9 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re If you are using a region other than `us-east-1`, be sure to use it when you run the command\. + For the required `environment` object, information about this project's build environment settings\. These settings include: - + *environment\-type*: Required value\. The type of build environment\. Valid values are `LINUX_CONTAINER` and `WINDOWS_CONTAINER`\. + + *environment\-type*: Required value\. The type of build environment\. Valid values are `ARM_CONTAINER`, `LINUX_CONTAINER`, `LINUX_GPU_CONTAINER`, and `WINDOWS_CONTAINER`\. + *image*: Required value\. 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:2.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 value\. A category corresponding to the number of CPU cores and memory used by this build environment\. Allowed values include `BUILD_GENERAL1_SMALL`, `BUILD_GENERAL1_MEDIUM`, and `BUILD_GENERAL1_LARGE`\. + + *computeType*: Required value\. A category corresponding 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, and BUILD_GENERAL1_2XLARGE`\. `BUILD_GENERAL1_2XLARGE` is only supported with the `LINUX_CONTAINER` environment type\. + *certificate*: Optional value\. 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 Amazon 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*\. @@ -447,8 +447,8 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re 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** -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 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 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 automatically\. However, if you chose **Existing service role**, you must include this action to your service role separately\. +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`\. @@ -461,9 +461,9 @@ The value in the build spec 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** 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 automatically\. 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, 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. +If you choose **New service role**, the created 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`\. diff --git a/doc_source/history.md b/doc_source/history.md index 34fca3a..d8266ab 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,12 +2,13 @@ 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: **November 6, 2019 ++ **Latest documentation update: **November 19, 2019 | Change | Description | Date | | --- |--- |--- | +| [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-specc) and [Secrets Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#secrets-manager-build-spec) in [Build Spec 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-acb.html)\. | November 5, 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 [Build Spec 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 | diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md new file mode 100644 index 0000000..2435acc --- /dev/null +++ b/doc_source/notification-rule-create.md @@ -0,0 +1,80 @@ +# Create a Notification Rule + +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\) + +1. Sign in to the AWS Management Console and open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. Choose **Build**, choose **Build projects**, and then choose a build project where you want to add notifications\. + +1. On the build project page, choose **Notify**, and then choose **Create notification rule**\. You can also go to the **Settings** page for the build project and choose **Create notification rule**\. + +1. In **Notification name**, enter a name for the rule\. + +1. In **Detail type**, choose **Basic** if you want only the information provided to Amazon EventBridge included in the notification\. Choose **Full** if you want to include information provided to Amazon EventBridge and information that might be supplied by the CodeBuild or the notification manager\. + + For more information, see [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. + +1. In **Events that trigger notifications**, select the events for which you want to send notifications\. +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/notification-rule-create.html) + +1. In **Targets**, choose **Create SNS topic**\. +**Note** +When you create the topic, the policy that allows CodeBuild to publish events to the topic is applied for you\. Using a topic created specifically for CodeBuild notifications also helps ensure that you only add users to the subscription list for that topic that you want to see notifications about this build project\. + + After the **codestar\-notifications\-** prefix,enter a name for the topic, and then choose **Submit**\. +**Note** +If you want to use an existing Amazon SNS topic instead of creating a new one, in **Targets**, choose its ARN\. Make sure the topic has the appropriate access policy and that the subscriber list contains only those users who are allowed to see information about the build project\. For more information, see [Configure Existing Amazon SNS Topics for Notifications](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/set-up-sns.html) and [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. + +1. To finish creating the rule, choose **Submit**\. + +1. You must subscribe users to the Amazon SNS topic for the rule before they can receive notifications\. For more information, see [Subscribe Users to Amazon SNS Topics That Are Targets](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/subscribe-users-sns.html)\. You can also set up integration between notifications and AWS Chatbot to send notifications to Amazon Chime chatrooms or Slack channels\. For more information, see [Configure Integration Between Notifications and AWS Chatbot](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/notifications-chatbot.html)\. + +# To create a notification rule \(AWS CLI\) + +1. At a terminal or command prompt, run the create\-notification rule command to generate the JSON skeleton: + + ``` + aws codestarnotifications create-notification-rule --generate-cli-skeleton > rule.json + ``` + + You can name the file anything you want\. In this example, the file is named *rule\.json*\. + +1. Open the JSON file in a plain\-text editor and edit it to include the resource, event types, and Amazon SNS target you want for the rule\. The following example shows a notification rule named **MyNotificationRule** for a build project named *MyBuildProject* in an AWS acccount with the ID *123456789012*\. Notifications are sent with the full detail type to an Amazon SNS topic named *codestar\-notifications\-MyNotificationTopic* when builds are successful: + + ``` + { + "Name": "MyNotificationRule", + "EventTypeIds": [ + "codebuild-project-build-state-succeeded" + ], + "Resource": "arn:aws:codebuild:us-east-2:123456789012:MyBuildProject", + "Targets": [ + { + "TargetType": "SNS", + "TargetAddress": "arn:aws:sns:us-east-2:123456789012:codestar-notifications-MyNotificationTopic" + } + ], + "Status": "ENABLED", + "DetailType": "FULL" + } + ``` + + Save the file\. + +1. Using the file you just edited, at the terminal or command line, run the create\-notification\-rule command again to create the notification rule: + + ``` + aws codestarnotifications create-notification-rule --cli-input-json file://rule.json + ``` + +1. If successful, the command returns the ARN of the notification rule, similar to the following: + + ``` + { + "Arn": "arn:aws:codestar-notifications:us-east-1:123456789012:notificationrule/dc82df7a-EXAMPLE" + } + ``` \ No newline at end of file diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 044de22..1120ab9 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -21,9 +21,9 @@ Updating your project source might affect the accuracy of the project's build ba 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) + + 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/) 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\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 6663743..61205b8 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 56f39d7..c0f0d9a 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index f21027d..4b9db5b 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -18,9 +18,9 @@ 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) + + 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/) 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\. diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 317f91d..18aed24 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w26aac11c41c32c17) ++ [Related Resources](#w28aac11c41c32c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 642d8cb..fa25c97 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w26aac11c41c17c23) ++ [Related Resources](#w28aac11c41c17c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index b168db1..a591531 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 3d9db5a..7b45b11 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 0515177..a8cfc2e 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -65,9 +65,9 @@ We recommend that you use **Enable insecure SSL** for testing only\. It should n 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) + + 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/) 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\. @@ -99,15 +99,18 @@ When you use the console to create or update a build project, you can create a C + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. -1. Expand **Additional configuration**\. In **Cache type**, do one of the following: +1. For **Cache type**, choose one of the following: + If you do not want to use a cache, choose **No cache**\. - + To use a cache, choose **Amazon S3**, and then do the following: - + For **Cache bucket**, choose the name of the Amazon S3 bucket where the cache is stored\. + + If you want to use an Amazon S3 cache, choose **Amazon S3**, and then do the following: + + For **Bucket**, choose the name of the Amazon 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\. 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\. + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build Caching in CodeBuild](build-caching.md)\. 1. Choose **Create build project**\. On the build project page, choose **Start build**\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 48eaf31..5c156c8 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -30,9 +30,9 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 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**, and **Runtime version**\. - + To use another Docker image, choose **Custom image**\. For **Environment type**, choose **Linux** or **Windows**\. For **Custom image type**, choose **Amazon ECR** or **Other location**\. If you choose **Other location**, 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 **Linux** or **Windows**\. For **Custom image type**, choose **Other location**, 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/) + + 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/) 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\. @@ -90,7 +90,7 @@ Filter groups work the same way in GitHub and GitHub Enterprise\. + `ACTOR_ACCOUNT_ID` \(`ACTOR_ID` in the console\): A webhook event triggers a build when a GitHub or GitHub Enterprise 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 and GitHub Enterprise push events only\. + + `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 and GitHub Enterprise push events only\. **Note** You can find the webhook payload in the webhook settings of your GitHub repository\. diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index 8602f79..c1b60f5 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file From 812636b15119792da3b1c13a1a89a9eb8c14429b Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Tue, 26 Nov 2019 18:06:02 +0000 Subject: [PATCH 016/156] Periodic update, Nov 26, 2019, that documents the new test reporting functionality. --- ...ntrol-iam-access-control-identity-based.md | 4 +- ...ntrol-iam-identity-based-access-control.md | 198 ++++++++++++- ...nd-access-control-permissions-reference.md | 12 +- doc_source/build-env-ref-available.md | 2 +- doc_source/build-spec-ref.md | 44 ++- doc_source/change-project.md | 2 + doc_source/create-project.md | 4 + doc_source/history.md | 5 +- doc_source/index.md | 16 ++ doc_source/limits.md | 14 +- doc_source/report-create.md | 24 ++ doc_source/report-group-create.md | 14 + doc_source/report-group-export-settings.md | 37 +++ doc_source/report-group-test-case-commands.md | 17 ++ doc_source/report-group-test-cases.md | 24 ++ doc_source/sample-build-notifications.md | 2 +- doc_source/sample-codedeploy.md | 2 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-lambda.md | 2 +- doc_source/sample-test-report-cli.md | 260 ++++++++++++++++++ doc_source/samples.md | 1 + doc_source/security-encryption.md | 2 +- doc_source/test-permissions.md | 121 ++++++++ .../test-report-group-create-buildspec.md | 28 ++ doc_source/test-report-group-create-cfn.md | 42 +++ doc_source/test-report-group-create-cli.md | 49 ++++ .../test-report-group-create-console.md | 35 +++ doc_source/test-report-group-naming.md | 19 ++ doc_source/test-report-group.md | 19 ++ doc_source/test-report.md | 29 ++ doc_source/test-reporting.md | 21 ++ doc_source/test-view-reports.md | 70 +++++ doc_source/use-case-based-samples.md | 1 + 36 files changed, 1104 insertions(+), 28 deletions(-) create mode 100644 doc_source/report-create.md create mode 100644 doc_source/report-group-create.md create mode 100644 doc_source/report-group-export-settings.md create mode 100644 doc_source/report-group-test-case-commands.md create mode 100644 doc_source/report-group-test-cases.md create mode 100644 doc_source/sample-test-report-cli.md create mode 100644 doc_source/test-permissions.md create mode 100644 doc_source/test-report-group-create-buildspec.md create mode 100644 doc_source/test-report-group-create-cfn.md create mode 100644 doc_source/test-report-group-create-cli.md create mode 100644 doc_source/test-report-group-create-console.md create mode 100644 doc_source/test-report-group-naming.md create mode 100644 doc_source/test-report-group.md create mode 100644 doc_source/test-report.md create mode 100644 doc_source/test-reporting.md create mode 100644 doc_source/test-view-reports.md 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 fbbc6a0..b426f7c 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 @@ -22,8 +22,10 @@ In AWS CodeBuild, the primary resource is a build project\. In a policy, you use | --- | --- | | Build project | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | Build | `arn:aws:codebuild:region-ID:account-ID:build/build-ID` | +| Report group | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | +| Report | arn:aws:codebuild:region\-ID:account\-ID:report/report\-ID | | All CodeBuild resources | `arn:aws:codebuild:*` | -| All CodeBuild resources owned by the specified account in the specified region | `arn:aws:codebuild:region-ID:account-ID:*` | +| All CodeBuild resources owned by the specified account in the specified AWS Region | `arn:aws:codebuild:region-ID:account-ID:*` | **Note** Most AWS services treat a colon \(:\) or a forward slash \(/\) as the same character in ARNs\. However, CodeBuild uses an exact match in resource patterns and rules\. Be sure to use the correct characters when you create event patterns so that they match the ARN syntax in the resource\. 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 54e802b..44bff02 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 @@ -198,14 +198,24 @@ You can use the following sample IAM policies to limit CodeBuild access for your **Topics** + [Allow a User to Get Information About Build Projects](#customer-managed-policies-example-batch-get-projects) ++ [Allow a User to Get Information About Report Groups](#customer-managed-policies-get-information-about-report-group) ++ [Allow a User to Get Information About Reports](#customer-managed-policies-get-information-about-reports) + [Allow a User to Create Build Projects](#customer-managed-policies-example-create-project) ++ [Allow a User to Create a Report Group](#customer-managed-policies-example-create-report-group) ++ [Allow a User to Delete a Report Group](#customer-managed-policies-example-delete-report-group) ++ [Allow a User to Delete a Report](#customer-managed-policies-example-delete-report) + [Allow a User to Delete Build Projects](#customer-managed-policies-example-delete-project) + [Allow a User to Get a List of Build Project Names](#customer-managed-policies-example-list-projects) + [Allow a User to Change Information About Build Projects](#customer-managed-policies-example-update-project) ++ [Allow a User to Change a Report Group](#customer-managed-policies-example-change-report-group) + [Allow a User to Get Information About Builds](#customer-managed-policies-example-batch-get-builds) + [Allow a User to Get a List of Build IDs for a Build Project](#customer-managed-policies-example-list-builds-for-project) + [Allow a User to Get a List of Build IDs](#customer-managed-policies-example-list-builds) -+ [Allow a User to Begin Running Builds](#customer-managed-policies-example-start-build) ++ [Allow a User to Get a List of Report Groups](#customer-managed-policies-example-get-list-of-report-groups) ++ [Allow a User to Get a List of Reports](#customer-managed-policies-example-get-list-of-reports) ++ [Allow a User to Get a List of Reports for a Report Group](#customer-managed-policies-example-get-list-of-reports-for-report-group) ++ [Allow a User to Get a List of Test Cases for a Report](#customer-managed-policies-example-get-list-of-test-cases-for-report) ++ [Allow a User to Start Running Builds](#customer-managed-policies-example-start-build) + [Allow a User to Attempt to Stop Builds](#customer-managed-policies-example-stop-build) + [Allow a User to Attempt to Delete Builds](#customer-managed-policies-example-delete-builds) + [Allow a User to Get Information About Docker Images That Are Managed by CodeBuild](#customer-managed-policies-example-list-curated-environment-images) @@ -214,7 +224,7 @@ You can use the following sample IAM policies to limit CodeBuild access for your ### Allow a User to Get Information About Build Projects -The following example policy statement allows a user to get information about build projects only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: +The following example policy statement allows a user to get information about build projects in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: ``` { @@ -229,9 +239,43 @@ The following example policy statement allows a user to get information about bu } ``` +### Allow a User to Get Information About Report Groups + +The following example policy statement allows a user to get information about report groups in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:BatchGetReportGroups", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + +### Allow a User to Get Information About Reports + +The following example policy statement allows a user to get information about reports in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:BatchGetReports", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + ### Allow a User to Create Build Projects -The following example policy statement allows a user to create build projects with any name but only in the `us-east-2` region for account `123456789012` and using only the specified CodeBuild service role: +The following example policy statement allows a user to create build projects with any name but only in the `us-east-2` Region for account `123456789012` and only using the specified CodeBuild service role: ``` { @@ -251,9 +295,60 @@ The following example policy statement allows a user to create build projects wi } ``` +### Allow a User to Create a Report Group + +The following example policy statement allows a user to create a report group in the `us-east-2`Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:CreateReportGroup", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + +### Allow a User to Delete a Report Group + +The following example policy statement allows a user to delete a report group in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:DeleteReportGroup", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + +### Allow a User to Delete a Report + +The following example policy statement allows a user to delete a report in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:DeleteReport", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + ### Allow a User to Delete Build Projects -The following example policy statement allows a user to delete build projects only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: +The following example policy statement allows a user to delete build projects in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: ``` { @@ -287,7 +382,7 @@ The following example policy statement allows a user to get a list of build proj ### Allow a User to Change Information About Build Projects -The following example policy statement allows a user to change information about build projects with any name but only in the `us-east-2` region for account `123456789012` and using only the specified AWS CodeBuild service role: +The following example policy statement allows a user to change information about build projects with any name but only in the `us-east-2` Region for account `123456789012` and only using the specified AWS CodeBuild service role: ``` { @@ -307,9 +402,26 @@ The following example policy statement allows a user to change information about } ``` +### Allow a User to Change a Report Group + +The following example policy statement allows a user to change a report group in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:UpdateReportGroup", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + ### Allow a User to Get Information About Builds -The following example policy statement allows a user to get information about builds only in the `us-east-2` region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: +The following example policy statement allows a user to get information about builds in the `us-east-2` Region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: ``` { @@ -329,7 +441,7 @@ The following example policy statement allows a user to get information about bu ### Allow a User to Get a List of Build IDs for a Build Project -The following example policy statement allows a user to get a list of build IDs only in the `us-east-2` region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: +The following example policy statement allows a user to get a list of build IDs in the `us-east-2` Region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: ``` { @@ -364,9 +476,77 @@ The following example policy statement allows a user to get a list of all build } ``` -### Allow a User to Begin Running Builds +### Allow a User to Get a List of Report Groups + +The following example policy statement allows a user to get a list of report groups in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:ListReportGroups", + "Resource": "*" + } + ] +} +``` + +### Allow a User to Get a List of Reports + +The following example policy statement allows a user to get a list of reports in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:ListReports", + "Resource": "*" + } + ] +} +``` + +### Allow a User to Get a List of Reports for a Report Group + +The following example policy statement allows a user to get a list of reports for a report group in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:ListReportsForReportGroup", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + +### Allow a User to Get a List of Test Cases for a Report + +The following example policy statement allows a user to get a list of test cases for a report in the `us-east-2` Region for account `123456789012`: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "codebuild:DescribeTestCases", + "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" + } + ] +} +``` + +### Allow a User to Start Running Builds -The following example policy statement allows a user to run builds only in the `us-east-2` region for account `123456789012` for build project that starts with the name `my`: +The following example policy statement allows a user to run builds in the `us-east-2` Region for account `123456789012` for a build project that starts with the name `my`: ``` { diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index ea18725..2dbe4e5 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -24,19 +24,29 @@ If you see an expand arrow \(**↗**\) in the upper\-right corner of the table, | BatchDeleteBuilds | `codebuild:BatchDeleteBuilds` Required to delete builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | BatchGetBuilds | `codebuild:BatchGetBuilds` Required to get information about builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | BatchGetProjects | `codebuild:BatchGetProjects` Required to get information about build projects\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | +| BatchGetReportGroups | codebuild:BatchGetReportGroupsRequired to get information about report groups\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | +| BatchGetReports | codebuild:BatchGetReportsRequired to get information about reports\. | `arn:aws:codebuild:region-ID:account-ID:report-group/report-name` | | CreateProject | `codebuild:CreateProject` `iam:PassRole` Required to create build projects\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` `arn:aws:iam:account-ID:role/role-name` | +| CreateReportGroup | codebuild:CreateReportGroupRequired to create a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | | CreateWebhook | `codebuild:CreateWebhook` Required to create a webhook\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | DeleteProject | `codebuild:DeleteProject` Required to delete build projects\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | +| DeleteReport | codebuild:DeleteReportRequired to delete a report\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | +| DeleteReportGroup | codebuild:DeleteReportGroupRequired to delete a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | | DeleteSourceCredentials | `codebuild:DeleteSourceCredentials` Required to delete a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | | DeleteWebhook | `codebuild:DeleteWebhook` Required to delete a webhook\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | +| DescribeTestCases | codebuild:DescribeTestCasesRequired to return a paginated list of test cases\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | | ImportSourceCredentials | `codebuild:ImportSourceCredentials` Required to import a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | | InvalidateProjectCache | `codebuild:InvalidateProjectCache` Required to reset the cache for a project\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | ListBuilds | codebuild:ListBuildsRequired to get a list of build IDs\. | `*` | | ListBuildsForProject | `codebuild:ListBuildsForProject` Required to get a list of build IDs for a build project\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | ListCuratedEnvironmentImages | `codebuild:ListCuratedEnvironmentImages` Required to get information about all Docker images that are managed by CodeBuild\. | `*` \(required, but does not refer to an addressable AWS resource\) | -| ListSourceCredentials | `codebuild:ListSourceCredentials` Required to get a list of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | | ListProjects | `codebuild:ListProjects` Required to get a list of build project names\. | `*` | +| ListReportGroups | codebuild:ListReportGroupsRequired to get a list of report groups\. | \* | +| ListReports | codebuild:ListReportsRequired to get a list of reports\. | \* | +| ListReportsForReportGroup | codebuild:ListReportsForReportGroupRequired to get a list of reports for a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | +| ListSourceCredentials | `codebuild:ListSourceCredentials` Required to get a list of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | | StartBuild | `codebuild:StartBuild` Required to start running builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | StopBuild | `codebuild:StopBuild` Required to attempt to stop running builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | UpdateProject | `codebuild:UpdateProject` `iam:PassRole` Required to change information about builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` `arn:aws:iam:account-ID:role/role-name` | +| UpdateReportGroup | codebuild:UpdateReportGroupRequired to update a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | | UpdateWebhook | `codebuild:UpdateWebhook` Required to update a webhook\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | \ No newline at end of file diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 9d3f11f..df8ed5a 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -8,7 +8,7 @@ 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:1\.0 | [al2/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/1.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.00 ) | +| 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) | | 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:1\.0 | N/A | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 7f22b24..2fec30a 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -91,7 +91,15 @@ phases: finally: - command - command -artifacts: + reports: + report-name-or-arn: + files: + - location + - location + base-directory: location + discard-paths: yes + file-format: JunitXml | CucumberJson + artifacts: files: - location - location @@ -198,6 +206,16 @@ In build spec version 0\.1, CodeBuild runs each command in a separate instance o **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)\. + `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\. ++ `report-name-or-arn`: Optional sequence\. Represents information about where you want the files with your test results\. A project can have a maximum of five report groups\. Specify a name for a new report group or the ARN of an existing report group\. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format project\-name\-report\-group\-name\-in\-buildspec\. For more information, see [Report Group Naming](test-report-group-naming.md)\. + + `files`: Required sequence\. Represents the locations that contain the raw data of test results generated by the report\. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find test files, relative to the original build location or, if set, the `base-directory`\. Locations can include the following: + + A single file \(for example, `my-test-report-file.json`\)\. + + A single file in a subdirectory \(for example, `my-subdirectory/my-test-report-file.json` or `my-parent-subdirectory/my-subdirectory/my-test-report-file.json`\)\. + + `'**/*'` represents all files recursively\. + + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. + + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + + `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\. + + `discard-paths`: Optional mapping\. Represents whether paths to test result files updloaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TesResult.xml`\. + + `file-format`: Optional mapping\. Represents the test file format\. Valid values are `JunitXml` for JUnit XML and `CumberJson` for Cucubmer JSON\. If not specified, `JunitXml` is used\. + `artifacts`: Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the Amazon 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\. + `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`\)\. @@ -363,6 +381,11 @@ You can use the CodeBuild or CodePipeline consoles instead of a buildspec\.yml f ## Build Spec Example + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + Here is an example of a buildspec\.yml file\. ``` @@ -399,7 +422,19 @@ phases: commands: - echo Entered the post_build phase... - echo Build completed on `date` -artifacts: + +reports: + arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: + files: + - "**/*" + base-directory: 'target/tests/reports' + discard-paths: no + reportGroupCucumberJson: + files: + - 'cucumber/target/cucumber-tests.xml' + discard-paths: yes + file-format: CucumberJson # default is JunitXml + artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes @@ -420,7 +455,7 @@ cache: Here is an example of the preceding build spec, 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\nphases:\n install:\n commands:\n - apt-get update -y\n - apt-get install -y maven\n pre_build:\n commands:\n - echo Entered the pre_build phase...\n build:\n commands:\n - echo Build started on `date`\n - mvn install\n post_build:\n commands:\n - echo Build completed on `date`\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes" +"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\. @@ -434,6 +469,9 @@ In these examples: + A custom environment variable named `dockerLoginPassword` you stored in Amazon EC2 Systems Manager Parameter Store is referenced later in build commands by using the key `LOGIN_PASSWORD`\. + You cannot change these build phase names\. The commands that are run in this example are `apt-get update -y` and `apt-get install -y maven` \(to install Apache Maven\), `mvn install` \(to compile, test, and package the source code into a build output artifact and to install the build output artifact in its internal repository\), `docker login` \(to sign in to Docker with the password that corresponds to the value of the custom environment variable `dockerLoginPassword` you set in Amazon EC2 Systems Manager Parameter Store\), and several `echo` commands\. The `echo` commands are included here to show how CodeBuild runs commands and the order in which it runs them\. + `files` represents the files to upload to the build output location\. In this example, CodeBuild uploads the single file `messageUtil-1.0.jar`\. The `messageUtil-1.0.jar` file can be found in the relative directory named `target` in the build environment\. Because `discard-paths: yes` is specified, `messageUtil-1.0.jar` is uploaded directly \(and not to an intermediate `target` directory\)\. The file name `messageUtil-1.0.jar` and the relative directory name of `target` is based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own scenarios, these file names and directories will be different\. ++ `reports` represents two report groups that generate reports during the build: + + `arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1` specifies the ARN of a report group\. Test results generated by the test framework are in the `target/tests/reports` directory\. The file format is `JunitXml` and the path is not removed from the files that contain test results\. + + `reportGroupCucumberJson` specifies a new report group\. If the name of the project is `my-project`, a report group with the name `my-project-reportGroupCucumberJson` is created when a build is run\.\. Test results generated by the test framework are in `cucumber/target/cucumber-tests.xml`\. The test file format is `CucumberJson` and the path is removed from the files that contain test results\. ## Build Spec Versions diff --git a/doc_source/change-project.md b/doc_source/change-project.md index ec93a7a..9d81928 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -2,6 +2,8 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to change a build project's settings\. +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) diff --git a/doc_source/create-project.md b/doc_source/create-project.md index f2ea65d..2b9c32f 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -25,6 +25,8 @@ Answer the questions in [Plan a Build](planning.md)\. 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\. + In **Description**, enter an optional description for your project\. + 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\. @@ -388,6 +390,8 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + *cache\-location*: Required value only if you set *CacheType* to `S3`\. If you specified Amazon S3 for *CacheType*, this is the ARN of the Amazon S3 bucket and the path prefix\. For example, if your Amazon 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 value 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** +`LOCAL_DOCKER_LAYER_CACHE` mode is available for Linux only\. If you choose it, your project must run in privileged mode\. +**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 value\. Valid values are `ENABLED` or `DISABLED`\. If its value is `ENABLED` then 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)\. diff --git a/doc_source/history.md b/doc_source/history.md index d8266ab..08da3cd 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,12 +2,13 @@ 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: **November 19, 2019 ++ **Latest documentation update: **November 25, 2019 | Change | Description | Date | | --- |--- |--- | +| [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-specc) and [Secrets Manager](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#secrets-manager-build-spec) in [Build Spec Syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | November 6, 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 [Build Spec 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 [Build Spec 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 | diff --git a/doc_source/index.md b/doc_source/index.md index 52ae0bb..37dc040 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -24,6 +24,7 @@ Amazon's trademarks and trade dress may not be used in + [Amazon ECR Sample for CodeBuild](sample-ecr.md) + [Runtime Versions in Buildspec File Sample for CodeBuild](sample-runtime-versions.md) + [Private Registry with AWS Secrets Manager Sample for CodeBuild](sample-private-registry.md) + + [Create a Test Report in CodeBuild Using the AWS CLI Sample](sample-test-report-cli.md) + [Docker Sample for CodeBuild](sample-docker.md) + [GitHub Enterprise Sample for CodeBuild](sample-github-enterprise.md) + [GitHub Pull Request and Webhook Filter Sample for CodeBuild](sample-github-pull-request.md) @@ -75,6 +76,21 @@ Amazon's trademarks and trade dress may not be used in + [View a List of Build IDs for a Build Project in CodeBuild](view-builds-for-project.md) + [Stop a Build in CodeBuild](stop-build.md) + [Delete Builds in CodeBuild](delete-builds.md) ++ [Working with Test Reporting in CodeBuild](test-reporting.md) + + [Create a Test Report](report-create.md) + + [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 (AWS CloudFormation)](test-report-group-create-cfn.md) + + [Specify Export Settings](report-group-export-settings.md) + + [Specify Test Files](report-group-test-cases.md) + + [Specify Test Commands](report-group-test-case-commands.md) + + [Report Group Naming](test-report-group-naming.md) + + [Working with Reports](test-report.md) + + [Working with Test Report Permissions](test-permissions.md) + + [View Test Reports](test-view-reports.md) + [Security in AWS CodeBuild](security.md) + [Data Protection in AWS CodeBuild](data-protection.md) + [Data Encryption](security-encryption.md) diff --git a/doc_source/limits.md b/doc_source/limits.md index 896ccd8..cabe4cf 100644 --- a/doc_source/limits.md +++ b/doc_source/limits.md @@ -19,6 +19,7 @@ The following tables list the current limits in CodeBuild\. These limits are for | 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 subnets you can add under VPC configuration | 1 to 16 | | Number of security groups you can add under VPC configuration | 1 to 5 | +| Maximum number of reports you can add to a project | 5 | ## Build Limits @@ -32,4 +33,15 @@ The following tables list the current limits in CodeBuild\. These limits are for | Number of minutes you can specify for the build timeout of a single build | 5 to 480 \(8 hours\) | | Maximum time the history of a build can be accessed | 1 year | -\* Limits 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 limit can be between 1 and 5\. To request a higher concurrent build limit or if you get a "Cannot have more than X active builds for the account" error, contact AWS Support\. \ No newline at end of file +\* Limits 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 limit can be between 1 and 5\. To request a higher concurrent build limit or if you get a "Cannot have more than X active builds for the account" error, contact AWS Support\. + +## Report Limits + + +**** + +| Resource | Default limit | +| --- | --- | +| Maximum number of report groups per AWS account | 1000 | +| Maximum duration a test report is available after it is created | 30 days | +| Maximum number of test cases per report | 500 | \ No newline at end of file diff --git a/doc_source/report-create.md b/doc_source/report-create.md new file mode 100644 index 0000000..fa42a0d --- /dev/null +++ b/doc_source/report-create.md @@ -0,0 +1,24 @@ +# Create a Test Report + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + To create a test report, you run a build project that is configured with one to five report groups in its buildspec file\. A test report is created during the run\. It contains the results of the test cases that are specified for the report groups\. 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 CodeBuild](create-project.md)\. + +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. 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)\. + + 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 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 diff --git a/doc_source/report-group-create.md b/doc_source/report-group-create.md new file mode 100644 index 0000000..6b9535b --- /dev/null +++ b/doc_source/report-group-create.md @@ -0,0 +1,14 @@ +# Create a Report Group + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + You can use the CodeBuild console, the AWS CLI, or a buildspec file to create a report group\. Your IAM role must have the permissions required to create a report group\. For more information, see [Working with Test Report Permissions](test-permissions.md)\. + +**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 \(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 new file mode 100644 index 0000000..9421694 --- /dev/null +++ b/doc_source/report-group-export-settings.md @@ -0,0 +1,37 @@ +# Specify Export Settings + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + You can specify information about whether to export the raw test result data to files in an S3 bucket\. If you choose to export to an S3 bucket, specify the following when you create 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\. + +**To update export settings for a report group** + +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 naviagation pane, choose **Report groups**\. + +1. Choose the report group you want to update\. + +1. Choose **Edit**\. + +1. Select or clear **Backup to Amazon S3**\. If you selected this option, specify your export settings: + + 1. For **S3 bucket name**, enter the name of the S3 bucket\. + + 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. 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\.\) + + For more information, see [Data Encryption](security-encryption.md)\. \ No newline at end of file diff --git a/doc_source/report-group-test-case-commands.md b/doc_source/report-group-test-case-commands.md new file mode 100644 index 0000000..feccfb5 --- /dev/null +++ b/doc_source/report-group-test-case-commands.md @@ -0,0 +1,17 @@ +# Specify Test Commands + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + You specify the commands that run your test cases in the `commands` section of your buildspec file\. These commands run the test cases specified for your report groups in the `reports` section of your buildspec file\. The following is a sample `commands` section that includes commands to run the tests in test files: + +``` +commands: + - echo Running tests for surefire junit + - mvn test -f surefire/pom.xml -fn + - echo + - echo Running tests for cucumber with json plugin + - mvn test -Dcucumber.options="--plugin json:target/cucumber-json-report.json" -f cucumber-json/pom.xml -fn +``` \ No newline at end of file diff --git a/doc_source/report-group-test-cases.md b/doc_source/report-group-test-cases.md new file mode 100644 index 0000000..c56ace9 --- /dev/null +++ b/doc_source/report-group-test-cases.md @@ -0,0 +1,24 @@ +# Specify Test Files + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports Syntax in the Buildspec File](build-spec-ref.md#reports-buildspec-file)\. + + The following is a sample `reports` section that specifies two report groups for a build project\. One is specified with its ARN, the other with a name\. The `files` section specifies the files that contain the test case results\. The optional `base-directory` section specifies the directory where the test case files are located\. The optional `discard-paths` section specifies whether paths to test result files uploaded to an S3 bucket are discarded\. + +``` +reports: + arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: #surefire junit reports + files: + - '**/*' + base-directory: 'surefire/target/surefire-reports' + discard-paths: false + + sampleReportGroup: #Cucumber reports from json plugin + files: + - 'cucumber-json/target/cucumber-json-report.json' + file-format: CucumberJson #Type of the report, defaults to JunitXml +``` \ No newline at end of file diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 61205b8..753f882 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index c0f0d9a..540d18f 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 18aed24..5bede52 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w28aac11c41c32c17) ++ [Related Resources](#w39aac11c41c34c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index fa25c97..bc8d941 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w28aac11c41c17c23) ++ [Related Resources](#w39aac11c41c19c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index a591531..cb77181 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 7b45b11..34d8e37 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index c1b60f5..6c252d3 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md new file mode 100644 index 0000000..2bc9a15 --- /dev/null +++ b/doc_source/sample-test-report-cli.md @@ -0,0 +1,260 @@ +# Create a Test Report in CodeBuild Using the AWS CLI Sample + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + Tests that you specify in your buildspec file are run during your build\. This sample shows you how to use the AWS CLI to incorporate tests into builds in CodeBuild\. \. You can use JUnit to create unit tests, or you can use another tool to create configuration tests\. You can then evaluate the test results to fix issues or optimize your application\. + +You can use the CodeBuild API or the AWS CodeBuild console to access the test results\. This sample shows you how to configure your report so its test results are exported to an S3 bucket\. + +**Topics** ++ [Prerequisites](#sample-test-report-cli-prerequisites) ++ [Create a Report Group](#sample-test-report-cli-create-report) ++ [Configure a Project with a Report Group](#sample-test-report-cli-create-project-with-report) ++ [Run and View Results of a Report](#sample-test-report-cli-run-and-view-report-results) + +## Prerequisites ++ 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 format of your test cases can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create test files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and 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*\. ++ Make a note of the ARN of the IAM role you use\. You need the ARN when you create your build project\. ++ If your role does not have the following permissions, add them\. + + ``` + { + "Effect": "Allow", + "Resource": [ + "*" + ], + "Action": [ + "codebuild:CreateReportGroup", + "codebuild:CreateReport", + "codebuild:UpdateReport", + "codebuild:BatchPutTestCases" + ] + } + ``` + + For more information, see [Permissions for Test Reporting Operations](test-permissions.md#test-permissions-related-to-reporting)\. + +## Create a Report Group + +1. Create a file named `CreateReportGroupInput.json`\. + +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\. + + ``` + { + "name": "report-name", + "type": "TEST", + "exportConfig": { + "type": "S3", + "s3": { + "bucket": "bucket-name", + "path": "path-to-folder", + "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`\)\. + + ``` + aws codebuild create-report-group \ + --cli-input-json file://CreateReportGroupInput.json \ + --region your-region + ``` + + The output looks like the following\. Make a note of the report group ARN\. You use it when you create a project that uses this report group\. + + ``` + { + "reportGroup": { + "arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/report-name", + "name": "report-name", + "type": "TEST", + "exportConfig": { + "type": "S3", + "s3": { + "bucket": "s3-bucket-name", + "path": "folder-path", + "packaging": "NONE", + "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" + } + }, + "created": 1570837165.885, + "lastModified": 1570837165.885 + } + } + ``` + +## 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\. + +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\. + + ``` + version: 0.2 + phases: + install: + runtime-versions: + java: openjdk8 + build: + commands: + - echo Running tests + - enter commands to run your tests + + reports: + report-name-or-arn: #test file information + files: + - 'test-result-files' + base-directory: 'optional-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)\. + +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\. + + ``` + {create-project-with-report + "name": "test-report-project", + "description": "sample-test-report-project", + "source": { + "type": "your-repository-type", + "location": "https://github.com/your-repository/your-folder" + }, + "artifacts": { + "type": "NO_ARTIFACTS" + }, + "cache": { + "type": "NO_CACHE" + }, + "environment": { + "type": "LINUX_CONTAINER", + "image": "aws/codebuild/standard:2.0", + "computeType": "small" + }, "serviceRole": "arn:aws:iam::your-aws-account-id:role/service-role/your-role-name" + } + ``` + +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 + ``` + +## 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\. + +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`\. + + ``` + aws codebuild start-build --project-name "test-project" --region your-region + ``` + +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\. + + ``` + aws codebuild batch-get-builds \ + --ids "build-id" \ + --region your-region + ``` + +1. Run the following command to get details about your reports\. For `--report-group-arn`, specify your report ARN\. + + ``` + aws codebuild batch-get-reports \ + --report-arns report-group-arn \ + --region your-region + ``` + + 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\. + + ``` + { + "reports": [ + { + "status": "FAILED", + "reportGroupArn": "report-group-arn", + "name": "report-group-name", + "created": 1573324770.154, + "exportConfig": { + "type": "S3", + "s3": { + "bucket": "your-s3-bucket", + "path": "path-to-your-report-results", + "packaging": "NONE", + "encryptionKey": "encryption-key" + } + }, + "expired": 1575916770.0, + "truncated": false, + "executionId": "arn:aws:codebuild:us-west-2:123456789012:build/name-of-build-project:2c254862-ddf6-4831-a53f-6839a73829c1", + "type": "TEST", + "arn": "report-arn", + "testSummary": { + "durationInNanoSeconds": 6657770, + "total": 11, + "statusCounts": { + "FAILED": 3, + "SKIPPED": 7, + "ERROR": 0, + "SUCCEEDED": 1, + "UNKNOWN": 0 + } + } + } + ], + "reportsNotFound": [] + } + ``` + +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`\)\. + + ``` + aws codebuild describe-test-cases \ + --report-arn report-arn \ + --filter status=SUCCEEDED|FAILED|SKIPPED|ERROR|UNKNOWN \ + --region your-region + ``` + + The output looks like the following\. + + ``` + { + "testCases": [ + { + "status": "FAILED", + "name": "Test case 1", + "expired": 1575916770.0, + "reportArn": "report-arn", + "prefix": "Cucumber tests for agent", + "message": "A test message", + "durationInNanoSeconds": 1540540, + "testRawDataPath": "path-to-output-report-files" + }, + { + "status": "SUCCEEDED", + "name": "Test case 2", + "expired": 1575916770.0, + "reportArn": "report-arn", + "prefix": "Cucumber tests for agent", + "message": "A test message", + "durationInNanoSeconds": 1540540, + "testRawDataPath": "path-to-output-report-files" + } + ] + } + ``` \ No newline at end of file diff --git a/doc_source/samples.md b/doc_source/samples.md index 5165c32..39adb2d 100644 --- a/doc_source/samples.md +++ b/doc_source/samples.md @@ -9,6 +9,7 @@ | --- | --- | | [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\. | | [Private Registry with AWS Secrets Manager Sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment\. The private registry credentials are stored in Secrets Manager\. | +| [Create a Test Report in CodeBuild Using the AWS CLI Sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | | [Docker Sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | | [Amazon EFS Sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | | [GitHub Enterprise Sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 6568e89..6c412f8 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -1,7 +1,7 @@ # 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, 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)\. ++ **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.md#encryptionkey-console) and [Set the Encryption Key Using the CLI](create-project.md#encryptionkey-cli)\. diff --git a/doc_source/test-permissions.md b/doc_source/test-permissions.md new file mode 100644 index 0000000..032a112 --- /dev/null +++ b/doc_source/test-permissions.md @@ -0,0 +1,121 @@ +# Working with Test Report Permissions + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + This topic describes important information about permissions related to test reporting\. + +**Topics** ++ [Create a Role for Test Reports](#test-permissions-required) ++ [Permissions for Test Reporting Operations](#test-permissions-related-to-reporting) ++ [Test Reporting Permissions Examples](#test-permissions-examples) + +## Create a Role for Test Reports + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + 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` + +**Note** + `BatchPutTestCases`, `CreateReport`, and `UpdateReport` 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: + +``` +{ + "Effect": "Allow", + "Resource": [ + "*" + ], + "Action": [ + "codebuild:CreateReportGroup", + "codebuild:CreateReport", + "codebuild:UpdateReport", + "codebuild:BatchPutTestCases" + ] +} +``` + + 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: + +``` +{ + "Effect": "Allow", + "Resource": [ + "arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1", + "arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-2" + ], + "Action": [ + "codebuild:CreateReportGroup", + "codebuild:CreateReport", + "codebuild:UpdateReport", + "codebuild:BatchPutTestCases" + ] +} +``` + + The following restricts permissions to only report groups created by running builds of a project named `my-project`: + +``` +{ + "Effect": "Allow", + "Resource": [ + "arn:aws:codebuild:your-region:your-aws-account-id:report-group/my-project-*" + ], + "Action": [ + "codebuild:CreateReportGroup", + "codebuild:CreateReport", + "codebuild:UpdateReport", + "codebuild:BatchPutTestCases" + ] +} +``` + +## Permissions for Test Reporting Operations + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + You can specify permissions for the following test reporting CodeBuild API operations: ++ `BatchGetReportGroups` ++ `BatchGetReports` ++ `CreateReportGroup` ++ `DeleteReportGroup` ++ `DeleteReport` ++ `DescribeTestCases` ++ `ListReportGroups` ++ `ListReports` ++ `ListReportsForReportGroup` ++ `UpdateReportGroup` + +For more information, see [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. + +## Test Reporting Permissions Examples + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + For information about sample policies related to test reporting, see the following: ++ [Allow a User to Get Information About Report Groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-report-group) ++ [Allow a User to Get Information About Reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-reports) ++ [Allow a User to Create a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-report-group) ++ [Allow a User to Delete a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report-group) ++ [Allow a User to Delete a Report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report) ++ [Allow a User to Get a List of Test Cases for a Report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-test-cases-for-report) ++ [Allow a User to Get a List of Report Groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-report-groups) ++ [Allow a User to Get a List of Reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports) ++ [Allow a User to Get a List of Reports for a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports-for-report-group) ++ [Allow a User to Change a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-change-report-group) \ No newline at end of file diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md new file mode 100644 index 0000000..aace1bd --- /dev/null +++ b/doc_source/test-report-group-create-buildspec.md @@ -0,0 +1,28 @@ +# Create a Report Group \(Buildspec\) + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Specify Export Settings](report-group-export-settings.md)\. + +**To create a report group using a buildspec file** + +1. Choose a report group name that is not associated with a report group in your AWS account\. + +1. Configure the `reports` section of the buildspec file with this name\. In this example, the report group name is `new-report-group` and the use test cases are created with the JUnit framework: + + ``` + reports: + new-report-group: #surefire junit reports + files: + - '**/*' + base-directory: 'surefire/target/surefire-reports' + ``` + + For more information, see [Specify Test Files](report-group-test-cases.md) and [Reports Syntax in the Buildspec File](build-spec-ref.md#reports-buildspec-file)\. + +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 diff --git a/doc_source/test-report-group-create-cfn.md b/doc_source/test-report-group-create-cfn.md new file mode 100644 index 0000000..33e6c4b --- /dev/null +++ b/doc_source/test-report-group-create-cfn.md @@ -0,0 +1,42 @@ +# Create a Report Group \(AWS CloudFormation\) + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + **To create a test report using the AWS CloudFormation template** + + You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide//Welcome.html)\. + + The following AWS CloudFormation YAML template creates a report group that does not export raw test result files\. + +``` +Resources: + CodeBuildReportGroup: + Type: AWS::CodeBuild::ReportGroup + Properties: + Name: my-report-group-name + Type: TEST + ExportConfig: + ExportConfigType: NO_EXPORT +``` + + The following AWS CloudFormation YAML template creates a report group that exports raw test result files to an S3 bucket\. + +``` +Resources: + CodeBuildReportGroup: + Type: AWS::CodeBuild::ReportGroup + Properties: + Name: my-report-group-name + Type: TEST + ExportConfig: + ExportConfigType: S3 + S3Destination: + Bucket: my-s3-bucket-name + Path: path-to-folder-for-exported-files + Packaging: ZIP + EncryptionKey: my-KMS-encryption-key + EncryptionDisabled: false +``` \ No newline at end of file diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md new file mode 100644 index 0000000..b9c4017 --- /dev/null +++ b/doc_source/test-report-group-create-cli.md @@ -0,0 +1,49 @@ +# Create a Report Group \(CLI\) + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +**To create a test report using the AWS CLI** ++ Create a file named `CreateReportGroup.json`\. + +1. Depending on your requirements, copy one of the following JSON code snippets into `CreateReportGroup`: + + Use the following JSON to specify that your test report group exports raw test result files to an S3 bucket\. + + ``` + { + "name": "report-name", + "type": "TEST", + "exportConfig": { + "type": "S3", + "s3": { + "bucket": "bucket-name", + "path": "path", + "packaging": "NONE | ZIP", + "encryptionDisabled": "false", + "encryptionKey": "your-key" + } + } + ``` + + 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 [Specify Export Settings](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", + "exportConfig": { + "type": "NO_EXPORT" + } + } + ``` + +1. Run the following command: + + ``` + aws codebuild create-report-group \ + --cli-input-json file://CreateReportGroupInput.json \ + --region us-east-2 + ``` \ 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 new file mode 100644 index 0000000..f0e9fc2 --- /dev/null +++ b/doc_source/test-report-group-create-console.md @@ -0,0 +1,35 @@ +# Create a Report Group \(Console\) + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +**To create a test report using the AWS CodeBuild 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 **Report groups**\. + +1. Choose **Create report group**\. + +1. For **Report group name**, enter a name for your report group\. + +1. If you want to upload the raw data of your test report results to an S3 bucket: + + 1. Select **Backup to Amazon S3**\. + + 1. For **S3 bucket name**, enter the name of the S3 bucket\. + + 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. 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\.\) + + For more information about encryption of data at\-rest, see [Data Encryption](security-encryption.md)\. + +1. Choose **Create report group**\. \ No newline at end of file diff --git a/doc_source/test-report-group-naming.md b/doc_source/test-report-group-naming.md new file mode 100644 index 0000000..865c62d --- /dev/null +++ b/doc_source/test-report-group-naming.md @@ -0,0 +1,19 @@ +# Report Group Naming + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + When you use the AWS CLI or the AWS CodeBuild console to create a report group, you specify a name for the report group\. If you use the buildspec to create a new report group, it is named using using the format `project-name-report-group-name-specified-in-buildspec`\. All reports created by running builds of that build project belong to the new report group that has the new name\. + + If you do not want CodeBuild to create a new report group, specify the ARN of the report group in a build project's buildspec file\. You can specify a report group's ARN in multiple build projects\. After each build project runs, the report group contains test reports created by each build project\. + + For example, if you create one report group with the name `my-report-group`, and then use its name in two different build projects named `my-project-1` and `my-project-2` and create a build of both projects, two new report groups are created\. The result is three report groups with the following names: ++ `my-report-group`: Does not have any test reports\. ++ `my-project-1-my-report-group`: Contains reports with results of tests run by the build project named `my-project-1`\. ++ `my-project-2-my-report-group`: Contains reports with results of tests run by the build project named `my-project-2`\. + + If you use the ARN of the report group named `my-report-group` in both projects, and then run builds of each project, you still have one report group \(`my-report-group`\)\. That report group contains test reports with results of tests run by both build projects\. + + If you a choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. \ No newline at end of file diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md new file mode 100644 index 0000000..a28b509 --- /dev/null +++ b/doc_source/test-report-group.md @@ -0,0 +1,19 @@ +# Working with Report Groups + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +A *report group* contains test reports and specifies shared settings\. You use the buildspec file to specify the test cases to run and the commands to run them when it builds\. For each report group configured in a build project, a run of the build project creates a test report\. Multiple runs of a build project configured with a report group create multiple test reports in that report group, each with results of the the same test cases specified for that report group\. + + The test cases are specified for a report group in the buildspec file of a build project\. You can specify up to 5 report groups in one build project\. When your run a build, all the test cases run\. A new test report is created with the results of each test case specified for a report group\. Each time you run a new build, the test cases run and a new test report is created with the new test results\. + + Report groups can be used in more than one build project\. All test reports created with one report group share the same configuration, such as its export option and permissions, even if the test reports are created using different build projects\. Test reports created with one report group in multiple build projects can contain the results from running different sets of test cases \(one set of test cases for each build project\)\. This is because you can specify different test case files for the report group in each project's buildspec file\. You can also change the test case files for a report group in a build project by editing its buildspec file\. Subsequent build runs create new test reports that contain the results of the test case files in the updated buildspec\. + +**Topics** ++ [Create a Report Group](report-group-create.md) ++ [Specify Export Settings](report-group-export-settings.md) ++ [Specify Test Files](report-group-test-cases.md) ++ [Specify Test Commands](report-group-test-case-commands.md) ++ [Report Group Naming](test-report-group-naming.md) \ No newline at end of file diff --git a/doc_source/test-report.md b/doc_source/test-report.md new file mode 100644 index 0000000..012423d --- /dev/null +++ b/doc_source/test-report.md @@ -0,0 +1,29 @@ +# Working with Reports + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +A report contains the results of test cases that are specified for one report group\. A test report is created during the run of a build project\. You specify a report group, test case files, and commands to run the test cases in its buildspec file\. Each time the test cases run, a new test report is created in the report group\. + + A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Specify Export Settings](report-group-export-settings.md)\. + +The status of a test report can be one of the following: ++ `GENERATING`: The run of the test cases is still in progress\. ++ `DELETING`: The test report is being deleted\. When a test report is deleted, its test cases are also deleted\. Raw test result data files exported to an S3 bucket are not deleted\. ++ `INCOMPLETE`: The test report was not completed\. This status might be returned for one of the following reasons: + + A problem with the configuration of the report group that specifies this report's test cases\. For example, the path to the test cases under the report group in the buildspec file might be incorrect\. + + The IAM user that ran the build does not have permissions to run tests\. For more information, see [Working with Test Report Permissions](test-permissions.md)\. + + The build was not completed because of an error that is not related to the tests\. ++ `SUCCEEDED`: All test cases were successful\. ++ `FAILED`: Some of the test cases were not successful\. + +Each test case returns a status\. The status for a test case can be one of the following: ++ `SUCCEEDED`: The test case passed\. ++ `FAILED`: The test case failed\. ++ `ERROR`: The test case resulted in an unexpected error\. ++ `SKIPPED`: The test case did not run\. ++ `UNKNOWN`: The test case returned a status other than `SUCCEEDED`, `FAILED`, `ERROR`, or `SKIPPED`\. + +A test report can have a maximum of 500 test case results\. If more than 500 test cases are run, CodeBuild prioritizes tests with the status `FAILED` and truncates the test case results\. \ No newline at end of file diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md new file mode 100644 index 0000000..31cb7c7 --- /dev/null +++ b/doc_source/test-reporting.md @@ -0,0 +1,21 @@ +# Working with Test Reporting in CodeBuild + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +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 test file format can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. + +To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. + +You can use a test report to help troubleshoot a problem during a build run\. If you have many test reports from multiple builds of a build project, you can use your test reports to view trends and test and failure rates to help you optimize builds\. + +A report expires 30 days after it was created\. You cannot view an expired test report\. If you want to keep test reports for more than 30 days, you can export your test results' raw data files to an S3 bucket\. Exported test files do not expire\. Information about the S3 bucket is specified when you create the report group\. + +**Topics** ++ [Create a Test Report](report-create.md) ++ [Working with Report Groups](test-report-group.md) ++ [Working with Reports](test-report.md) ++ [Working with Test Report Permissions](test-permissions.md) ++ [View Test Reports](test-view-reports.md) \ No newline at end of file diff --git a/doc_source/test-view-reports.md b/doc_source/test-view-reports.md new file mode 100644 index 0000000..492fee3 --- /dev/null +++ b/doc_source/test-view-reports.md @@ -0,0 +1,70 @@ +# View Test Reports + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + + You can view details about a test report, such as information about its test cases, pass and fail numbers, and how long it took for it to run\. You can view test reports grouped by build run, report group, or your AWS account\. Choose a test report in the console to see its details and results of its test cases\. + + You can see view test reports that are not expired\. Test reports expire 30 days after they are created\. You cannot view an expired report in CodeBuild\. + +**Topics** ++ [View Test Reports for a Build](#test-view-project-reports) ++ [View Test Reports for a Report Group](#test-view-report-group-reports) ++ [View Test Reports in Your AWS Account](#test-view-account-reports) + +## View Test Reports for a Build + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +**To view test reports for a build** + +1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. + +1. Locate the build you want to view\. If you know the project that ran the build that created the test report: + + 1. In the navigation pane, choose **Build projects**, and then choose the project with the build that ran the test report you want to view\. + + 1. Choose **Build history**, and then choose the build that ran created the reports you want to view\. + + You can also locate the build in the build history for your AWS account: + + 1. In the navigation pane, choose **Build history**, and then choose the build that created the test reports you want to view\. + +1. In the build page, choose **Reports**, and then choose a test report to see its details\. + +## View Test Reports for a Report Group + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +**To view test reports in a report group** + +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. Choose the report group that contains the test reports you want to view\. + +1. Choose a test report to see its details\. + +## View Test Reports in Your AWS Account + + +| | +| --- | +| The test reporting feature is in preview release for CodeBuild and is subject to change\. | + +**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)\. + +1. In the navigation pane, choose **Report history**\. + +1. Choose a test report to see its details\. \ 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 d2bdce9..d0ee0d1 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -9,6 +9,7 @@ You can use these use case\-based samples to experiment with AWS CodeBuild: | --- | --- | | [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\. | | [Private Registry with AWS Secrets Manager Sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment when building with CodeBuild The private registry credentials are stored in AWS Secrets Manager\. | +| [Create a Test Report Using the AWS CLI Sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | | [ Runtime Versions in Buildspec File Sample ](sample-runtime-versions.md) | Shows how to specify runtimes and their versions in the buildspec file\. This is a requirement when using the Ubuntu standard image version 2\.0\. | | [Source Version Sample](sample-source-version.md) | Shows how to use a specific version of your source in a CodeBuild build project\. | | [Docker Sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | From 7481629a62c79a569145a125e7249b61ae5cd32e Mon Sep 17 00:00:00 2001 From: Maksim Aniskov Date: Wed, 27 Nov 2019 13:44:27 +0100 Subject: [PATCH 017/156] Fix indentation of some of 'artifacts:' and 'reports:' Closes #46 --- doc_source/build-spec-ref.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 2fec30a..4ee4ff9 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -91,7 +91,7 @@ phases: finally: - command - command - reports: +reports: report-name-or-arn: files: - location @@ -99,7 +99,7 @@ phases: base-directory: location discard-paths: yes file-format: JunitXml | CucumberJson - artifacts: +artifacts: files: - location - location @@ -434,7 +434,7 @@ reports: - 'cucumber/target/cucumber-tests.xml' discard-paths: yes file-format: CucumberJson # default is JunitXml - artifacts: +artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes From 6d018ea5bd60195c8c9930faffe7d00b622a0249 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anton=20Gr=C3=BCbel?= <33207684+gruebel@users.noreply.github.com> Date: Fri, 29 Nov 2019 16:29:46 +0100 Subject: [PATCH 018/156] Fix typo in build-spec-ref.md --- doc_source/build-spec-ref.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 4ee4ff9..4f088d1 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -215,7 +215,7 @@ Commands in some build phases might not be run if commands in earlier build phas + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + `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\. + `discard-paths`: Optional mapping\. Represents whether paths to test result files updloaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TesResult.xml`\. - + `file-format`: Optional mapping\. Represents the test file format\. Valid values are `JunitXml` for JUnit XML and `CumberJson` for Cucubmer JSON\. If not specified, `JunitXml` is used\. + + `file-format`: Optional mapping\. Represents the test file format\. Valid values are `JunitXml` for JUnit XML and `CucumberJson` for Cucumber JSON\. If not specified, `JunitXml` is used\. + `artifacts`: Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the Amazon 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\. + `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`\)\. @@ -483,4 +483,4 @@ The following table lists the build spec versions and the changes between versio | 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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From dffd861dce658a8d44f8338cc109543a0aed58e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Deividas=20Pek=C5=ABnas?= Date: Tue, 3 Dec 2019 16:47:54 +0200 Subject: [PATCH 019/156] Fix CLI command name --- doc_source/notification-rule-create.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md index 2435acc..cfaec01 100644 --- a/doc_source/notification-rule-create.md +++ b/doc_source/notification-rule-create.md @@ -38,7 +38,7 @@ If you want to use an existing Amazon SNS topic instead of creating a new one, i 1. At a terminal or command prompt, run the create\-notification rule command to generate the JSON skeleton: ``` - aws codestarnotifications create-notification-rule --generate-cli-skeleton > rule.json + aws codestar-notifications create-notification-rule --generate-cli-skeleton > rule.json ``` You can name the file anything you want\. In this example, the file is named *rule\.json*\. @@ -68,7 +68,7 @@ If you want to use an existing Amazon SNS topic instead of creating a new one, i 1. Using the file you just edited, at the terminal or command line, run the create\-notification\-rule command again to create the notification rule: ``` - aws codestarnotifications create-notification-rule --cli-input-json file://rule.json + aws codestar-notifications create-notification-rule --cli-input-json file://rule.json ``` 1. If successful, the command returns the ARN of the notification rule, similar to the following: @@ -77,4 +77,4 @@ If you want to use an existing Amazon SNS topic instead of creating a new one, i { "Arn": "arn:aws:codestar-notifications:us-east-1:123456789012:notificationrule/dc82df7a-EXAMPLE" } - ``` \ No newline at end of file + ``` From 1bd68bd04a5c3a2db4205ff4b9b62ea15186b0a9 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Mon, 9 Dec 2019 19:22:57 +0000 Subject: [PATCH 020/156] Periodic update, Dec 9, 2019 --- doc_source/build-env-ref-available.md | 7 ++++++- doc_source/build-env-ref-compute-types.md | 6 +++--- doc_source/build-spec-ref.md | 2 +- doc_source/history.md | 8 ++++---- doc_source/notification-rule-create.md | 2 +- doc_source/sample-build-badges.md | 3 ++- doc_source/troubleshooting.md | 20 ++++++++++++++++---- 7 files changed, 33 insertions(+), 15 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index df8ed5a..f726cee 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -8,8 +8,10 @@ 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:1\.0 | [al2/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/1.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\-aarch64\-standard:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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) | +| 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) | | Windows Server Core 2016 | aws/codebuild/windows\-base:1\.0 | N/A | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | @@ -21,12 +23,15 @@ AWS CodeBuild manages the following Docker images that are available in the Code | android | 28, 29 | android: 28, android: 29 | | docker | 18 | docker: 18 | | dotnet | 2\.2 | dotnet: 2\.2 | +| dotnet \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 3\.0 | dotnet: 3\.0 | | golang | 1\.12, 1\.13 | golang: 1\.12, golang: 1\.13 | | nodejs | 8, 10 | nodejs: 8, nodejs: 10 | +| nodejs \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 10, 12 | nodejs: 10, nodejs: 12 | | java \(Ubuntu only\) | openjdk8, openjdk11 | java: openjdk8, java: openjdk11 | | java \(Amazon Linux 2 only\) | corretto8, corretto11 | java: corretto8, java: corretto11 | | php | 7\.3 | php: 7\.3 | | python | 3\.7 | python: 3\.7 | +| python \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 3\.8 | python: 3\.8 | | ruby | 2\.6 | ruby: 2\.6 | **Note** @@ -46,7 +51,7 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the | ruby | 2\.4 | 2\.6 | **Note** - The base image of the Windows Server Core 2016 platform is available in the US East \(N\. Virginia\), US East \(Ohio\), US West \(Oregon\), and EU \(Ireland\) regions only\. + The base image of the Windows Server Core 2016 platform is 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 [Build Spec Example](build-spec-ref.md#build-spec-ref-example)\. diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index bbc92d3..a0fd66c 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -16,9 +16,9 @@ AWS CodeBuild provides build environments with the following available memory, v **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\), EU \(Ireland\), EU \(London\), EU \(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\), EU \(Ireland\), Asia Pacific \(Mumbai\), Asia Pacific \(Tokyo\), Asia Pacific \(Sydney\), and EU \(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\), EU \(Stockholm\), EU \(Ireland\), EU \(London\), EU \(Paris\), EU \(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\)\. +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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 4f088d1..9ed393f 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -483,4 +483,4 @@ The following table lists the build spec versions and the changes between versio | 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/history.md b/doc_source/history.md index 08da3cd..60a6dcf 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **November 25, 2019 ++ **Latest documentation update: **December 9, 2019 | Change | Description | Date | | --- |--- |--- | @@ -51,7 +51,7 @@ The following table describes important changes in each release of the *AWS Code | 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 riggers to schedule builds at regular frequencies\. For more information, see [Create 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 CodeBuild Endpoint](endpoint-specify.md)\. | March 28, 2018 | -| AWS CodeBuild available in Asia Pacific \(Mumbai\), EU \(Paris\), and South America \(São Paulo\) | AWS CodeBuild is now available in the Asia Pacific \(Mumbai\), EU \(Paris\), and South America \(São Paulo\) regions\. For more information, see the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | March 28, 2018 | | GitHub Enterprise support | CodeBuild can now build from source code stored in a GitHub Enterprise repository\. For more information, see [GitHub Enterprise 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 | @@ -63,14 +63,14 @@ The following table describes important changes in each release of the *AWS Code | 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 build spec | AWS CodeBuild now makes it easier to use a build spec 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 [Build Spec 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\), EU \(London\), and Canada \(Central\) | AWS CodeBuild is now available in the US West \(N\. California\), EU \(London\), and Canada \(Central\) regions\. For more information, see the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | June 29, 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | June 29, 2017 | | Alternate build spec file names and locations supported | You can now specify an alternate file name or location of a build spec file to use for a build project, instead of a default build spec file named buildspec\.yml at the root of the source code\. For more information, see [Build Spec 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.md#run-build-console) or the `sourceVersion` value in [Run a Build \(AWS CLI\)](run-build.md#run-build-cli)\. | June 6, 2017 | | Build specification version updated | A new version of the build spec 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 EU \(Frankfurt\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), and Asia Pacific \(Tokyo\) | AWS CodeBuild is now available in the EU \(Frankfurt\), Asia Pacific \(Singapore\), Asia Pacific \(Sydney\), and Asia Pacific \(Tokyo\) regions\. For more information, see the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | March 21, 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic 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 an CodeBuild Test Action to a Pipeline \(CodePipeline Console\)](how-to-create-pipeline.md#how-to-create-pipeline-add-test)\. | March 8, 2017 | | Build specs support fetching build output from within selected top\-level directories | Build specs 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 [Build Spec 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 | diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md index cfaec01..929aecf 100644 --- a/doc_source/notification-rule-create.md +++ b/doc_source/notification-rule-create.md @@ -77,4 +77,4 @@ If you want to use an existing Amazon SNS topic instead of creating a new one, i { "Arn": "arn:aws:codestar-notifications:us-east-1:123456789012:notificationrule/dc82df7a-EXAMPLE" } - ``` + ``` \ No newline at end of file diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 1120ab9..756e3d4 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -11,12 +11,13 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, 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 **Source**, for **Source provider**, choose the source code provider type, and then do one of the following: - + If you chose **Amazon S3**, then for **Bucket**, choose the name of the input bucket that contains the source code\. For **S3 object key**, enter the name of the ZIP file that contains the source code\. + If you chose **CodeCommit**, then for **Repository**, choose the name of the repository\. Select **Enable build badge** to make your project's build status visible and embeddable\. + If you chose **GitHub**, follow the instructions to connect \(or reconnect\) with GitHub\. On the GitHub **Authorize application** page, for **Organization access**, choose **Request access** next to each repository you want AWS CodeBuild to be able to access\. After you choose **Authorize application**, back in the AWS CodeBuild console, for **Repository**, choose the name of the repository that contains the source code\. Select **Enable build badge** to make your project's build status visible and embeddable\. + If you chose **Bitbucket**, follow the instructions to connect \(or reconnect\) with Bitbucket\. On the Bitbucket **Confirm access to your account** page, for **Organization access**, choose **Grant access**\. After you choose **Grant access**, back in the AWS CodeBuild console, for **Repository**, choose the name of the repository that contains the source code\. Select **Enable build badge** to make your project's build status visible and embeddable\. **Important** Updating your project source might affect the accuracy of the project's build badges\. +**Note** + CodeBuild does not support build badges with the S3 source provider\. 1. In **Environment**: diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 7b52c02..8c5e65e 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -398,12 +398,24 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u **Issue:** When you try to update a project in the console, the update failed with the error: "The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation\." **Possible causes:** -+ You have manually updated the policies attached to the target AWS CodeBuild service role\. -+ You have selected a previous version of a policy attached to the target CodeBuild service role\. ++ You have updated the policies attached to the target AWS CodeBuild service role\. ++ You have selected an earlier version of a policy attached to the target CodeBuild service role\. **Recommended solutions:** -+ Edit your CodeBuild project, and clear **Allow CodeBuild to modify this service role so it can be used with this build project**\. Manually update the target CodeBuild service role to have sufficient permissions\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. -+ Edit your CodeBuild project, and select **Create a role**\. ++ Edit your CodeBuild project and clear the **Allow CodeBuild to modify this service role so it can be used with this build project** check box\. Verify the CodeBuild service role you are using has sufficient permissions\. If you edit your CodeBuild project again, you must clear this check box again\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. ++ Edit your CodeBuild project to use a new service role: + + 1. Open the IAM console and create a new service role\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role) + + 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 button next to your build project, choose **Edit**, and then choose **Environment**\. + + 1. For **Service role**, choose the role you created\. + + 1. Choose **Update environment**\. ## 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" From 4e5fcb7ad44faa80538fdec72b96e2f35fdd8bd2 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Fri, 13 Dec 2019 21:18:20 +0000 Subject: [PATCH 021/156] Periodic update - Dec 13, 2019. CodeBuild now supports cross account resource sharing. --- doc_source/build-env-ref-compute-types.md | 2 + doc_source/create-project.md | 2 - doc_source/delete-project.md | 4 +- doc_source/history.md | 3 +- doc_source/index.md | 2 + doc_source/project-sharing.md | 157 +++++++++++++++++ doc_source/report-groups-sharing.md | 200 ++++++++++++++++++++++ doc_source/sample-build-notifications.md | 2 +- doc_source/sample-codedeploy.md | 2 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-lambda.md | 2 +- doc_source/test-report-group.md | 3 +- doc_source/use-codebuild-agent.md | 2 +- doc_source/working-with-build-projects.md | 3 +- 17 files changed, 379 insertions(+), 17 deletions(-) create mode 100644 doc_source/project-sharing.md create mode 100644 doc_source/report-groups-sharing.md diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index a0fd66c..3728211 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -14,6 +14,8 @@ AWS CodeBuild provides build environments with the following available memory, v | 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 | +The disk space listed for each build environment is available only in the directory specified by the `CODEBUILD_SRC_DIR` environment variable\. + **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\)\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 2b9c32f..ee62a50 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -390,8 +390,6 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + *cache\-location*: Required value only if you set *CacheType* to `S3`\. If you specified Amazon S3 for *CacheType*, this is the ARN of the Amazon S3 bucket and the path prefix\. For example, if your Amazon 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 value 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** -`LOCAL_DOCKER_LAYER_CACHE` mode is available for Linux only\. If you choose it, your project must run in privileged mode\. -**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 value\. Valid values are `ENABLED` or `DISABLED`\. If its value is `ENABLED` then 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)\. diff --git a/doc_source/delete-project.md b/doc_source/delete-project.md index f4ca655..d21e916 100644 --- a/doc_source/delete-project.md +++ b/doc_source/delete-project.md @@ -1,9 +1,9 @@ # Delete a Build Project in AWS CodeBuild -You can use the CodeBuild console, AWS CLI, or AWS SDKs to delete a build project in CodeBuild\. +You can use the CodeBuild console, AWS CLI, or AWS SDKs to delete a build project in CodeBuild\. If you delete a project, its builds are not deleted\. **Warning** -If you delete a build project, it cannot be recovered\. All information about builds is also deleted and cannot be recovered\. +You cannot delete a project that has builds and a resource policy\. To delete a project with a resource policy and builds, remove the resource policy or delete its builds first\. **Topics** + [Delete a Build Project \(Console\)](#delete-project-console) diff --git a/doc_source/history.md b/doc_source/history.md index 60a6dcf..de70f60 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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: **December 9, 2019 ++ **Latest documentation update: **December 13, 2019 | Change | Description | Date | | --- |--- |--- | +| [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 [Build Spec Syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | November 6, 2019 | diff --git a/doc_source/index.md b/doc_source/index.md index 37dc040..b949042 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -69,6 +69,7 @@ Amazon's trademarks and trade dress may not be used in + [Edit CodeBuild Triggers](triggers-edit.md) + [Change a Build Project's Settings in CodeBuild](change-project.md) + [Delete a Build Project in AWS CodeBuild](delete-project.md) + + [Working with Shared Projects](project-sharing.md) + [Working with Builds in CodeBuild](builds-working.md) + [Run a Build in CodeBuild](run-build.md) + [View Build Details in CodeBuild](view-build-details.md) @@ -88,6 +89,7 @@ Amazon's trademarks and trade dress may not be used in + [Specify Test Files](report-group-test-cases.md) + [Specify Test Commands](report-group-test-case-commands.md) + [Report Group Naming](test-report-group-naming.md) + + [Working with Shared Report Groups](report-groups-sharing.md) + [Working with Reports](test-report.md) + [Working with Test Report Permissions](test-permissions.md) + [View Test Reports](test-view-reports.md) diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md new file mode 100644 index 0000000..d84d71e --- /dev/null +++ b/doc_source/project-sharing.md @@ -0,0 +1,157 @@ +# Working with Shared Projects + +Project sharing allows project owners to share their CodeBuild projects with other AWS accounts or users\. In this model, the account that owns the project \(owner\) shares a project with other accounts \(consumers\)\. A consumer cannot edit or run a project\. + +**Topics** ++ [Prerequisites for Sharing Projects](#project-sharing-prereqs) ++ [Prerequisites for Accessing Shared Projects Shared with You](#project-sharing-access-prereqs) ++ [Related Services](#project-sharing-related) ++ [Sharing a Project](#project-sharing-share) ++ [Unsharing a Shared Project](#project-sharing-unshare) ++ [Identifying a Shared Project](#project-sharing-identify) ++ [Shared Project Permissions](#project-sharing-perms) + +## Prerequisites for Sharing Projects + + To share a project, your AWS account must own it\. You cannot share a project that has been shared with you\. + +## 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: + +``` +{ + "Effect": "Allow", + "Resource": [ + "*" + ], + "Action": [ + "codebuild:BatchGetProjects" + ] +} +``` + + For more information, see [Using Identity\-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. + +## Related Services + +Project sharing integrates with AWS Resource Access Manager \(AWS RAM\), a service that makes it possible for you to share your AWS resources with any AWS account or through AWS Organizations\. With AWS RAM, you share resources by creating a *resource share* that specifies the resources and the consumers to share them with\. Consumers can be individual AWS accounts, organizational units in AWS Organizations, or an entire organization in AWS Organizations\. + +For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*\. + +## Sharing a Project + +The consumer can use the AWS CLI but not the CodeBuild console to view the project and builds you've shared\. The consumer cannot edit or run the project\. + +You can add a project to an existing resource share or you can create one in the [AWS RAM console](https://console.aws.amazon.com/ram)\. + +**Note** + You cannot delete a project with builds that has been added to a resource share\. + +To share a project with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. + +You can use the CodeBuild console, AWS RAM console, or the AWS CLI to share a project that you own\. + +**To share a project that you own \(CodeBuild 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**\. +**Note** +By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. + +1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. + +**To share a project that you own \(AWS RAM console\)** +See [Creating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. + +**To share a project that you own \(AWS RAM command\)** +Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. + + **To share a project that you own \(CodeBuild command\)** + +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\. + + ``` + { + "Version":"2012-10-17", + "Statement":[{ + "Effect":"Allow", + "Principal":{ + "AWS":"consumer-aws-account-id-or-user" + }, + "Action":[ + "codebuild:BatchGetProjects", + "codebuild:BatchGetBuilds", + "codebuild:ListBuildsForProject"], + "Resource":"arn-of-project-to-share" + }] + } + ``` + +1. Update `policy.json` with the project ARN and identifiers to share it with\. The following example grants read\-only access to the project with the ARN `arn:aws:codebuild:us-west-2:123456789012:project/my-project` to Alice and the root user for the AWS account identified by 123456789012\. + + ``` + { + "Version":"2012-10-17", + "Statement":[{ + "Effect":"Allow", + "Principal":{ + "AWS": [ + "arn:aws:iam::123456789012:user/Alice", + "123456789012" + ] + }, + "Action":[ + "codebuild:BatchGetProjects", + "codebuild:BatchGetBuilds", + "codebuild:ListBuildsForProject"], + "Resource":"arn:aws:codebuild:us-west-2:123456789012:project/my-project" + }] + } + ``` + +1. Run the following command\. + + ``` + aws codebuild put-resource-policy --resource-arn project-arn --policy file://policy.json + ``` + +## Unsharing a Shared Project + +An unshared project, including its builds, can be accessed only by its owner\. If you unshare a project, any AWS account or user you previously shared it with cannot access the project or its builds\. + +To unshare a shared project that you own, you must remove it from the resource share\. You can use the CodeBuild console, AWS RAM console, or AWS CLI to do this\. + +**To unshare a shared project that you own \(AWS RAM console\)** +See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. + +**To unshare a shared project that you own \(AWS CLI\)** +Use the [disassociate\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command\. + + ** To unshare project that you own \(CodeBuild command\)** + +Run the [delete\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/delete-resource-policy.html) command and specify the ARN of the project you want to unshare: + +``` +aws codebuild delete-resource-policy --resource-arn project-arn +``` + +## Identifying a Shared Project + +Owners and consumers can use the AWS CLI to identify shared projects\. + +**To identify projects shared with your AWS account or user \(AWS CLI\)** +Use the [list\-shared\-project](https://docs.aws.amazon.com/cli/latest/reference/ram/list-shared-project.html) command to return the projects that are shared with you\. + +## Shared Project Permissions + +### Permissions for Owners + +A project owner can edit the project and use it to run builds\. + +### Permissions for Consumers + +A project consumer can view a project and its builds, but cannot edit a project or use it to run builds\. \ No newline at end of file diff --git a/doc_source/report-groups-sharing.md b/doc_source/report-groups-sharing.md new file mode 100644 index 0000000..7474119 --- /dev/null +++ b/doc_source/report-groups-sharing.md @@ -0,0 +1,200 @@ +# Working with Shared Report Groups + +Report group sharing allows multiple AWS accounts or users to view a report group, its unexpired reports, and the test results of its reports\. In this model, the account that owns the report group \(owner\) shares a report group with other accounts \(consumers\)\. A consumer cannot edit a report group\. A report expires 30 days after it is created\. + +**Topics** ++ [Prerequisites for Sharing Report Groups](#report-groups-sharing-prereqs) ++ [Prerequisites for Accessing Report Groups Shared with You](#report-groups-sharing-access-prereqs) ++ [Related Services](#report-groups-sharing-related) ++ [Sharing a Report Group](#report-groups-sharing-share) ++ [Unsharing a Shared Report Group](#report-groups-sharing-unshare) ++ [Identifying a Shared Report Group](#report-groups-sharing-identify) ++ [Shared Report Group Permissions](#report-groups-sharing-perms) + +## Prerequisites for Sharing Report Groups + + To share a report group, your AWS account must own it\. You cannot share a report group that has been shared with you\. + +## Prerequisites for Accessing Report Groups Shared with You + +To access a shared report group, a consumer's IAM role requires the `BatchGetReportGroups` permission\. You can attach the following policy to their IAM role: + +``` +{ + "Effect": "Allow", + "Resource": [ + "*" + ], + "Action": [ + "codebuild:BatchGetReportGroups" + ] +} +``` + + For more information, see [Using Identity\-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. + +## Related Services + +Report group sharing integrates with AWS Resource Access Manager \(AWS RAM\), a service that makes it possible for you to share your AWS resources with any AWS account or through AWS Organizations\. With AWS RAM, you share resources that you own by creating a *resource share* that specifies the resources and the consumers to share them with\. Consumers can be individual AWS accounts, organizational units in AWS Organizations, or an entire organization in AWS Organizations\. + +For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*\. + +## Sharing a Report Group + + When you share a report group, the consumer is granted read\-only access to the report group and its reports\. The consumer can use the AWS CLI to view the report group, its reports, and the test case results for each report\. The consumer cannot: ++ View a shared report group or its reports in the CodeBuild console\. ++ Edit a shared report group\. ++ Use the ARN of the shared report group in a project to run a report\. A project build that specifies a shared report group fails\. + +You can use the CodeBuild console to add a report group to an existing resource share\. If you want to add the report group to a new resource share, you must first create it in the [AWS RAM console](https://console.aws.amazon.com/ram)\. + +To share a report group with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. + +You can use the CodeBuild console, AWS RAM console, or AWS CLI to share report groups that you own\. + +**To share a report group that you own \(CodeBuild 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 **Report groups**\. + +1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. + +**To share report groups that you own \(AWS RAM console\)** +See [Creating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. + +**To share report groups that you own \(AWS RAM command\)** +Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. + + **To share a report group that you own \(CodeBuild command\)** + +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\. + + ``` + { + "Version":"2012-10-17", + "Statement":[{ + "Effect":"Allow", + "Principal":{ + "AWS":"consumer-aws-account-id-or-user" + }, + "Action":[ + "codebuild:BatchGetReportGroups", + "codebuild:BatchGetReports", + "codebuild:ListBuildsForProject", + "codebuild:DescribeTestCases"], + "Resource":"arn-of-report-group-to-share" + }] + } + ``` + +1. Update `policy.json` with the report group ARN and identifiers to share it with\. The following example grants read\-only access to the report group with the ARN `arn:aws:codebuild:us-west-2:123456789012:report-group/my-report-group` to Alice and the root user for the AWS account identified by 123456789012\. + + ``` + { + "Version":"2012-10-17", + "Statement":[{ + "Effect":"Allow", + "Principal":{ + "AWS": [ + "arn:aws:iam::123456789012:user/Alice", + "123456789012" + ] + }, + "Action":[ + "codebuild:BatchGetReportGroups", + "codebuild:BatchGetReports", + "codebuild:ListBuildsForProject", + "codebuild:DescribeTestCases"], + "Resource":"arn:aws:codebuild:us-west-2:123456789012:report-group/my-report-group" + }] + } + ``` + +1. Run the following command\. + + ``` + aws codebuild put-resource-policy --resource-arn report-group-arn --policy file://policy.json + ``` + +## Unsharing a Shared Report Group + +An unshared report group, including its reports and their test case results, can be accessed only by its owner\. If you unshare a report group, any AWS account or user you previously shared it with cannot access the report group, its reports, or the results of test cases in the reports\. + +To unshare a shared report group that you own, you must remove it from the resource share\. You can use the AWS RAM console or AWS CLI to do this\. + +**To unshare a shared report group that you own \(AWS RAM console\)** +See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. + +**To unshare a shared report group that you own \(AWS RAM command\)** +Use the [disassociate\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command\. + + ** To unshare report group that you own CodeBuild command\)** + +Run the [delete\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/delete-resource-policy.html) command and specify the ARN of the report group you want to unshare: + +``` +aws codebuild delete-resource-policy --resource-arn report-group-arn +``` + +## Identifying a Shared Report Group + +Owners and consumers can use the AWS CLI to identify shared report groups\. + +To identify and get information about a shared report group and its reports, use the following commands: ++ To see the ARNs of report groups shared with you, run `[list\-shared\-report\-groups](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-shared-report-groups.html)`: + + ``` + aws codebuild list-shared-report-groups + ``` ++ To see the ARNs of the reports in a report group, run `[list\-reports\-for\-report\-group](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-reports-for-report-group.html)` using the report group ARN: + + ``` + aws codebuild list-reports-for-report-group --report-group-arn report-group-arn + ``` ++ To see information about test cases in a report, run `[describe\-test\-cases](https://docs.aws.amazon.com/cli/latest/reference/codebuild/describe-test-cases.html)` using the report ARN: + + ``` + aws codebuild describe-test-cases --report-arn report-arn + ``` + + The output looks like the following: + + ``` + { + "testCases": [ + { + "status": "FAILED", + "name": "Test case 1", + "expired": 1575916770.0, + "reportArn": "report-arn", + "prefix": "Cucumber tests for agent", + "message": "A test message", + "durationInNanoSeconds": 1540540, + "testRawDataPath": "path-to-output-report-files" + }, + { + "status": "SUCCEEDED", + "name": "Test case 2", + "expired": 1575916770.0, + "reportArn": "report-arn", + "prefix": "Cucumber tests for agent", + "message": "A test message", + "durationInNanoSeconds": 1540540, + "testRawDataPath": "path-to-output-report-files" + } + ] + } + ``` + +## Shared Report Group Permissions + +### Permissions for Owners + +A report group owner can edit the report group and specify it in a project to run reports\. + +### Permissions for Consumers + +A report group consumer can view a report group, its reports, and the test case results for its reports\. A consumer cannot edit a report group or its reports, and cannot use it to create reports\. \ No newline at end of file diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 753f882..0a0a05a 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 540d18f..f1c00b5 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 5bede52..deb3918 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w39aac11c41c34c17) ++ [Related Resources](#w47aac11c41c34c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index bc8d941..c51e90b 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w39aac11c41c19c23) ++ [Related Resources](#w47aac11c41c19c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index cb77181..5f632ca 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 34d8e37..d9e8d8f 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index 6c252d3..20ef089 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md index a28b509..a1cc90a 100644 --- a/doc_source/test-report-group.md +++ b/doc_source/test-report-group.md @@ -16,4 +16,5 @@ A *report group* contains test reports and specifies shared settings\. You use t + [Specify Export Settings](report-group-export-settings.md) + [Specify Test Files](report-group-test-cases.md) + [Specify Test Commands](report-group-test-case-commands.md) -+ [Report Group Naming](test-report-group-naming.md) \ No newline at end of file ++ [Report Group Naming](test-report-group-naming.md) ++ [Working with Shared Report Groups](report-groups-sharing.md) \ No newline at end of file diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 5e180d4..531742e 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -28,7 +28,7 @@ docker inspect amazon/aws-codebuild-local 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 region to **US East \(N\. Virginia\)**, if it not already selected\. You must select this region because the SNS notifications that you are subscribing to are created in this region\. +1. In the navigation bar, if it's not already selected, change the region to **US East \(N\. Virginia\)**\. You must select this region because the Amazon SNS notifications that you are subscribing to are created in this region\. 1. In the navigation pane, choose **Subscriptions**\. diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index bbd58e9..62960ae 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -13,4 +13,5 @@ You can perform these tasks when working with build projects: + [Create CodeBuild Triggers](trigger-create.md) + [Edit CodeBuild Triggers](triggers-edit.md) + [Change a Build Project's Settings in CodeBuild](change-project.md) -+ [Delete a Build Project in AWS CodeBuild](delete-project.md) \ No newline at end of file ++ [Delete a Build Project in AWS CodeBuild](delete-project.md) ++ [Working with Shared Projects](project-sharing.md) \ No newline at end of file From dbf3ee624451c7e5f92d3bddbf49dfd7c90e72ce Mon Sep 17 00:00:00 2001 From: sharmus <45380175+sharmus@users.noreply.github.com> Date: Sun, 15 Dec 2019 15:20:44 +1100 Subject: [PATCH 022/156] Update sample-build-badges.md Added text "Build badges are also not supported when CodeBuild project is part of a CodePipeline." to clarify build badge support is not available when used as part of CodePipeline project. --- doc_source/sample-build-badges.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 756e3d4..6f8382f 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -17,7 +17,7 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, **Important** Updating your project source might affect the accuracy of the project's build badges\. **Note** - CodeBuild does not support build badges with the S3 source provider\. + CodeBuild does not support build badges with the S3 source provider\. Build badges are also not supported when CodeBuild project is part of a CodePipeline. 1. In **Environment**: @@ -76,4 +76,4 @@ Sample markdown code: + **PASSING** The most recent build on the given branch passed\. + **FAILING** The most recent build on the given branch timed out, failed, faulted, or was stopped\. + **IN\_PROGRESS** The most recent build on the given branch is in progress\. -+ **UNKNOWN** The project has not yet run a build for the given branch or at all\. Also, the build badges feature might have been disabled\. \ No newline at end of file ++ **UNKNOWN** The project has not yet run a build for the given branch or at all\. Also, the build badges feature might have been disabled\. From 5d1be04ba6754e0601dd85f05df9c3566bc97a8d Mon Sep 17 00:00:00 2001 From: sharmus <45380175+sharmus@users.noreply.github.com> Date: Tue, 17 Dec 2019 08:40:04 +1100 Subject: [PATCH 023/156] Update sample-build-badges.md --- doc_source/sample-build-badges.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 6f8382f..d07ed4d 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -17,7 +17,7 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, **Important** Updating your project source might affect the accuracy of the project's build badges\. **Note** - CodeBuild does not support build badges with the S3 source provider\. Build badges are also not supported when CodeBuild project is part of a CodePipeline. + CodeBuild does not support build badges with the S3 source provider\. Because AWS CodePipeline uses S3 for artifact transfers, build badges are not supported for build projects that are part of a CodePipeline pipeline\. 1. In **Environment**: From 385c01e475985fd010e0d6752d3cb7741c5df6f4 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Mon, 23 Dec 2019 17:49:02 +0000 Subject: [PATCH 024/156] Periodic update, Dec 23, 2019 --- doc_source/build-env-ref-available.md | 22 +- doc_source/build-spec-ref.md | 12 +- doc_source/concepts.md | 4 +- doc_source/create-project.md | 2 +- .../getting-started-build-log-console.md | 17 + .../getting-started-clean-up-console.md | 32 + doc_source/getting-started-cli-build-log.md | 70 ++ doc_source/getting-started-cli-clean-up.md | 32 + ...etting-started-cli-create-build-project.md | 112 +++ .../getting-started-cli-create-build-spec.md | 63 ++ .../getting-started-cli-create-source-code.md | 122 +++ .../getting-started-cli-input-bucket.md | 20 + .../getting-started-cli-monitor-build.md | 84 ++ doc_source/getting-started-cli-next-steps.md | 5 + doc_source/getting-started-cli-output.md | 29 + doc_source/getting-started-cli-run-build.md | 62 ++ .../getting-started-cli-upload-source-code.md | 36 + doc_source/getting-started-cli.md | 21 + ...ng-started-create-build-project-console.md | 51 ++ ...tting-started-create-build-spec-console.md | 63 ++ ...ting-started-create-source-code-console.md | 122 +++ .../getting-started-input-bucket-console.md | 20 + .../getting-started-monitor-build-console.md | 32 + .../getting-started-next-steps-console.md | 5 + doc_source/getting-started-output-console.md | 29 + doc_source/getting-started-overview.md | 8 + .../getting-started-run-build-console.md | 19 + ...ting-started-upload-source-code-console.md | 36 + doc_source/getting-started.md | 720 +----------------- doc_source/history.md | 2 +- doc_source/index.md | 26 +- doc_source/project-sharing.md | 2 +- doc_source/run-build.md | 2 +- doc_source/sample-build-badges.md | 4 +- doc_source/sample-build-notifications.md | 4 +- doc_source/sample-codedeploy.md | 4 +- doc_source/sample-docker-custom-image.md | 6 +- doc_source/sample-docker.md | 6 +- doc_source/sample-ecr.md | 4 +- doc_source/sample-elastic-beanstalk.md | 4 +- doc_source/sample-lambda.md | 4 +- doc_source/sample-runtime-versions.md | 2 +- doc_source/setting-up.md | 2 +- doc_source/view-build-details.md | 2 +- doc_source/welcome.md | 2 +- doc_source/working-with-build-projects.md | 2 +- 46 files changed, 1181 insertions(+), 747 deletions(-) create mode 100644 doc_source/getting-started-build-log-console.md create mode 100644 doc_source/getting-started-clean-up-console.md create mode 100644 doc_source/getting-started-cli-build-log.md create mode 100644 doc_source/getting-started-cli-clean-up.md create mode 100644 doc_source/getting-started-cli-create-build-project.md create mode 100644 doc_source/getting-started-cli-create-build-spec.md create mode 100644 doc_source/getting-started-cli-create-source-code.md create mode 100644 doc_source/getting-started-cli-input-bucket.md create mode 100644 doc_source/getting-started-cli-monitor-build.md create mode 100644 doc_source/getting-started-cli-next-steps.md create mode 100644 doc_source/getting-started-cli-output.md create mode 100644 doc_source/getting-started-cli-run-build.md create mode 100644 doc_source/getting-started-cli-upload-source-code.md create mode 100644 doc_source/getting-started-cli.md create mode 100644 doc_source/getting-started-create-build-project-console.md create mode 100644 doc_source/getting-started-create-build-spec-console.md create mode 100644 doc_source/getting-started-create-source-code-console.md create mode 100644 doc_source/getting-started-input-bucket-console.md create mode 100644 doc_source/getting-started-monitor-build-console.md create mode 100644 doc_source/getting-started-next-steps-console.md create mode 100644 doc_source/getting-started-output-console.md create mode 100644 doc_source/getting-started-overview.md create mode 100644 doc_source/getting-started-run-build-console.md create mode 100644 doc_source/getting-started-upload-source-code-console.md diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index f726cee..d9ee774 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -7,14 +7,14 @@ 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:1\.0 | [al2/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/1.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\-aarch64\-standard:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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) | | 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) | -| Windows Server Core 2016 | aws/codebuild/windows\-base:1\.0 | N/A | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | + The latest version of each images 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.0-1.0.0`\. + The standard image of the Ubuntu 18\.04 and Amazon Linux 2 platforms contain the following runtimes\. If you use the Amazon Linux 2 standard image 1\.0 or the Ubuntu standard image 2\.0, you must specify your runtime in the `runtime-versions` section of your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](build-spec-ref.md#runtime-versions-buildspec-file)\. @@ -40,15 +40,15 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the The base image of the Windows Server Core 2016 contains the following runtimes\. -| Runtime name | Version in `windows-base:1.0` | Version in `windows-base:2.0` | -| --- | --- | --- | -| dotnet | 2\.1 | 2\.2 | -| golang | 1\.11 | 1\.13 | -| nodejs | 9\.11 | 10\.16 | -| java | openjdk8 | openjdk11 | -| php | 7\.2 | 7\.3 | -| python | 3\.6 | 3\.7 | -| ruby | 2\.4 | 2\.6 | +| Runtime name | Version in `windows-base:2.0` | +| --- | --- | +| dotnet | 2\.2 | +| golang | 1\.13 | +| nodejs | 10\.16 | +| java | openjdk11 | +| php | 7\.3 | +| python | 3\.7 | +| ruby | 2\.6 | **Note** The base image of the Windows Server Core 2016 platform is available in the US East \(N\. Virginia\), US East \(Ohio\), US West \(Oregon\), and Europe \(Ireland\) regions only\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 9ed393f..2d77b8f 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -25,7 +25,13 @@ To override the default build spec file name, location, or both, do one of the f ## Build Spec Syntax -Build spec files must be expressed in [YAML](http://yaml.org/) format\. +Build spec files must be expressed in [YAML](http://yaml.org/) format\. + +If a command contains a character, or a string of characters, that is not supported by YAML, you must enclose the command in quotation marks \(""\)\. The following command is enclosed in quotation marks because a colon \(:\) followed by a space is not allowed in YAML\. The quotation mark in the command is escaped \(\\"\)\. + +``` +"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')" +``` **Important** If you use the Ubuntu standard image 2\.0 or later, or the Amazon Linux 2 \(AL2\) standard image 1\.0 or later, you must specify `runtime-versions` in your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](#runtime-versions-buildspec-file)\. @@ -180,7 +186,7 @@ In build spec version 0\.1, CodeBuild runs each command in a separate instance o The allowed build phase names are: + `install`: Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. - + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 1\.0, then the following specifies that version 8 of Java, version 29 of Android, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. + + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, version 29 of Android, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. ``` phases: @@ -190,7 +196,7 @@ In build spec version 0\.1, CodeBuild runs each command in a separate instance o android: 29 ruby: "$MY_RUBY_VAR" ``` - + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, if you use any supported version of `android`, then version 8 of Java is required\. If you use the Ubuntu standard image 2\.0, you specify this using `java: openjdk8`\. If you use the Amazon Linux 2 standard image 1\.0, you specify this using `java: corretto8`\. + + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, if you use any supported version of `android`, then version 8 of Java is required\. If you use the Ubuntu standard image 2\.0, you specify this using `java: openjdk8`\. If you use the Amazon Linux 2 standard image 2\.0, you specify this using `java: corretto8`\. + 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\. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) diff --git a/doc_source/concepts.md b/doc_source/concepts.md index 65085d4..aec74e1 100644 --- a/doc_source/concepts.md +++ b/doc_source/concepts.md @@ -12,7 +12,7 @@ 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* defines how CodeBuild runs a build\. It includes information such as where to get the source code, the build environment to use, the 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: +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) @@ -30,6 +30,6 @@ The following diagram shows what happens when you run a build with CodeBuild: Now that you know more about AWS CodeBuild, we recommend that you complete the following steps: -1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting Started](getting-started.md)\. +1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting Started in the Console](getting-started.md)\. 1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a Build](planning.md)\. \ No newline at end of file diff --git a/doc_source/create-project.md b/doc_source/create-project.md index ee62a50..ce4e10e 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -489,7 +489,7 @@ If you choose **New service role**, the created service role includes permission + *encryptionKey*: Optional value\. The alias or ARN of the AWS KMS customer managed key \(CMK\) CodeBuild uses 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 that contains a `key` and `value` value of *tag\-key* and *tag\-value*\. - For an example, see [To create the build project \(AWS CLI\)](getting-started.md#getting-started-create-build-project-cli)\. + For an example, see [To create the build project ](getting-started-cli-create-build-project.md#getting-started-cli-create-build-project-cli)\. 1. Switch to the directory that contains the file you just saved, and run the create\-projectcommand again: diff --git a/doc_source/getting-started-build-log-console.md b/doc_source/getting-started-build-log-console.md new file mode 100644 index 0000000..bffc48e --- /dev/null +++ b/doc_source/getting-started-build-log-console.md @@ -0,0 +1,17 @@ +# Step 8: View Detailed Build Information + +\(Previous step: [Step 7: View Summarized Build Information](getting-started-monitor-build-console.md)\) + +In this step, you view detailed information about your build in CloudWatch Logs\. + +**To view detailed build information** + +1. With the build details page still displayed from the previous step, the last 10,000 lines of the build log are displayed in **Build logs**\. To see the entire build log in CloudWatch Logs, choose the **View entire log** link\. + +1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. + +1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. + +## Next Step + +[Step 9: Get the Build Output Artifact](getting-started-output-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-clean-up-console.md b/doc_source/getting-started-clean-up-console.md new file mode 100644 index 0000000..bc69ed6 --- /dev/null +++ b/doc_source/getting-started-clean-up-console.md @@ -0,0 +1,32 @@ +# Step 10: Clean Up + +\(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*\. + +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\. + +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\. + +``` +{ + "Version": "2012-10-17", + "Id": "...", + "Statement": [ + ### BEGIN ADDING STATEMENT HERE ### + { + "Effect": "Allow", + "Action": [ + "s3:DeleteBucket", + "s3:DeleteObject" + ], + "Resource": "*" + } + ### END ADDING STATEMENT HERE ### + ] +} +``` + +## Next Step + +[Wrapping Up](getting-started-next-steps-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-build-log.md b/doc_source/getting-started-cli-build-log.md new file mode 100644 index 0000000..df83df7 --- /dev/null +++ b/doc_source/getting-started-cli-build-log.md @@ -0,0 +1,70 @@ +# Step 8: View Detailed Build Information + +\(Previous step: [Step 7: View Summarized Build Information](getting-started-cli-monitor-build.md)\) + +In this step, you view detailed information about your build in CloudWatch Logs\. + +**To view detailed build information** + +1. Use your web browser to go to the `deepLink` location that appeared in the output in the previous step \(for example, `https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE`\)\. + +1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. + +1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. + +These portions of a CloudWatch Logs log stream pertain to this tutorial\. + +``` +... +[Container] 2016/04/15 17:49:42 Entering phase PRE_BUILD +[Container] 2016/04/15 17:49:42 Running command echo Entering pre_build phase... +[Container] 2016/04/15 17:49:42 Entering pre_build phase... +[Container] 2016/04/15 17:49:42 Phase complete: PRE_BUILD Success: true +[Container] 2016/04/15 17:49:42 Entering phase BUILD +[Container] 2016/04/15 17:49:42 Running command echo Entering build phase... +[Container] 2016/04/15 17:49:42 Entering build phase... +[Container] 2016/04/15 17:49:42 Running command mvn install +[Container] 2016/04/15 17:49:44 [INFO] Scanning for projects... +[Container] 2016/04/15 17:49:44 [INFO] +[Container] 2016/04/15 17:49:44 [INFO] ------------------------------------------------------------------------ +[Container] 2016/04/15 17:49:44 [INFO] Building Message Utility Java Sample App 1.0 +[Container] 2016/04/15 17:49:44 [INFO] ------------------------------------------------------------------------ +... +[Container] 2016/04/15 17:49:55 ------------------------------------------------------- +[Container] 2016/04/15 17:49:55 T E S T S +[Container] 2016/04/15 17:49:55 ------------------------------------------------------- +[Container] 2016/04/15 17:49:55 Running TestMessageUtil +[Container] 2016/04/15 17:49:55 Inside testSalutationMessage() +[Container] 2016/04/15 17:49:55 Hi!Robert +[Container] 2016/04/15 17:49:55 Inside testPrintMessage() +[Container] 2016/04/15 17:49:55 Robert +[Container] 2016/04/15 17:49:55 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 sec +[Container] 2016/04/15 17:49:55 +[Container] 2016/04/15 17:49:55 Results : +[Container] 2016/04/15 17:49:55 +[Container] 2016/04/15 17:49:55 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 +... +[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ +[Container] 2016/04/15 17:49:56 [INFO] BUILD SUCCESS +[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ +[Container] 2016/04/15 17:49:56 [INFO] Total time: 11.845 s +[Container] 2016/04/15 17:49:56 [INFO] Finished at: 2016-04-15T17:49:56+00:00 +[Container] 2016/04/15 17:49:56 [INFO] Final Memory: 18M/216M +[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ +[Container] 2016/04/15 17:49:56 Phase complete: BUILD Success: true +[Container] 2016/04/15 17:49:56 Entering phase POST_BUILD +[Container] 2016/04/15 17:49:56 Running command echo Entering post_build phase... +[Container] 2016/04/15 17:49:56 Entering post_build phase... +[Container] 2016/04/15 17:49:56 Phase complete: POST_BUILD Success: true +[Container] 2016/04/15 17:49:57 Preparing to copy artifacts +[Container] 2016/04/15 17:49:57 Assembling file list +[Container] 2016/04/15 17:49:57 Expanding target/messageUtil-1.0.jar +[Container] 2016/04/15 17:49:57 Found target/messageUtil-1.0.jar +[Container] 2016/04/15 17:49:57 Creating zip artifact +``` + +In this example, CodeBuild successfully completed the pre\-build, build, and post\-build build phases\. It ran the unit tests and successfully built the `messageUtil-1.0.jar` file\. + +## Next Step + +[Step 9: Get the Build Output Artifact](getting-started-cli-output.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-clean-up.md b/doc_source/getting-started-cli-clean-up.md new file mode 100644 index 0000000..7384968 --- /dev/null +++ b/doc_source/getting-started-cli-clean-up.md @@ -0,0 +1,32 @@ +# Step 10: Clean Up + +\(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*\. + +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\. + +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\. + +``` +{ + "Version": "2012-10-17", + "Id": "...", + "Statement": [ + ### BEGIN ADDING STATEMENT HERE ### + { + "Effect": "Allow", + "Action": [ + "s3:DeleteBucket", + "s3:DeleteObject" + ], + "Resource": "*" + } + ### END ADDING STATEMENT HERE ### + ] +} +``` + +## Next Step + +[Wrapping Up](getting-started-cli-next-steps.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md new file mode 100644 index 0000000..6319ce4 --- /dev/null +++ b/doc_source/getting-started-cli-create-build-project.md @@ -0,0 +1,112 @@ +# Step 5: Create the Build Project + +\(Previous step: [Step 4: Upload the Source Code and the Build Spec](getting-started-cli-upload-source-code.md)\) + +In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. + +For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. + +**To create the build project** + +1. Use the AWS CLI to 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 named `create-project.json` in a location on the local computer or instance where the AWS CLI is installed\. If you choose to use a different file name, be sure to use it throughout this tutorial\. + + Modify the copied data to follow this format, and then save your results: + + ``` + { + "name": "codebuild-demo-project", + "source": { + "type": "S3", + "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" + }, + "artifacts": { + "type": "S3", + "location": "codebuild-region-ID-account-ID-output-bucket" + }, + "environment": { + "type": "LINUX_CONTAINER", + "image": "aws/codebuild/standard:2.0", + "computeType": "BUILD_GENERAL1_SMALL" + }, + "serviceRole": "serviceIAMRole" + } + ``` + + Replace *serviceIAMRole* with the Amazon Resource Name \(ARN\) of a CodeBuild service role \(for example, `arn:aws:iam::account-ID:role/role-name`\)\. To create one, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. + + In this data: + + `name` represents a required identifier for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across all build projects in your account\. + + For `source`, `type` is a required value that represents the source code's repository type \(in this example, `S3` for an Amazon S3 bucket\)\. + + 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:2.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\. + + 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`\)\. +**Note** +Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this tutorial, so they are not shown here\. For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. + +1. Switch to the directory that contains the file you just saved, and then run the create\-project command again\. + + ``` + aws codebuild create-project --cli-input-json file://create-project.json + ``` + + If successful, data similar to this appears in the output\. + + ``` + { + "project": { + "name": "codebuild-demo-project", + "serviceRole": "serviceIAMRole", + "tags": [], + "artifacts": { + "packaging": "NONE", + "type": "S3", + "location": "codebuild-region-ID-account-ID-output-bucket", + "name": "message-util.zip" + }, + "lastModified": 1472661575.244, + "timeoutInMinutes": 60, + "created": 1472661575.244, + "environment": { + "computeType": "BUILD_GENERAL1_SMALL", + "image": "aws/codebuild/standard:2.0", + "type": "LINUX_CONTAINER", + "environmentVariables": [] + }, + "source": { + "type": "S3", + "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" + }, + "encryptionKey": "arn:aws:kms:region-ID:account-ID:alias/aws/s3", + "arn": "arn:aws:codebuild:region-ID:account-ID:project/codebuild-demo-project" + } + } + ``` + + `project` represents information about this build project\. + + `tags` represents any tags that were declared\. + + `packaging` represents how the build output artifact is stored in the output bucket\. `NONE` means that a folder is created in the output bucket\. The build output artifact is stored in that folder\. + + `lastModified` represents the time, in Unix time format, when information about the build project was last changed\. + + `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\. + + `arn` represents the ARN of the build project\. + +**Note** +After you run the create\-project command, an error message similar to the following might be output: **User: *user\-ARN* is not authorized to perform: codebuild:CreateProject**\. This is most likely because you configured the AWS CLI with the credentials of an IAM user who does not have sufficient permissions to use CodeBuild to create build projects\. To fix this, configure the AWS CLI with credentials belonging to one of the following IAM entities: +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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. + +## Next Step + +[Step 6: Run the Build](getting-started-cli-run-build.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-spec.md b/doc_source/getting-started-cli-create-build-spec.md new file mode 100644 index 0000000..24dda34 --- /dev/null +++ b/doc_source/getting-started-cli-create-build-spec.md @@ -0,0 +1,63 @@ +# Step 3: Create the Build Spec + +\(Previous step: [Step 2: Create the Source Code](getting-started-cli-create-source-code.md)\) + +In this step, you create a build specification \(build spec\) file\. A *build spec* 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\. + +Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. + +``` +version: 0.2 + +phases: + install: + runtime-versions: + java: corretto11 + pre_build: + commands: + - echo Nothing to do in the pre_build phase... + build: + commands: + - echo Build started on `date` + - mvn install + post_build: + commands: + - echo Build completed on `date` +artifacts: + files: + - target/messageUtil-1.0.jar +``` + +**Important** +Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. + +**Note** +Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + +In this build spec declaration: ++ `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. ++ `phases` represents the build phases during which you can instruct CodeBuild to run commands\. These build phases are listed here as `install`, `pre_build`, `build`, and `post_build`\. You cannot change the spelling of these build phase names, and you cannot create more build phase names\. + + In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. ++ `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. + +For more information, see the [Build Spec Reference](build-spec-ref.md)\. + +At this point, your directory structure should look like this\. + +``` +(root directory name) + |-- pom.xml + |-- buildspec.yml + `-- src + |-- main + | `-- java + | `-- MessageUtil.java + `-- test + `-- java + `-- TestMessageUtil.java +``` + +## Next Step + +[Step 4: Upload the Source Code and the Build Spec](getting-started-cli-upload-source-code.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 new file mode 100644 index 0000000..cf660d4 --- /dev/null +++ b/doc_source/getting-started-cli-create-source-code.md @@ -0,0 +1,122 @@ +# Step 2: Create the Source Code + +\(Previous step: [Step 1: Create Two S3 Buckets](getting-started-cli-input-bucket.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\. + +1. In an empty directory on your local computer or instance, create this directory structure\. + + ``` + (root directory name) + `-- src + |-- main + | `-- java + `-- test + `-- java + ``` + +1. Using a text editor of your choice, create this file, name it `MessageUtil.java`, and then save it in the `src/main/java` directory\. + + ``` + public class MessageUtil { + private String message; + + public MessageUtil(String message) { + this.message = message; + } + + public String printMessage() { + System.out.println(message); + return message; + } + + public String salutationMessage() { + message = "Hi!" + message; + System.out.println(message); + return message; + } + } + ``` + + This class file creates as output the string of characters passed into it\. The `MessageUtil` constructor sets the string of characters\. The `printMessage` method creates the output\. The `salutationMessage` method outputs `Hi!` followed by the string of characters\. + +1. Create this file, name it `TestMessageUtil.java`, and then save it in the `/src/test/java` directory\. + + ``` + import org.junit.Test; + import org.junit.Ignore; + import static org.junit.Assert.assertEquals; + + public class TestMessageUtil { + + String message = "Robert"; + MessageUtil messageUtil = new MessageUtil(message); + + @Test + public void testPrintMessage() { + System.out.println("Inside testPrintMessage()"); + assertEquals(message,messageUtil.printMessage()); + } + + @Test + public void testSalutationMessage() { + System.out.println("Inside testSalutationMessage()"); + message = "Hi!" + "Robert"; + assertEquals(message,messageUtil.salutationMessage()); + } + } + ``` + + This class file sets the `message` variable in the `MessageUtil` class to `Robert`\. It then tests to see if the `message` variable was successfully set by checking whether the strings `Robert` and `Hi!Robert` appear in the output\. + +1. Create this file, name it `pom.xml`, and then save it in the root \(top level\) directory\. + + ``` + + 4.0.0 + org.example + messageUtil + 1.0 + jar + Message Utility Java Sample App + + + junit + junit + 4.11 + test + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.0 + + + + + ``` + + Apache Maven uses the instructions in this file to convert the `MessageUtil.java` and `TestMessageUtil.java` files into a file named `messageUtil-1.0.jar` and then run the specified tests\. + +At this point, your directory structure should look like this\. + +``` +(root directory name) + |-- pom.xml + `-- src + |-- main + | `-- java + | `-- MessageUtil.java + `-- test + `-- java + `-- TestMessageUtil.java +``` + +## Next Step + +[Step 3: Create the Build Spec](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 new file mode 100644 index 0000000..541bd7c --- /dev/null +++ b/doc_source/getting-started-cli-input-bucket.md @@ -0,0 +1,20 @@ +# Step 1: Create Two S3 Buckets + +\(Part of: [Getting Started with CodeBuild Using the AWS CLI](getting-started-cli.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\. ++ The other bucket \(the *output bucket*\) stores the build output\. In this tutorial, the name of this output bucket is `codebuild-region-ID-account-ID-output-bucket`\. + +If you chose different names for these buckets, be sure to use them throughout this tutorial\. + +These two buckets must be in the same AWS Region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, these buckets must also be in the US East \(Ohio\) Region\. + +For more information, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon Simple Storage Service User Guide*\. + +**Note** +Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a Build](planning.md)\. + +## Next Step + +[Step 2: Create the Source Code](getting-started-cli-create-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 new file mode 100644 index 0000000..0384752 --- /dev/null +++ b/doc_source/getting-started-cli-monitor-build.md @@ -0,0 +1,84 @@ +# Step 7: View Summarized Build Information + +\(Previous step: [Step 6: Run the Build](getting-started-cli-run-build.md)\) + +In this step, you view summarized information about the status of your build\. + +## To view summarized build information + +Use the AWS CLI to run the batch\-get\-builds command\. + +``` +aws codebuild batch-get-builds --ids id +``` + +Replace *id* with the `id` value that appeared in the output of the previous step\. + +If successful, data similar to this appears in the output\. + +``` +{ + "buildsNotFound": [], + "builds": [ + { + "buildComplete": true, + "phases": [ + { + "phaseStatus": "SUCCEEDED", + "endTime": 1472848788.525, + "phaseType": "SUBMITTED", + "durationInSeconds": 0, + "startTime": 1472848787.882 + }, + ... The full list of build phases has been omitted for brevity ... + { + "phaseType": "COMPLETED", + "startTime": 1472848878.079 + } + ], + "logs": { + "groupName": "/aws/codebuild/codebuild-demo-project", + "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE", + "streamName": "38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE" + }, + "artifacts": { + "md5sum": "MD5-hash", + "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip", + "sha256sum": "SHA-256-hash" + }, + "projectName": "codebuild-demo-project", + "timeoutInMinutes": 60, + "initiator": "user-name", + "buildStatus": "SUCCEEDED", + "environment": { + "computeType": "BUILD_GENERAL1_SMALL", + "image": "aws/codebuild/standard:2.0", + "type": "LINUX_CONTAINER", + "environmentVariables": [] + }, + "source": { + "type": "S3", + "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" + }, + "currentPhase": "COMPLETED", + "startTime": 1472848787.882, + "endTime": 1472848878.079, + "id": "codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE", + "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE" + } + ] +} +``` ++ `buildsNotFound` represents the build IDs for any builds where information is not available\. In this example, it should be empty\. ++ `builds` represents information about each build where information is available\. In this example, information about only one build appears in the output\. + + `phases` represents the set of build phases CodeBuild runs during the build process\. Information about each build phase is listed separately as `startTime`, `endTime`, and `durationInSeconds` \(when the build phase started and ended, expressed in Unix time format, and how long it lasted, in seconds\), and `phaseType` such as \(`SUBMITTED`, `PROVISIONING`, `DOWNLOAD_SOURCE`, `INSTALL`, `PRE_BUILD`, `BUILD`, `POST_BUILD`, `UPLOAD_ARTIFACTS`, `FINALIZING`, or `COMPLETED`\) and `phaseStatus` \(such as `SUCCEEDED`, `FAILED`, `FAULT`, `TIMED_OUT`, `IN_PROGRESS`, or `STOPPED`\)\. The first time you run the batch\-get\-builds command, there might not be many \(or any\) phases\. After subsequent runs of the batch\-get\-builds command with the same build ID, more build phases should appear in the output\. + + `logs` represents information in Amazon CloudWatch Logs about the build's logs\. + + `md5sum` and `sha256sum` represent MD5 and SHA\-256 hashes of the build's output artifact\. These appear in the output only if the build project's `packaging` value is set to `ZIP`\. \(You did not set this value in this tutorial\.\) You can use these hashes along with a checksum tool to confirm file integrity and authenticity\. +**Note** +You can also use the Amazon S3 console to view these hashes\. Select the box next to the build output artifact, choose **Actions**, and then choose **Properties**\. In the **Properties** pane, expand **Metadata**, and view the values for **x\-amz\-meta\-codebuild\-content\-md5** and **x\-amz\-meta\-codebuild\-content\-sha256**\. \(In the Amazon S3 console, the build output artifact's **ETag** value should not be interpreted to be either the MD5 or SHA\-256 hash\.\) +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\. + +## 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 new file mode 100644 index 0000000..bb6b116 --- /dev/null +++ b/doc_source/getting-started-cli-next-steps.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..1c14a11 --- /dev/null +++ b/doc_source/getting-started-cli-output.md @@ -0,0 +1,29 @@ +# Step 9: Get the Build Output Artifact + +\(Previous step: [Step 8: View Detailed Build Information](getting-started-cli-build-log.md)\) + +In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. + +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, in **Build Status**, choose the **View artifacts** link\. This opens the folder in Amazon S3 for the build output artifact\. \(If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\.\) + +1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. + +: + +**To get the build output artifact \(Amazon S3 console\)** + +1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. + +1. Open `codebuild-region-ID-account-ID-output-bucket`\. + +1. Open the `codebuild-demo-project` folder\. + +1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. + +## Next Step + +[Step 10: Clean Up](getting-started-cli-clean-up.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-run-build.md b/doc_source/getting-started-cli-run-build.md new file mode 100644 index 0000000..18cd64b --- /dev/null +++ b/doc_source/getting-started-cli-run-build.md @@ -0,0 +1,62 @@ +# Step 6: Run the Build + +\(Previous step: [Step 5: Create the Build Project](getting-started-cli-create-build-project.md)\) + +In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. + +**To run the build** + +1. Use the AWS CLI to run the start\-build command: + + ``` + aws codebuild start-build --project-name project-name + ``` + + Replace *project\-name* with your build project name from the previous step \(for example, `codebuild-demo-project`\)\. + +1. If successful, data similar to the following appears in the output: + + ``` + { + "build": { + "buildComplete": false, + "initiator": "user-name", + "artifacts": { + "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip" + }, + "projectName": "codebuild-demo-project", + "timeoutInMinutes": 60, + "buildStatus": "IN_PROGRESS", + "environment": { + "computeType": "BUILD_GENERAL1_SMALL", + "image": "aws/codebuild/standard:2.0", + "type": "LINUX_CONTAINER", + "environmentVariables": [] + }, + "source": { + "type": "S3", + "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" + }, + "currentPhase": "SUBMITTED", + "startTime": 1472848787.882, + "id": "codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE", + "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE" + } + } + ``` + + `build` represents information about this build\. + + `buildComplete` represents whether the build was completed \(`true`\)\. Otherwise, `false`\. + + `initiator` represents the entity that started the build\. + + `artifacts` represents information about the build output, including its location\. + + `projectName` represents the name of the build project\. + + `buildStatus` represents the current build status when the start\-build command was run\. + + `currentPhase` represents the current build phase when the start\-build command was run\. + + `startTime` represents the time, in Unix time format, when the build process started\. + + `id` represents the ID of the build\. + + `arn` represents the ARN of the build\. + + Make a note of the `id` value\. You need it in the next step\. + +## Next Step + +[Step 7: View Summarized Build Information](getting-started-cli-monitor-build.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 new file mode 100644 index 0000000..691dd60 --- /dev/null +++ b/doc_source/getting-started-cli-upload-source-code.md @@ -0,0 +1,36 @@ +# Step 4: Upload the Source Code and the Build Spec + +\(Previous step: [Step 3: Create the Build Spec](getting-started-cli-create-build-spec.md)\) + +In this step, you add the source code and build spec file to the input bucket\. + +Using your operating system's zip utility, create a file named `MessageUtil.zip` that includes `MessageUtil.java`, `TestMessageUtil.java`, `pom.xml`, and `buildspec.yml`\. + +The `MessageUtil.zip` file's directory structure must look like this\. + +``` +MessageUtil.zip + |-- pom.xml + |-- buildspec.yml + `-- src + |-- main + | `-- java + | `-- MessageUtil.java + `-- test + `-- java + `-- TestMessageUtil.java +``` + +**Important** +Do not include the `(root directory name)` directory, only the directories and files in the `(root directory name)` directory\. + +Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID-account-ID-input-bucket`\. + +**Important** +For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. +For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. +If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. + +## Next Step + +[Step 5: Create the Build Project](getting-started-cli-create-build-project.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md new file mode 100644 index 0000000..ab5531a --- /dev/null +++ b/doc_source/getting-started-cli.md @@ -0,0 +1,21 @@ +# Getting Started with CodeBuild Using the AWS CLI + +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 CodeBuild](how-to-create-pipeline.md)\. For information about using the AWS SDKs, see [Run AWS 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 Build Spec](getting-started-cli-create-build-spec.md) ++ [Step 4: Upload the Source Code and the Build Spec](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: Clean Up](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-project-console.md b/doc_source/getting-started-create-build-project-console.md new file mode 100644 index 0000000..8833729 --- /dev/null +++ b/doc_source/getting-started-create-build-project-console.md @@ -0,0 +1,51 @@ +# Step 5: Create the Build Project + +\(Previous step: [Step 4: Upload the Source Code and the Build Spec](getting-started-upload-source-code-console.md)\) + +In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. + +For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. + +**To create the build project** + +1. Sign in to the AWS Management Console and open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. + +1. Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. + +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**, for **Project name**, enter a name for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across each AWS account\. If you use a different name, be sure to use it throughout this tutorial\. +**Note** +On the **Create build project** page, you might see an error message similar to the following: **User: *user\-ARN* is not authorized to perform: codebuild:ListProjects**\. This is most likely because you signed in to the AWS Management Console as an IAM user who does not have sufficient permissions to use CodeBuild in the console\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: +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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. + +1. In **Source**, for **Source provider**, choose **Amazon S3**\. + +1. For **Bucket**, choose **codebuild\-*region\-ID*\-*account\-ID*\-input\-bucket**\. + +1. For **S3 object key**, enter **MessageUtil\.zip**\. + +1. In **Environment**, for **Environment image**, leave **Managed image** selected\. + +1. For **Operating system**, choose **Amazon Linux 2**\. + +1. For **Runtime\(s\)**, choose **Standard**\. + +1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. + +1. In **Service role**, leave **New service role** selected, and leave **Role name** unchanged\. + +1. For **Buildspec**, leave **Use a buildspec file** selected\. + +1. In **Artifacts**, for **Type**, choose **Amazon S3**\. + +1. For **Bucket name**, choose **codebuild\-*region\-ID*\-*account\-ID*\-output\-bucket**\. + +1. Leave **Name** and **Path** blank\. + +1. Choose **Create build project**\. + +## Next Step + +[Step 6: Run the Build](getting-started-run-build-console.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 new file mode 100644 index 0000000..77897e6 --- /dev/null +++ b/doc_source/getting-started-create-build-spec-console.md @@ -0,0 +1,63 @@ +# Step 3: Create the Build Spec + +\(Previous step: [Step 2: Create the Source Code](getting-started-create-source-code-console.md)\) + +In this step, you create a build specification \(build spec\) file\. A *build spec* 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\. + +Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. + +``` +version: 0.2 + +phases: + install: + runtime-versions: + java: corretto11 + pre_build: + commands: + - echo Nothing to do in the pre_build phase... + build: + commands: + - echo Build started on `date` + - mvn install + post_build: + commands: + - echo Build completed on `date` +artifacts: + files: + - target/messageUtil-1.0.jar +``` + +**Important** +Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. + +**Note** +Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + +In this build spec declaration: ++ `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. ++ `phases` represents the build phases during which you can instruct CodeBuild to run commands\. These build phases are listed here as `install`, `pre_build`, `build`, and `post_build`\. You cannot change the spelling of these build phase names, and you cannot create more build phase names\. + + In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. ++ `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. + +For more information, see the [Build Spec Reference](build-spec-ref.md)\. + +At this point, your directory structure should look like this\. + +``` +(root directory name) + |-- pom.xml + |-- buildspec.yml + `-- src + |-- main + | `-- java + | `-- MessageUtil.java + `-- test + `-- java + `-- TestMessageUtil.java +``` + +## Next Step + +[Step 4: Upload the Source Code and the Build Spec](getting-started-upload-source-code-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 new file mode 100644 index 0000000..83e06a9 --- /dev/null +++ b/doc_source/getting-started-create-source-code-console.md @@ -0,0 +1,122 @@ +# Step 2: Create the Source Code + +\(Previous step: [Step 1: Create Two S3 Buckets](getting-started-input-bucket-console.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\. + +1. In an empty directory on your local computer or instance, create this directory structure\. + + ``` + (root directory name) + `-- src + |-- main + | `-- java + `-- test + `-- java + ``` + +1. Using a text editor of your choice, create this file, name it `MessageUtil.java`, and then save it in the `src/main/java` directory\. + + ``` + public class MessageUtil { + private String message; + + public MessageUtil(String message) { + this.message = message; + } + + public String printMessage() { + System.out.println(message); + return message; + } + + public String salutationMessage() { + message = "Hi!" + message; + System.out.println(message); + return message; + } + } + ``` + + This class file creates as output the string of characters passed into it\. The `MessageUtil` constructor sets the string of characters\. The `printMessage` method creates the output\. The `salutationMessage` method outputs `Hi!` followed by the string of characters\. + +1. Create this file, name it `TestMessageUtil.java`, and then save it in the `/src/test/java` directory\. + + ``` + import org.junit.Test; + import org.junit.Ignore; + import static org.junit.Assert.assertEquals; + + public class TestMessageUtil { + + String message = "Robert"; + MessageUtil messageUtil = new MessageUtil(message); + + @Test + public void testPrintMessage() { + System.out.println("Inside testPrintMessage()"); + assertEquals(message,messageUtil.printMessage()); + } + + @Test + public void testSalutationMessage() { + System.out.println("Inside testSalutationMessage()"); + message = "Hi!" + "Robert"; + assertEquals(message,messageUtil.salutationMessage()); + } + } + ``` + + This class file sets the `message` variable in the `MessageUtil` class to `Robert`\. It then tests to see if the `message` variable was successfully set by checking whether the strings `Robert` and `Hi!Robert` appear in the output\. + +1. Create this file, name it `pom.xml`, and then save it in the root \(top level\) directory\. + + ``` + + 4.0.0 + org.example + messageUtil + 1.0 + jar + Message Utility Java Sample App + + + junit + junit + 4.11 + test + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.8.0 + + + + + ``` + + Apache Maven uses the instructions in this file to convert the `MessageUtil.java` and `TestMessageUtil.java` files into a file named `messageUtil-1.0.jar` and then run the specified tests\. + +At this point, your directory structure should look like this\. + +``` +(root directory name) + |-- pom.xml + `-- src + |-- main + | `-- java + | `-- MessageUtil.java + `-- test + `-- java + `-- TestMessageUtil.java +``` + +## Next Step + +[Step 3: Create the Build Spec](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 new file mode 100644 index 0000000..0776340 --- /dev/null +++ b/doc_source/getting-started-input-bucket-console.md @@ -0,0 +1,20 @@ +# Step 1: Create Two S3 Buckets + +\(Part of: [Getting Started with CodeBuild in the Console](getting-started.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\. ++ The other bucket \(the *output bucket*\) stores the build output\. In this tutorial, the name of this output bucket is `codebuild-region-ID-account-ID-output-bucket`\. + +If you chose different names for these buckets, be sure to use them throughout this tutorial\. + +These two buckets must be in the same AWS Region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, these buckets must also be in the US East \(Ohio\) Region\. + +For more information, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon Simple Storage Service User Guide*\. + +**Note** +Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a Build](planning.md)\. + +## Next Step + +[Step 2: Create the Source Code](getting-started-create-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 new file mode 100644 index 0000000..a1b4310 --- /dev/null +++ b/doc_source/getting-started-monitor-build-console.md @@ -0,0 +1,32 @@ +# Step 7: View Summarized Build Information + +\(Previous step: [Step 6: Run the Build](getting-started-run-build-console.md)\) + +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. On the build details page, in **Phase details**, the following build phases should be displayed, with **Succeeded** in the **Status** column: + + **SUBMITTED** + + **QUEUED** + + **PROVISIONING** + + **DOWNLOAD\_SOURCE** + + **INSTALL** + + **PRE\_BUILD** + + **BUILD** + + **POST\_BUILD** + + **UPLOAD\_ARTIFACTS** + + **FINALIZING** + + **COMPLETED** + + In **Build Status**, **Succeeded** should be displayed\. + + If you see **In Progress** instead, choose the refresh button\. + +1. Next to each build phase, the **Duration** value indicates how long the build phase lasted\. The **End time** value indicates when that build phase ended\. + +## Next Step + +[Step 8: View Detailed Build Information](getting-started-build-log-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-next-steps-console.md b/doc_source/getting-started-next-steps-console.md new file mode 100644 index 0000000..1e2830d --- /dev/null +++ b/doc_source/getting-started-next-steps-console.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..f82b344 --- /dev/null +++ b/doc_source/getting-started-output-console.md @@ -0,0 +1,29 @@ +# Step 9: Get the Build Output Artifact + +\(Previous step: [Step 8: View Detailed Build Information](getting-started-build-log-console.md)\) + +In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. + +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, in **Build Status**, choose the **View artifacts** link\. This opens the folder in Amazon S3 for the build output artifact\. \(If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\.\) + +1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. + +: + +**To get the build output artifact \(Amazon S3 console\)** + +1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. + +1. Open `codebuild-region-ID-account-ID-output-bucket`\. + +1. Open the `codebuild-demo-project` folder\. + +1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. + +## Next Step + +[Step 10: Clean Up](getting-started-clean-up-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-overview.md b/doc_source/getting-started-overview.md new file mode 100644 index 0000000..ebff61d --- /dev/null +++ b/doc_source/getting-started-overview.md @@ -0,0 +1,8 @@ +# Getting Started with CodeBuild + +In the following tutorials, you use AWS CodeBuild to build a collection of sample source code input files into a deployable version of the source code\. + +Both tutorials have the same input and results, but one uses the CodeBuild console and the other uses the AWS CLI\. You can choose to follow either or both\. + +**Important** +It is not recommended that you use your AWS root account to complete this tutorial\. \ 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 new file mode 100644 index 0000000..572efc4 --- /dev/null +++ b/doc_source/getting-started-run-build-console.md @@ -0,0 +1,19 @@ +# Step 6: Run the Build + +\(Previous step: [Step 5: Create the Build Project](getting-started-create-build-project-console.md)\) + +In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. + +**To run the build** + +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. In the list of build projects, choose **codebuild\-demo\-project**, and then choose **Start build**\. + +1. On the **Start build** page, choose **Start build**\. + +## Next Step + +[Step 7: View Summarized Build Information](getting-started-monitor-build-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-upload-source-code-console.md b/doc_source/getting-started-upload-source-code-console.md new file mode 100644 index 0000000..761f5eb --- /dev/null +++ b/doc_source/getting-started-upload-source-code-console.md @@ -0,0 +1,36 @@ +# Step 4: Upload the Source Code and the Build Spec + +\(Previous step: [Step 3: Create the Build Spec](getting-started-create-build-spec-console.md)\) + +In this step, you add the source code and build spec file to the input bucket\. + +Using your operating system's zip utility, create a file named `MessageUtil.zip` that includes `MessageUtil.java`, `TestMessageUtil.java`, `pom.xml`, and `buildspec.yml`\. + +The `MessageUtil.zip` file's directory structure must look like this\. + +``` +MessageUtil.zip + |-- pom.xml + |-- buildspec.yml + `-- src + |-- main + | `-- java + | `-- MessageUtil.java + `-- test + `-- java + `-- TestMessageUtil.java +``` + +**Important** +Do not include the `(root directory name)` directory, only the directories and files in the `(root directory name)` directory\. + +Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID-account-ID-input-bucket`\. + +**Important** +For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. +For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. +If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. + +## Next Step + +[Step 5: Create the Build Project](getting-started-create-build-project-console.md) \ No newline at end of file diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index 560d1e2..9d84969 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -1,707 +1,21 @@ -# Getting Started with CodeBuild +# Getting Started with CodeBuild in the Console -In this walkthrough, 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 walkthrough\. +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\. -**Important** -Completing this walkthrough may 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)\. - -**Topics** -+ [Step 1: Create or Use Amazon S3 Buckets to Store the Build Input and Output](#getting-started-input-bucket) -+ [Step 2: Create the Source Code to Build](#getting-started-create-source-code) -+ [Step 3: Create the Build Spec](#getting-started-create-build-spec) -+ [Step 4: Add the Source Code and the Build Spec to the Input Bucket](#getting-started-upload-source-code) -+ [Step 5: Create the Build Project](#getting-started-create-build-project) -+ [Step 6: Run the Build](#getting-started-run-build) -+ [Step 7: View Summarized Build Information](#getting-started-monitor-build) -+ [Step 8: View Detailed Build Information](#getting-started-build-log) -+ [Step 9: Get the Build Output Artifact](#getting-started-output) -+ [Step 10: Clean Up](#getting-started-clean-up) -+ [Next Steps](#getting-started-next-steps) - -## Step 1: Create or Use Amazon S3 Buckets to Store the Build Input and Output - -To complete this walkthrough, you need two Amazon S3 buckets: -+ One of these buckets stores the build input \(the *input bucket*\)\. In this walkthrough, we name this input bucket `codebuild-region-ID-account-ID-input-bucket`, where *region\-ID* represents the AWS Region of the bucket, and *account\-ID* represents your AWS account ID\. -+ The other bucket stores the build output \(the *output bucket*\)\. In this walkthrough, we name this output bucket `codebuild-region-ID-account-ID-output-bucket`\. - -If you chose a different name for either of these buckets, be sure to use it throughout this walkthrough\. - -These two buckets must be in the same AWS Region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, then these buckets must also be in the US East \(Ohio\) Region\. - -To create a bucket, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/CreatingaBucket.html) in the *Amazon Simple Storage Service User Guide*\. - -**Note** -You can use a single bucket for this walkthrough, but using two buckets makes it easier to see where the build input is coming from and where the build output is going\. -Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this walkthrough does not show you how to use them\. For more information, see [Plan a Build](planning.md)\. - -## Step 2: Create the Source Code to Build - -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\. - -1. In an empty directory on your local computer or instance, create this directory structure\. - - ``` - (root directory name) - `-- src - |-- main - | `-- java - `-- test - `-- java - ``` - -1. Using a text editor of your choice, create this file, name it `MessageUtil.java`, and then save it in the `src/main/java` directory\. - - ``` - public class MessageUtil { - private String message; - - public MessageUtil(String message) { - this.message = message; - } - - public String printMessage() { - System.out.println(message); - return message; - } - - public String salutationMessage() { - message = "Hi!" + message; - System.out.println(message); - return message; - } - } - ``` - - This class file creates as output the string of characters passed into it\. The `MessageUtil` constructor sets the string of characters\. The `printMessage` method creates the output\. The `salutationMessage` method outputs `Hi!` followed by the string of characters\. - -1. Create this file, name it `TestMessageUtil.java`, and then save it in the `/src/test/java` directory\. - - ``` - import org.junit.Test; - import org.junit.Ignore; - import static org.junit.Assert.assertEquals; - - public class TestMessageUtil { - - String message = "Robert"; - MessageUtil messageUtil = new MessageUtil(message); - - @Test - public void testPrintMessage() { - System.out.println("Inside testPrintMessage()"); - assertEquals(message,messageUtil.printMessage()); - } - - @Test - public void testSalutationMessage() { - System.out.println("Inside testSalutationMessage()"); - message = "Hi!" + "Robert"; - assertEquals(message,messageUtil.salutationMessage()); - } - } - ``` - - This class file sets the `message` variable in the `MessageUtil` class to `Robert`\. It then tests to see if the `message` variable was successfully set by checking whether the strings `Robert` and `Hi!Robert` appear in the output\. - -1. Create this file, name it `pom.xml`, and then save it in the root \(top level\) directory\. - - ``` - - 4.0.0 - org.example - messageUtil - 1.0 - jar - Message Utility Java Sample App - - - junit - junit - 4.11 - test - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.8.0 - - - - - ``` - - Apache Maven uses the instructions in this file to convert the `MessageUtil.java` and `TestMessageUtil.java` files into a file named `messageUtil-1.0.jar` and then run the specified tests\. - -At this point, your directory structure should look like this\. - -``` -(root directory name) - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -## Step 3: Create the Build Spec - -In this step, you create a build specification \(build spec\) file\. A *build spec* 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\. - -Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. - -``` -version: 0.2 - -phases: - install: - runtime-versions: - java: corretto11 - pre_build: - commands: - - echo Nothing to do in the pre_build phase... - build: - commands: - - echo Build started on `date` - - mvn install - post_build: - commands: - - echo Build completed on `date` -artifacts: - files: - - target/messageUtil-1.0.jar -``` - -**Important** -Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. - -**Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. - -In this build spec declaration: -+ `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. -+ `phases` represents the build phases during which you can instruct CodeBuild to run commands\. These build phases are listed here as `install`, `pre_build`, `build`, and `post_build`\. You cannot change the spelling of these build phase names, and you cannot create more build phase names\. - - In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this walkthrough, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. -+ `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. - -For more information, see the [Build Spec Reference](build-spec-ref.md)\. - -At this point, your directory structure should look like this\. - -``` -(root directory name) - |-- pom.xml - |-- buildspec.yml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -## Step 4: Add the Source Code and the Build Spec to the Input Bucket - -In this step, you add the source code and build spec file to the input bucket\. - -Using your operating system's zip utility, create a file named `MessageUtil.zip` that includes `MessageUtil.java`, `TestMessageUtil.java`, `pom.xml`, and `buildspec.yml`\. - -The `MessageUtil.zip` file's directory structure must look like this\. - -``` -MessageUtil.zip - |-- pom.xml - |-- buildspec.yml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -**Important** -Do not include the `(root directory name)` directory, only the directories and files in the `(root directory name)` directory\. - -Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID-account-ID-input-bucket`\. +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 CodeBuild](how-to-create-pipeline.md)\. For information about using the AWS SDKs, see [Run AWS CodeBuild Directly](how-to-run.md)\. **Important** -For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. -For build input stored in Amazon S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. - -## Step 5: Create the Build Project - -In this step, you create a build project that AWS CodeBuild uses to run the build\. A *build project* defines how CodeBuild runs a build\. It includes information such as where to get the source code, the build environment to use, the 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\. The build environment is expressed as a Docker image\. \(For more information, see the [Docker Overview](https://docs.docker.com/engine/docker-overview/) topic on the Docker Docs website\.\) For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. - -You can use the [CodeBuild console](#getting-started-create-build-project-console) or [AWS CLI](#getting-started-create-build-project-cli) to complete this step\. - -**Note** -You can work with CodeBuild in several ways: through the CodeBuild console, AWS CodePipeline, the AWS CLI, or the AWS SDKs\. This walkthrough demonstrates how to use the CodeBuild console and the AWS CLI\. To learn how to use CodePipeline, see [Use AWS CodePipeline with CodeBuild](how-to-create-pipeline.md)\. To learn how to use the AWS SDKs, see [Run AWS CodeBuild Directly](how-to-run.md)\. - -**To create the build project \(console\)** - -1. Sign in to the AWS Management Console and 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 AWS region selector, choose a region that supports CodeBuild\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the "Regions and Endpoints" topic in the *Amazon Web Services General Reference*\. - -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**, for **Project name**, enter a name for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across each AWS account\. If you use a different name, be sure to use it throughout this walkthrough\. -**Note** -On the **Create build project** page, you might see an error message similar to the following: **User: *user\-ARN* is not authorized to perform: codebuild:ListProjects**\. This is most likely because you signed in to the AWS Management Console as an IAM user that does not have sufficient permissions to use CodeBuild in the console\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: -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 the AWS managed policies named **AWSCodeBuildAdminAccess**, **AmazonS3ReadOnlyAccess**, and **IAMFullAccess** attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. - -1. In **Source**, for **Source provider**, choose **Amazon S3**\. - -1. For **Bucket**, choose **codebuild\-*region\-ID*\-*account\-ID*\-input\-bucket**\. - -1. For **S3 object key**, enter **MessageUtil\.zip**\. - -1. In **Environment**, for **Environment image**, leave **Managed image** selected\. - -1. For **Operating system**, choose **Amazon Linux 2**\. - -1. For **Runtime\(s\)**, choose **Standard**\. - -1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. - -1. In **Service role**, leave **New service role** selected, and leave **Role name** unchanged\. - -1. For **Buildspec**, leave **Use a buildspec file** selected\. - -1. In **Artifacts**, for **Type**, choose **Amazon S3**\. - -1. For **Bucket name**, choose **codebuild\-*region\-ID*\-*account\-ID*\-output\-bucket**\. - -1. Leave **Name** and **Path** blank\. - -1. Choose **Create build project**\. - - Skip ahead to [Step 6: Run the Build](#getting-started-run-build)\. - -**To create the build project \(AWS CLI\)** - -1. Use the AWS CLI to 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 named `create-project.json` in a location on the local computer or instance where the AWS CLI is installed\. If you choose to use a different file name, be sure to use it throughout this walkthrough\. - - Modify the copied data to follow this format, and then save your results: - - ``` - { - "name": "codebuild-demo-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "artifacts": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", - "computeType": "BUILD_GENERAL1_SMALL" - }, - "serviceRole": "serviceIAMRole" - } - ``` - - Replace *serviceIAMRole* with the Amazon Resource Name \(ARN\) of a CodeBuild service role \(for example, `arn:aws:iam::account-ID:role/role-name`\)\. To create one, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. - - In this data: - + `name` represents a required identifier for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across all build projects in your account\. - + For `source`, `type` is a required value that represents the source code's repository type \(in this example, `S3` for an Amazon S3 bucket\)\. - + 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:2.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\. - - 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`\)\. -**Note** -Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this walkthrough, so they are not shown here\. For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. - -1. Switch to the directory that contains the file you just saved, and then run the create\-project command again\. - - ``` - aws codebuild create-project --cli-input-json file://create-project.json - ``` - - If successful, data similar to this appears in the output\. - - ``` - { - "project": { - "name": "codebuild-demo-project", - "serviceRole": "serviceIAMRole", - "tags": [], - "artifacts": { - "packaging": "NONE", - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket", - "name": "message-util.zip" - }, - "lastModified": 1472661575.244, - "timeoutInMinutes": 60, - "created": 1472661575.244, - "environment": { - "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:2.0", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "encryptionKey": "arn:aws:kms:region-ID:account-ID:alias/aws/s3", - "arn": "arn:aws:codebuild:region-ID:account-ID:project/codebuild-demo-project" - } - } - ``` - + `project` represents information about this build project\. - + `tags` represents any tags that were declared\. - + `packaging` represents how the build output artifact is stored in the output bucket\. `NONE` means that a folder is created in the output bucket\. The build output artifact is stored in that folder\. - + `lastModified` represents the time, in Unix time format, when information about the build project was last changed\. - + `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\. - + `arn` represents the ARN of the build project\. - -**Note** -After you run the create\-project command, an error message similar to the following might be output: **User: *user\-ARN* is not authorized to perform: codebuild:CreateProject**\. This is most likely because you configured the AWS CLI with the credentials of an IAM user that does not have sufficient permissions to use CodeBuild to create build projects\. To fix this, configure the AWS CLI with credentials belonging to one of the following IAM entities: -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 the AWS managed policies named **AWSCodeBuildAdminAccess**, **AmazonS3ReadOnlyAccess**, and **IAMFullAccess** attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. - -## Step 6: Run the Build - -In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. - -You can use the [CodeBuild console](#getting-started-run-build-console) or [AWS CLI](#getting-started-run-build-cli) to complete this step\. - -**To run the 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. 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. Skip ahead to [Step 7: View Summarized Build Information](#getting-started-monitor-build)\. - -**To run the build \(AWS CLI\)** - -1. Use the AWS CLI to run the start\-build command: - - ``` - aws codebuild start-build --project-name project-name - ``` - - Replace *project\-name* with your build project name from the previous step \(for example, `codebuild-demo-project`\)\. - -1. If successful, data similar to the following appears in the output: - - ``` - { - "build": { - "buildComplete": false, - "buildNumber": 1, - "initiator": "user-name", - "artifacts": { - "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip" - }, - "projectName": "codebuild-demo-project", - "timeoutInMinutes": 60, - "buildStatus": "IN_PROGRESS", - "environment": { - "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:2.0", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "currentPhase": "SUBMITTED", - "startTime": 1472848787.882, - "id": "codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE", - "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE" - } - } - ``` - + `build` represents information about this build\. - + `buildComplete` represents whether the build was completed \(`true`\); otherwise, `false`\. - + `buildNumber` represents the build number for the CodeBuild build project\. The first build is number 1\. For each build run, `buildNumber` is incremented by 1\. - + `initiator` represents the entity that started the build\. - + `artifacts` represents information about the build output, including its location\. - + `projectName` represents the name of the build project\. - + `buildStatus` represents the current build status when the start\-build command was run\. - + `currentPhase` represents the current build phase when the start\-build command was run\. - + `startTime` represents the time, in Unix time format, when the build process started\. - + `id` represents the ID of the build\. - + `arn` represents the ARN of the build\. - - Make a note of the `id` value\. You need it in the next step\. - -## Step 7: View Summarized Build Information - -In this step, you view summarized information about the status of your build\. - -You can use the [AWS CodeBuild console](#getting-started-monitor-build-console) or the [AWS CLI](#getting-started-monitor-build-cli) to complete this step\. - -### To view summarized build information \(console\) - -1. If the **codebuild\-demo\-project:*build\-ID*** page is not displayed, then 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 walkthrough before, choose the link in the **Completed** column for the most recent value\.\) - -1. On the build details page, in **Phase details**, the following list of build phases should be displayed, with **Succeeded** in the **Status** column: - + **SUBMITTED** - + **QUEUED** - + **PROVISIONING** - + **DOWNLOAD\_SOURCE** - + **INSTALL** - + **PRE\_BUILD** - + **BUILD** - + **POST\_BUILD** - + **UPLOAD\_ARTIFACTS** - + **FINALIZING** - + **COMPLETED** - - In **Build Status**, **Succeeded** should be displayed\. - - If you see **In Progress** instead, choose the refresh button to see the latest progress\. - -1. Next to each build phase, the **Duration** value indicates how long that build phase lasted\. The **End time** value indicates when that build phase ended\. - - Skip ahead to [Step 8: View Detailed Build Information](#getting-started-build-log)\. - -### To view summarized build information \(AWS CLI\) - -Use the AWS CLI to run the batch\-get\-builds command\. - -``` -aws codebuild batch-get-builds --ids id -``` - -Replace *id* with the `id` value that appeared in the output of the previous step\. - -If successful, data similar to this appears in the output\. - -``` -{ - "buildsNotFound": [], - "builds": [ - { - "buildComplete": true, - "buildNumber": 1, - "phases": [ - { - "phaseStatus": "SUCCEEDED", - "endTime": 1472848788.525, - "phaseType": "SUBMITTED", - "durationInSeconds": 0, - "startTime": 1472848787.882 - }, - ... The full list of build phases has been omitted for brevity ... - { - "phaseType": "COMPLETED", - "startTime": 1472848878.079 - } - ], - "logs": { - "groupName": "/aws/codebuild/codebuild-demo-project", - "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE", - "streamName": "38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE" - }, - "artifacts": { - "md5sum": "MD5-hash", - "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip", - "sha256sum": "SHA-256-hash" - }, - "projectName": "codebuild-demo-project", - "timeoutInMinutes": 60, - "initiator": "user-name", - "buildStatus": "SUCCEEDED", - "environment": { - "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:2.0", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "currentPhase": "COMPLETED", - "startTime": 1472848787.882, - "endTime": 1472848878.079, - "id": "codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE", - "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE" - } - ] -} -``` -+ `buildsNotFound` represents the build IDs for any builds where information is not available\. In this example, it should be empty\. -+ `builds` represents information about each build where information is available\. In this example, information about only one build appears in the output\. - + `phases` represents the set of build phases CodeBuild runs during the build process\. Information about each build phase is listed separately as `startTime`, `endTime`, and `durationInSeconds` \(when the build phase started and ended, expressed in Unix time format, and how long it lasted, in seconds\), and `phaseType` such as \(`SUBMITTED`, `PROVISIONING`, `DOWNLOAD_SOURCE`, `INSTALL`, `PRE_BUILD`, `BUILD`, `POST_BUILD`, `UPLOAD_ARTIFACTS`, `FINALIZING`, or `COMPLETED`\) and `phaseStatus` \(such as `SUCCEEDED`, `FAILED`, `FAULT`, `TIMED_OUT`, `IN_PROGRESS`, or `STOPPED`\)\. The first time you run the batch\-get\-builds command, there might not be many \(or any\) phases\. After subsequent runs of the batch\-get\-builds command with the same build ID, more build phases should appear in the output\. - + `logs` represents information in Amazon CloudWatch Logs about the build's logs\. - + `md5sum` and `sha256sum` represent MD5 and SHA\-256 hashes of the build's output artifact\. These appear in the output only if the build project's `packaging` value is set to `ZIP`\. \(You did not set this value in this walkthrough\.\) You can use these hashes along with a checksum tool to confirm file integrity and authenticity\. -**Note** -You can also use the Amazon S3 console to view these hashes\. Select the box next to the build output artifact, and then choose **Actions**, **Properties**\. In the **Properties** pane, expand **Metadata**, and view the values for **x\-amz\-meta\-codebuild\-content\-md5** and **x\-amz\-meta\-codebuild\-content\-sha256**\. \(In the Amazon S3 console, the build output artifact's **ETag** value should not be interpreted to be either the MD5 or SHA\-256 hash\.\) -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\. - -## Step 8: View Detailed Build Information - -In this step, you view detailed information about your build in CloudWatch Logs\. - -You can use the [CodeBuild console](#getting-started-build-log-console) or [AWS CLI](#getting-started-build-log-cli) to complete this step\. - -**To view detailed build information \(console\)** - -1. With the build details page still displayed from the previous step, the last 10,000 lines of the build log are displayed in **Build logs**\. To see the entire build log in CloudWatch Logs, choose the **View entire log** link\. - -1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. - -1. In this walkthrough, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in the **Filter events** box, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. - -Skip ahead to [Step 9: Get the Build Output Artifact](#getting-started-output)\. - -**To view detailed build information \(AWS CLI\)** - -1. Use your web browser to go to the `deepLink` location that appeared in the output in the previous step \(for example, `https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE`\)\. - -1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. - -1. In this walkthrough, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in the **Filter events** box, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. - -These portions of a CloudWatch Logs log stream pertain to this walkthrough\. - -``` -... -[Container] 2016/04/15 17:49:42 Entering phase PRE_BUILD -[Container] 2016/04/15 17:49:42 Running command echo Entering pre_build phase... -[Container] 2016/04/15 17:49:42 Entering pre_build phase... -[Container] 2016/04/15 17:49:42 Phase complete: PRE_BUILD Success: true -[Container] 2016/04/15 17:49:42 Entering phase BUILD -[Container] 2016/04/15 17:49:42 Running command echo Entering build phase... -[Container] 2016/04/15 17:49:42 Entering build phase... -[Container] 2016/04/15 17:49:42 Running command mvn install -[Container] 2016/04/15 17:49:44 [INFO] Scanning for projects... -[Container] 2016/04/15 17:49:44 [INFO] -[Container] 2016/04/15 17:49:44 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:44 [INFO] Building Message Utility Java Sample App 1.0 -[Container] 2016/04/15 17:49:44 [INFO] ------------------------------------------------------------------------ -... -[Container] 2016/04/15 17:49:55 ------------------------------------------------------- -[Container] 2016/04/15 17:49:55 T E S T S -[Container] 2016/04/15 17:49:55 ------------------------------------------------------- -[Container] 2016/04/15 17:49:55 Running TestMessageUtil -[Container] 2016/04/15 17:49:55 Inside testSalutationMessage() -[Container] 2016/04/15 17:49:55 Hi!Robert -[Container] 2016/04/15 17:49:55 Inside testPrintMessage() -[Container] 2016/04/15 17:49:55 Robert -[Container] 2016/04/15 17:49:55 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 sec -[Container] 2016/04/15 17:49:55 -[Container] 2016/04/15 17:49:55 Results : -[Container] 2016/04/15 17:49:55 -[Container] 2016/04/15 17:49:55 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 -... -[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:56 [INFO] BUILD SUCCESS -[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:56 [INFO] Total time: 11.845 s -[Container] 2016/04/15 17:49:56 [INFO] Finished at: 2016-04-15T17:49:56+00:00 -[Container] 2016/04/15 17:49:56 [INFO] Final Memory: 18M/216M -[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:56 Phase complete: BUILD Success: true -[Container] 2016/04/15 17:49:56 Entering phase POST_BUILD -[Container] 2016/04/15 17:49:56 Running command echo Entering post_build phase... -[Container] 2016/04/15 17:49:56 Entering post_build phase... -[Container] 2016/04/15 17:49:56 Phase complete: POST_BUILD Success: true -[Container] 2016/04/15 17:49:57 Preparing to copy artifacts -[Container] 2016/04/15 17:49:57 Assembling file list -[Container] 2016/04/15 17:49:57 Expanding target/messageUtil-1.0.jar -[Container] 2016/04/15 17:49:57 Found target/messageUtil-1.0.jar -[Container] 2016/04/15 17:49:57 Creating zip artifact -``` - -In this example, CodeBuild successfully completed the pre\-build, build, and post\-build build phases\. It ran the unit tests and successfully built the `messageUtil-1.0.jar` file\. - -## Step 9: Get the Build Output Artifact - -In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. - -You can use the [CodeBuild console](#getting-started-output-console) or [Amazon S3 console](#getting-started-output-s3) to complete this step\. - -**To get the build output artifact \(CodeBuild console\)** - -1. With the CodeBuild console still open and the build details page still displayed from the previous step, in **Build Status**, choose the **View artifacts** link\. This opens the folder in Amazon S3 for the build output artifact\. \(If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\.\) - -1. Open the folder named `target`, where you find the build output artifact file named `messageUtil-1.0.jar`\. - - Skip ahead to [Step 10: Clean Up](#getting-started-clean-up)\. - -**To get the build output artifact \(Amazon S3 console\)** - -1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. - -1. Open the bucket named `codebuild-region-ID-account-ID-output-bucket`\. - -1. Open the folder named `codebuild-demo-project`\. - -1. Open the folder named `target`, where you find the build output artifact file named `messageUtil-1.0.jar`\. - -## Step 10: Clean Up - -To prevent ongoing charges to your AWS account, you can delete the input bucket used in this walkthrough\. 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*\. - -If you are using the IAM user to delete this bucket instead of an AWS root account or an administrator IAM user, the user must have additional access permissions\. \(Using an AWS root account is not recommended\.\) Add the following statement between the markers \(*\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENTS HERE \#\#\#*\) to an existing access policy for the user\. Ellipses \(`...`\) are used for brevity\. Do not remove any statements in the existing access policy\. Do not enter these ellipses into the policy\. - -``` -{ - "Version": "2012-10-17", - "Id": "...", - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Effect": "Allow", - "Action": [ - "s3:DeleteBucket", - "s3:DeleteObject" - ], - "Resource": "*" - } - ### END ADDING STATEMENT HERE ### - ] -} -``` - -## Next Steps - -In this walkthrough, 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 by following 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 +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-input-bucket-console.md) ++ [Step 2: Create the Source Code](getting-started-create-source-code-console.md) ++ [Step 3: Create the Build Spec](getting-started-create-build-spec-console.md) ++ [Step 4: Upload the Source Code and the Build Spec](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: Clean Up](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/history.md b/doc_source/history.md index de70f60..7f611c5 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **December 13, 2019 ++ **Latest documentation update: **December 23, 2019 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/index.md b/doc_source/index.md index b949042..617406a 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -16,7 +16,31 @@ Amazon's trademarks and trade dress may not be used in ## Contents + [What Is AWS CodeBuild?](welcome.md) + [AWS CodeBuild Concepts](concepts.md) -+ [Getting Started with CodeBuild](getting-started.md) ++ [Getting Started with CodeBuild](getting-started-overview.md) + + [Getting Started with CodeBuild in 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 Build Spec](getting-started-create-build-spec-console.md) + + [Step 4: Upload the Source Code and the Build Spec](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: Clean Up](getting-started-clean-up-console.md) + + [Wrapping Up](getting-started-next-steps-console.md) + + [Getting Started with 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 Build Spec](getting-started-cli-create-build-spec.md) + + [Step 4: Upload the Source Code and the Build Spec](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: Clean Up](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) diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index d84d71e..51af290 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -144,7 +144,7 @@ aws codebuild delete-resource-policy --resource-arn project-arn Owners and consumers can use the AWS CLI to identify shared projects\. **To identify projects shared with your AWS account or user \(AWS CLI\)** -Use the [list\-shared\-project](https://docs.aws.amazon.com/cli/latest/reference/ram/list-shared-project.html) command to return the projects that are shared with you\. +Use the [list\-shared\-projects](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-shared-projects.html) command to return the projects that are shared with you\. ## Shared Project Permissions diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 96c1b68..4aac929 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -214,7 +214,7 @@ The value in the build spec declaration takes lowest precedence\. aws codebuild start-build --cli-input-json file://start-build.json ``` -1. If successful, data similar to that described in the [To run the build \(AWS CLI\)](getting-started.md#getting-started-run-build-cli) procedure appears in the output\. +1. If successful, data similar to that described in the [To run the build](getting-started-cli-run-build.md#getting-started-run-build-cli) procedure appears in the output\. To work with detailed information about this build, make a note of the `id` value in the output, and then see [View Build Details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index d07ed4d..4ed8bb4 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -17,7 +17,7 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, **Important** Updating your project source might affect the accuracy of the project's build badges\. **Note** - CodeBuild does not support build badges with the S3 source provider\. Because AWS CodePipeline uses S3 for artifact transfers, build badges are not supported for build projects that are part of a CodePipeline pipeline\. + CodeBuild does not support build badges with the S3 source provider\. Because AWS CodePipeline uses S3 for artifact transfers, build badges are not supported for build projects that are part of a CodePipeline pipeline 1. In **Environment**: @@ -76,4 +76,4 @@ Sample markdown code: + **PASSING** The most recent build on the given branch passed\. + **FAILING** The most recent build on the given branch timed out, failed, faulted, or was stopped\. + **IN\_PROGRESS** The most recent build on the given branch is in progress\. -+ **UNKNOWN** The project has not yet run a build for the given branch or at all\. Also, the build badges feature might have been disabled\. ++ **UNKNOWN** The project has not yet run a build for the given branch or at all\. Also, the build badges feature might have been disabled\. \ No newline at end of file diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 0a0a05a..0e34f84 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -258,8 +258,8 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +### Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index f1c00b5..c7d1189 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +## Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index deb3918..0446f8d 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w47aac11c41c34c17) ++ [Related Resources](#w48aac11c41c34c17) ## Running the Sample @@ -97,7 +97,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +## Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index c51e90b..4781859 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w47aac11c41c19c23) ++ [Related Resources](#w48aac11c41c19c23) ## Running the Sample @@ -305,7 +305,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +## Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 5f632ca..aabef48 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +## Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index d9e8d8f..9886947 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +## Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index 20ef089..d02a246 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild](getting-started.md)\. +## Related Resources ++ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 62995cb..4e05f37 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -41,7 +41,7 @@ java: openjdk11 ``` - 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 1\.0: + 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: ``` diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index 320405e..b6d6ace 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -1,6 +1,6 @@ # Advanced Setup -If you follow the steps in [Getting Started](getting-started.md) to access AWS CodeBuild for the first time, most likely you will not need to reference the information in this topic\. However, as you continue using CodeBuild, you will 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 in the Console](getting-started.md) to access AWS CodeBuild for the first time, most likely you will not need to reference the information in this topic\. However, as you continue using CodeBuild, you will 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\. 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\. diff --git a/doc_source/view-build-details.md b/doc_source/view-build-details.md index 3f0381e..727a39d 100644 --- a/doc_source/view-build-details.md +++ b/doc_source/view-build-details.md @@ -39,7 +39,7 @@ For example, if you run this command: aws codebuild batch-get-builds --ids codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE my-other-project:813bb6c6-891b-426a-9dd7-6d8a3EXAMPLE ``` -If the command is successful, data similar to that described in [To view summarized build information \(AWS CLI\)](getting-started.md#getting-started-monitor-build-cli) appears in the output\. +If the command is successful, data similar to that described in [To view summarized build information ](getting-started-cli-monitor-build.md#getting-started-cli-monitor-build-cli) appears in the output\. ## View Build Details \(AWS SDKs\) diff --git a/doc_source/welcome.md b/doc_source/welcome.md index 322b1e4..fd84949 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -41,6 +41,6 @@ We recommend that you complete the following steps: 1. **Learn** more about CodeBuild by reading the information in [Concepts](concepts.md)\. -1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting Started](getting-started.md)\. +1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting Started in the Console](getting-started.md)\. 1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a Build](planning.md)\. \ No newline at end of file diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 62960ae..470966c 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -1,6 +1,6 @@ # Working with Build Projects -A *build project* defines how CodeBuild runs a build\. It includes information such as where to get the source code, the build environment to use, the build commands to run, and where to store the build output\. +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\. You can perform these tasks when working with build projects: From af6a6e72b0bf8634bc914bb444614231c2ff1cba Mon Sep 17 00:00:00 2001 From: Joe Bowbeer Date: Tue, 14 Jan 2020 13:19:25 -0800 Subject: [PATCH 025/156] Update test-report-group-naming.md s/using using/using/ --- doc_source/test-report-group-naming.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/test-report-group-naming.md b/doc_source/test-report-group-naming.md index 865c62d..d05db0e 100644 --- a/doc_source/test-report-group-naming.md +++ b/doc_source/test-report-group-naming.md @@ -5,7 +5,7 @@ | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - When you use the AWS CLI or the AWS CodeBuild console to create a report group, you specify a name for the report group\. If you use the buildspec to create a new report group, it is named using using the format `project-name-report-group-name-specified-in-buildspec`\. All reports created by running builds of that build project belong to the new report group that has the new name\. + When you use the AWS CLI or the AWS CodeBuild console to create a report group, you specify a name for the report group\. If you use the buildspec to create a new report group, it is named using the format `project-name-report-group-name-specified-in-buildspec`\. All reports created by running builds of that build project belong to the new report group that has the new name\. If you do not want CodeBuild to create a new report group, specify the ARN of the report group in a build project's buildspec file\. You can specify a report group's ARN in multiple build projects\. After each build project runs, the report group contains test reports created by each build project\. @@ -16,4 +16,4 @@ If you use the ARN of the report group named `my-report-group` in both projects, and then run builds of each project, you still have one report group \(`my-report-group`\)\. That report group contains test reports with results of tests run by both build projects\. - If you a choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. \ No newline at end of file + If you a choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. From 203df65ab909e6e717d183f347fbbc570514594c Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Fri, 14 Feb 2020 18:18:56 +0000 Subject: [PATCH 026/156] Periodic update, Feb 14, 2020 --- doc_source/build-caching.md | 10 +- doc_source/build-env-ref-available.md | 16 +- doc_source/build-env-ref-cmd.md | 14 +- doc_source/build-env-ref-compute-types.md | 5 +- doc_source/build-env-ref-env-vars.md | 4 +- doc_source/build-spec-ref.md | 78 +++---- doc_source/change-project.md | 18 +- doc_source/cloudformation-vpc-template.md | 2 +- doc_source/cloudtrail.md | 6 + doc_source/concepts.md | 4 +- doc_source/create-project.md | 207 ++++++++++-------- doc_source/data-protection.md | 5 + doc_source/delete-builds.md | 4 +- .../getting-started-build-log-console.md | 8 +- doc_source/getting-started-cli-build-log.md | 8 +- ...etting-started-cli-create-build-project.md | 4 +- .../getting-started-cli-create-build-spec.md | 8 +- .../getting-started-cli-create-source-code.md | 2 +- .../getting-started-cli-upload-source-code.md | 6 +- doc_source/getting-started-cli.md | 4 +- ...ng-started-create-build-project-console.md | 4 +- ...tting-started-create-build-spec-console.md | 8 +- ...ting-started-create-source-code-console.md | 2 +- ...ting-started-upload-source-code-console.md | 6 +- doc_source/getting-started.md | 4 +- doc_source/history.md | 18 +- doc_source/how-to-create-pipeline.md | 4 +- doc_source/index.md | 14 +- doc_source/planning.md | 4 +- doc_source/report-group-export-settings.md | 27 +-- doc_source/run-build.md | 14 +- doc_source/sample-build-badges.md | 4 +- doc_source/sample-build-notifications.md | 24 +- doc_source/sample-codedeploy.md | 2 +- .../sample-disable-artifact-encryption.md | 6 +- doc_source/sample-docker-custom-image.md | 6 +- doc_source/sample-docker.md | 12 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-efs.md | 104 +++++---- doc_source/sample-elastic-beanstalk.md | 8 +- doc_source/sample-github-enterprise.md | 20 +- doc_source/sample-github-pull-request.md | 6 +- doc_source/sample-lambda.md | 2 +- .../sample-pipeline-multi-input-output.md | 2 +- doc_source/sample-runtime-versions.md | 4 +- doc_source/sample-source-version.md | 2 +- doc_source/sample-test-report-cli.md | 8 +- .../test-report-group-create-buildspec.md | 2 +- doc_source/test-report-group-create-cfn.md | 2 +- doc_source/test-report-group-create-cli.md | 4 +- doc_source/test-report-group-naming.md | 2 +- doc_source/test-report-group.md | 2 +- doc_source/test-report.md | 2 +- doc_source/troubleshooting.md | 16 +- doc_source/use-proxy-server.md | 2 +- doc_source/vpc-support.md | 20 +- doc_source/welcome.md | 2 +- 57 files changed, 426 insertions(+), 358 deletions(-) diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 67825a1..25d2b04 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -3,7 +3,7 @@ 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\. +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\. **Topics** + [Amazon S3 Caching](#caching-s3) @@ -20,12 +20,13 @@ Docker layer cache mode is available for the Linux environment only\. If you cho + 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\. + 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 are overriden if a source item has the same name\. Directories are specified using cache paths in the buildspec file\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + Cached directories are linked to your build before it downloads its project sources\. Cached items are overriden if a source item has 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)\. **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)\. @@ -104,4 +105,7 @@ CodeBuildProject: - LOCAL_SOURCE_CACHE ``` +**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\. + For more information, see [Create a Build Project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. \ No newline at end of file diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index d9ee774..d8aa1bb 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -13,9 +13,9 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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) | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | - The latest version of each images 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.0-1.0.0`\. + 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.0-1.0.0`\. - The standard image of the Ubuntu 18\.04 and Amazon Linux 2 platforms contain the following runtimes\. If you use the Amazon Linux 2 standard image 1\.0 or the Ubuntu standard image 2\.0, you must specify your runtime in the `runtime-versions` section of your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](build-spec-ref.md#runtime-versions-buildspec-file)\. + The standard image of the Ubuntu 18\.04 and Amazon Linux 2 platforms contain the following runtimes\. If you use the Amazon Linux 2 standard image 1\.0 or later or the Ubuntu standard image 2\.0 or later, you must specify your runtime in the `runtime-versions` section of your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](build-spec-ref.md#runtime-versions-buildspec-file)\. | Runtime name | Version/versions | How to specify in the buildspec file | @@ -24,12 +24,14 @@ AWS CodeBuild manages the following Docker images that are available in the Code | docker | 18 | docker: 18 | | dotnet | 2\.2 | dotnet: 2\.2 | | dotnet \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 3\.0 | dotnet: 3\.0 | +| dotnet | 3\.1 | dotnet: 3\.1 | | golang | 1\.12, 1\.13 | golang: 1\.12, golang: 1\.13 | | nodejs | 8, 10 | nodejs: 8, nodejs: 10 | -| nodejs \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 10, 12 | nodejs: 10, nodejs: 12 | +| nodejs \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 10\.18, 12\.14 | nodejs: 10, nodejs: 12 | | java \(Ubuntu only\) | openjdk8, openjdk11 | java: openjdk8, java: openjdk11 | | java \(Amazon Linux 2 only\) | corretto8, corretto11 | java: corretto8, java: corretto11 | | php | 7\.3 | php: 7\.3 | +| php | 7\.4 | php: 7\.4 | | python | 3\.7 | python: 3\.7 | | python \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 3\.8 | python: 3\.8 | | ruby | 2\.6 | ruby: 2\.6 | @@ -42,18 +44,18 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the | Runtime name | Version in `windows-base:2.0` | | --- | --- | -| dotnet | 2\.2 | +| dotnet | 2\.2, 3\.1 | | golang | 1\.13 | -| nodejs | 10\.16 | +| nodejs | 10\.18, 12\.14 | | java | openjdk11 | -| php | 7\.3 | +| php | 7\.3, 7\.4 | | python | 3\.7 | | ruby | 2\.6 | **Note** The base image of the Windows Server Core 2016 platform is 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 [Build Spec Example](build-spec-ref.md#build-spec-ref-example)\. +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)\. 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.md#create-project-console) or [Change a Build Project's Settings \(Console\)](change-project.md#change-project-console)\. diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index a9cc258..f4bc78c 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.md @@ -4,11 +4,13 @@ You provide a set of commands for AWS CodeBuild to run in a build environment du + 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.md#create-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.md#change-project-console)\. -+ 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 build spec file with your commands, or specify a single string that includes the contents of an equivalent build spec 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 build spec file or a single string that includes the contents of an equivalent build spec file\. For more information, see the description for the `buildspecOverride` value in [Run a Build](run-build.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)\. -You can specify any Shell command\. In build spec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: -+ Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell\. For example, you could include a file named `my-script.sh` in your source code that contains commands such as `cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;`\. Then, in your build spec file, specify the command `./my-script.sh`\. -+ In your build spec file or on the **Build commands** setting for the `build` phase only, enter a single command that includes all of the commands you want to run in a single instance of the default shell \(for example, `cd MyDir && mkdir -p mySubDir && cd mySubDir && pwd`\)\. +You can specify any Shell command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: ++ Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell\. For example, you could include a file named `my-script.sh` in your source code that contains commands such as `cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;`\. Then, in your buildspec file, specify the command `./my-script.sh`\. ++ In your buildspec file or on the **Build commands** setting for the `build` phase only, enter a single command that includes all of the commands you want to run in a single instance of the default shell \(for example, `cd MyDir && mkdir -p mySubDir && cd mySubDir && pwd`\)\. -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\. \ No newline at end of file +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 run in a Windows Server Core 2016 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 3728211..7dd8f23 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -39,4 +39,7 @@ To choose a compute type: + 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.md#create-project-cli) 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 CodeBuild](sample-efs.md)\. If you want to manipulate container disk space during a build, then the build must run in privileged mode\. \ No newline at end of file +You can use Amazon EFS to access more space in your build container\. For more information, see [Amazon Elastic File System Sample for CodeBuild](sample-efs.md)\. If you want to manipulate container disk space during a build, then the build must run in privileged mode\. + +**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\. \ No newline at end of file diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 8827527..75ccafb 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -42,10 +42,10 @@ You can also provide build environments with your own environment variables\. Fo + [Create a Build Project](create-project.md) + [Change a Build Project's Settings](change-project.md) + [Run a Build](run-build.md) -+ [Build Spec Reference](build-spec-ref.md) ++ [Buildspec Reference](build-spec-ref.md) To list all of the available environment variables in a build environment, you can run the `printenv` command \(for Linux\-based build environment\) or `"Get-ChildItem Env:"` \(for Windows\-based build environments\) during a build\. Except for those previously listed, environment variables that start with `CODEBUILD_` are for CodeBuild internal use\. They should not be used in your build commands\. **Important** We strongly discourage the use of environment variables to store sensitive values, especially AWS access key IDs and secret access keys\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. -We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your build spec\. To store sensitive values, 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. \ No newline at end of file +We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your buildspec\. To store sensitive values, 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)\. \ No newline at end of file diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 2d77b8f..1e7ae1d 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -1,31 +1,31 @@ # Build Specification Reference for CodeBuild -This topic provides important reference information about build specification \(build spec\) files\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a build spec as part of the source code or you can define a build spec when you create a build project\. For information about how a build spec works, see [How CodeBuild Works](concepts.md#concepts-how-it-works)\. +This topic provides important reference information about build specification \(build spec\) files\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project\. For information about how a build spec works, see [How CodeBuild Works](concepts.md#concepts-how-it-works)\. **Topics** -+ [Build Spec File Name and Storage Location](#build-spec-ref-name-storage) -+ [Build Spec Syntax](#build-spec-ref-syntax) -+ [Build Spec Example](#build-spec-ref-example) -+ [Build Spec Versions](#build-spec-ref-versions) ++ [Buildspec File Name and Storage Location](#build-spec-ref-name-storage) ++ [Buildspec Syntax](#build-spec-ref-syntax) ++ [Buildspec Example](#build-spec-ref-example) ++ [Buildspec Versions](#build-spec-ref-versions) -## Build Spec File Name and Storage Location +## Buildspec File Name and Storage Location -If you include a build spec as part of the source code, by default, the build spec file must be named `buildspec.yml` and placed in the root of your source directory\. +If you include a buildspec as part of the source code, by default, the buildspec file must be named `buildspec.yml` and placed in the root of your source directory\. -You can override the default build spec file name and location\. For example, you can: -+ Use a different build spec file for different builds in the same repository, such as `buildspec_debug.yml` and `buildspec_release.yml`\. -+ Store a build spec file somewhere other than the root of your source directory, such as `config/buildspec.yml`\. +You can override the default buildspec file name and location\. For example, you can: ++ Use a different buildspec file for different builds in the same repository, such as `buildspec_debug.yml` and `buildspec_release.yml`\. ++ Store a buildspec file somewhere other than the root of your source directory, such as `config/buildspec.yml` or in an S3 bucket\. The S3 bucket 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`\)\. -You can specify only one build spec for a build project, regardless of the build spec file's name\. +You can specify only one buildspec for a build project, regardless of the buildspec file's name\. -To override the default build spec file name, location, or both, do one of the following: -+ Run the AWS CLI `create-project` or `update-project` command, setting the `buildspec` value to the path to the alternate build spec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `create project` operation in the AWS SDKs\. For more information, see [Create a Build Project](create-project.md) or [Change a Build Project's Settings](change-project.md)\. -+ Run the AWS CLI `start-build` command, setting the `buildspecOverride` value to the path to the alternate build spec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `start build` operation in the AWS SDKs\. For more information, see [Run a Build](run-build.md)\. -+ In an AWS CloudFormation template, set the `BuildSpec` property of `Source` in a resource of type `AWS::CodeBuild::Project` to the path to the alternate build spec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. For more information, see the BuildSpec property in [AWS CodeBuild Project Source](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html) in the *AWS CloudFormation User Guide*\. +To override the default buildspec file name, location, or both, do one of the following: ++ Run the AWS CLI `create-project` or `update-project` command, setting the `buildspec` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `create project` operation in the AWS SDKs\. For more information, see [Create a Build Project](create-project.md) or [Change a Build Project's Settings](change-project.md)\. ++ Run the AWS CLI `start-build` command, setting the `buildspecOverride` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `start build` operation in the AWS SDKs\. For more information, see [Run a Build](run-build.md)\. ++ In an AWS CloudFormation template, set the `BuildSpec` property of `Source` in a resource of type `AWS::CodeBuild::Project` to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. For more information, see the BuildSpec property in [AWS CodeBuild Project Source](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html) in the *AWS CloudFormation User Guide*\. -## Build Spec Syntax +## Buildspec Syntax -Build spec files must be expressed in [YAML](http://yaml.org/) format\. +Buildspec files must be expressed in [YAML](http://yaml.org/) format\. If a command contains a character, or a string of characters, that is not supported by YAML, you must enclose the command in quotation marks \(""\)\. The following command is enclosed in quotation marks because a colon \(:\) followed by a space is not allowed in YAML\. The quotation mark in the command is escaped \(\\"\)\. @@ -36,7 +36,7 @@ If a command contains a character, or a string of characters, that is not suppor **Important** If you use the Ubuntu standard image 2\.0 or later, or the Amazon Linux 2 \(AL2\) standard image 1\.0 or later, you must specify `runtime-versions` in your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](#runtime-versions-buildspec-file)\. -The build spec has the following syntax: +The buildspec has the following syntax: ``` version: 0.2 @@ -104,7 +104,7 @@ reports: - location base-directory: location discard-paths: yes - file-format: JunitXml | CucumberJson + file-format: JunitXml | CucumberJson | VisualStudioTrx | TestNGXml artifacts: files: - location @@ -132,22 +132,22 @@ cache: - path ``` -The build spec contains the following: -+ `version`: Required mapping\. Represents the build spec version\. We recommend that you use `0.2`\. +The buildspec contains the following: ++ `version`: Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. **Note** -Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Build Spec Versions](#build-spec-ref-versions)\. +Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec Versions](#build-spec-ref-versions)\. + `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\. + `env`: Optional sequence\. Represents information for one or more custom environment variables\. + `variables`: Required if `env` is specified, and you want to define custom environment variables in plain text\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable in plain text\. *key* is the name of the custom environment variable, and *value* is that variable's value\. **Important** -We strongly discourage the storing of sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. For sensitive values, we recommend that you use the `parameter-store` mapping instead, as described later in this section\. +We strongly discourage the storing of sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. For sensitive values, we recommend that you use `parameter-store` or `secrets-manager` mapping instead, as described later in this section\. 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 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 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. -The value in the build spec declaration takes lowest precedence\. - + `parameter-store`: Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. +The value in the buildspec declaration takes lowest precedence\. + + `parameter-store`: Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. **Important** To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add the `ssm:GetParameters` action to your CodeBuild service role\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Store 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 retrieve 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 retrieve 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`\. @@ -155,7 +155,7 @@ Do not store any environment variable with a name that starts with `CODEBUILD_`\ 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 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. -The value in the build spec declaration takes lowest precedence\. +The value in the buildspec declaration takes lowest precedence\. + `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` @@ -181,12 +181,12 @@ The value in the build spec declaration takes lowest precedence\. + `logs`: Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch logs\. The default is `no`\. + `phases`: Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. **Note** -In build spec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use build spec version 0\.1, we recommend the approaches in [Shells and Commands in Build Environments](build-env-ref-cmd.md)\. +In buildspec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend the approaches in [Shells and Commands in Build Environments](build-env-ref-cmd.md)\. + `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\. The allowed build phase names are: + `install`: Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. - + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, version 29 of Android, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. + + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux 2\.0 \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, version 29 of Android, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. ``` phases: @@ -220,8 +220,12 @@ Commands in some build phases might not be run if commands in earlier build phas + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + `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\. - + `discard-paths`: Optional mapping\. Represents whether paths to test result files updloaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TesResult.xml`\. - + `file-format`: Optional mapping\. Represents the test file format\. Valid values are `JunitXml` for JUnit XML and `CucumberJson` for Cucumber JSON\. If not specified, `JunitXml` is used\. + + `discard-paths`: Optional mapping\. Represents whether paths to test result files updloaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TestResult.xml`\. + + `file-format`: Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: + + `JunitXml` + + `CucumberJson` + + `VisualStudioTrx` + + `TestNGXml` + `artifacts`: Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the Amazon 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\. + `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`\)\. @@ -235,7 +239,7 @@ Commands in some build phases might not be run if commands in earlier build phas + 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.md#create-project-console)\. - You can specify a name in the build spec file that is calculated at build time\. The name specified in a build spec 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/)\. + 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\. @@ -380,12 +384,12 @@ Commands in some build phases might not be run if commands in earlier build phas + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. **Important** -Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration is invalid, builds might fail immediately\. You can use a YAML validator to test whether your build spec declarations are valid YAML\. -If you use the AWS CLI, or the AWS SDKs to declare a build spec when you create or update a build project, the build spec must be a single string expressed in YAML format, along with required whitespace and newline escape characters\. There is an example in the next section\. +Because a buildspec declaration must be valid YAML, the spacing in a buildspec declaration is important\. If the number of spaces in your buildspec declaration is invalid, builds might fail immediately\. You can use a YAML validator to test whether your buildspec declarations are valid YAML\. +If you use the AWS CLI, or the AWS SDKs to declare a buildspec when you create or update a build project, the buildspec must be a single string expressed in YAML format, along with required whitespace and newline escape characters\. There is an example in the next section\. If you use the CodeBuild or AWS CodePipeline consoles instead of a buildspec\.yml file, you can insert commands for the `build` phase only\. Instead of using the preceding syntax, you list, in a single line, all of the commands that you want to run during the build phase\. For multiple commands, separate each command by `&&` \(for example, `mvn test && mvn package`\)\. You can use the CodeBuild or CodePipeline consoles instead of a buildspec\.yml file to specify the locations of the build output artifacts in the build environment\. Instead of using the preceding syntax, you list, in a single line, all of the locations\. For multiple locations, separate each location with a comma \(for example, `buildspec.yml, target/my-app.jar`\)\. -## Build Spec Example +## Buildspec Example | | @@ -458,7 +462,7 @@ cache: - '/root/.m2/**/*' ``` -Here is an example of the preceding build spec, expressed as a single string, for use with the AWS CLI, or the AWS SDKs\. +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/**/*'" @@ -479,9 +483,9 @@ In these examples: + `arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1` specifies the ARN of a report group\. Test results generated by the test framework are in the `target/tests/reports` directory\. The file format is `JunitXml` and the path is not removed from the files that contain test results\. + `reportGroupCucumberJson` specifies a new report group\. If the name of the project is `my-project`, a report group with the name `my-project-reportGroupCucumberJson` is created when a build is run\.\. Test results generated by the test framework are in `cucumber/target/cucumber-tests.xml`\. The test file format is `CucumberJson` and the path is removed from the files that contain test results\. -## Build Spec Versions +## Buildspec Versions -The following table lists the build spec versions and the changes between versions\. +The following table lists the buildspec versions and the changes between versions\. **** diff --git a/doc_source/change-project.md b/doc_source/change-project.md index 9d81928..5002ae7 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -35,7 +35,9 @@ CodeBuild does not support Bitbucket Server\. 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 build spec\. \(Do not run the following build commands if the specified build environment image is provided by CodeBuild with Docker support\.\) +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& @@ -48,7 +50,9 @@ When you use the console to create or update a build project, you can create a C 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, in **Additional configuration**, change the values for **VPC**, **Subnets**, and **Security groups**\. +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 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**\. @@ -73,18 +77,18 @@ The value in the build spec 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 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. +If you choose **New service role**, the service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. 1. To change information about tags for this build project, in **Additional configuration**, for **Tags**, change the values of **Name** and **Value**\. Use **Add row** to add a tag\. You can add up to 50 tags\. Choose the delete \(**X**\) icon next to a tag you no longer want to use\. 1. Choose **Update environment**\. -1. To change the project's build specifications, in **Buildspec**, choose **Edit**\. +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, + + 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**\. @@ -94,7 +98,7 @@ If you choose **New service role**, the created service role includes permission **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 build spec file, see [Build Spec 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: +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 Amazon S3 bucket where the cache is stored\. diff --git a/doc_source/cloudformation-vpc-template.md b/doc_source/cloudformation-vpc-template.md index a5f8ada..e78db74 100644 --- a/doc_source/cloudformation-vpc-template.md +++ b/doc_source/cloudformation-vpc-template.md @@ -1,6 +1,6 @@ # AWS CloudFormation VPC Template -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)\. +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 an Amazon VPC to use the AWS CodeBuild VPC feature\. diff --git a/doc_source/cloudtrail.md b/doc_source/cloudtrail.md index a698fc5..52a0c4e 100644 --- a/doc_source/cloudtrail.md +++ b/doc_source/cloudtrail.md @@ -27,6 +27,12 @@ For more information, see the [CloudTrail userIdentity Element](https://docs.aws A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify\. CloudTrail log files contain one or more log entries\. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on\. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order\. +**Note** + 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)\. + The following example shows a CloudTrail log entry that demonstrates creating a build project in CodeBuild\. ``` diff --git a/doc_source/concepts.md b/doc_source/concepts.md index aec74e1..c48e1ba 100644 --- a/doc_source/concepts.md +++ b/doc_source/concepts.md @@ -18,9 +18,9 @@ The following diagram shows what happens when you run a build with CodeBuild: 1. CodeBuild uses the build project to create the build environment\. -1. CodeBuild downloads the source code into the build environment and then uses the build specification \(build spec\), as defined in the build project or included directly in the source code\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. For more information, see the [Build Spec Reference](build-spec-ref.md)\. +1. CodeBuild downloads the source code into the build environment and then uses the build specification \(buildspec\), as defined in the build project or included directly in the source code\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. For more information, see the [Buildspec Reference](build-spec-ref.md)\. -1. If there is any build output, the build environment uploads its output to an Amazon S3 bucket\. The build environment can also perform tasks that you specify in the build spec \(for example, sending build notifications to an Amazon SNS topic\)\. For an example, see [Build Notifications Sample](sample-build-notifications.md)\. +1. If there is any build output, the build environment uploads its output to an Amazon S3 bucket\. The build environment can also perform tasks that you specify in the buildspec \(for example, sending build notifications to an Amazon SNS topic\)\. For an example, see [Build Notifications Sample](sample-build-notifications.md)\. 1. While the build is running, the build environment sends information to CodeBuild and Amazon CloudWatch Logs\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index ce4e10e..140f04b 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -59,6 +59,8 @@ CodeBuild does not support Bitbucket Server\. + 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/) \(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** +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& @@ -75,29 +77,34 @@ When you use the console to create or update a build project, you can create a C \(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\. - In **VPC**, do one of the following: - + If you are not using a VPC for your project, choose **No 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\. + 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 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 name of a directory in your build container that mounts the file system\. 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**, type the name and value, then choose the type, of each environment variable for builds to use\. Use **Add environment variable** to add an environment variable\. + For **Environment variables**, enter the name and value, and then choose the type of each environment variable for builds to use\. **Note** -CodeBuild sets the environment variable for your AWS Region automatically\. If you do not add them to your buildspec\.yml, then the following environment variables must be set: +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 - 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**\. + 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**, type `/CodeBuild/dockerLoginPassword`\. + 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** 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\. @@ -110,30 +117,30 @@ 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 build spec declaration takes lowest precedence\. - If you use Secrets Manager, then 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, 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 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. +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**\. + + 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 [Build Spec Reference](build-spec-ref.md)\. + 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 Amazon S3 bucket, choose **Amazon S3**, and then do the following: + + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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: @@ -155,15 +162,15 @@ If you choose **New service role**, the created service role includes permission 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 Amazon S3 bucket where the cache is stored\. + + 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\. 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\. 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build Caching in CodeBuild](build-caching.md)\. + 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 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\. @@ -287,6 +294,22 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re ], "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": [ @@ -321,19 +344,19 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re ``` Replace the following: - + *project\-name*: Required value\. The name for this build project\. This name must be unique across all of the build projects in your AWS account\. - + *description*: Optional value\. The description for this build project\. + + *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 value\. 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`, then 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 value \(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 build spec \(for example, `https://git-codecommit.region-id.amazonaws.com/v1/repos/repo-name`\)\. + + *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`, then 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 build spec \(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 build spec\. 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\. + + 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, the HTTP or HTTPS clone URL to the repository that contains the source code and the build spec\. You must also connect your AWS account to your GitHub Enterprise account\. To do this, use the CodeBuild console to create a build project\. + + For GitHub Enterprise, 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 account\. To do this, use the CodeBuild console to create a build project\. 1. Create a personal access token in GitHub Enterprise\. @@ -342,108 +365,114 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re 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 account\. - + For Bitbucket, the HTTPS clone URL to the repository that contains the source code and the build spec\. 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\. + + 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`\. It is ignored by CodePipeline because when you create a pipeline in CodePipeline, you specify the source code location in the Source stage of the pipeline\. - + *gitCloneDepth*: Optional value\. 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 value\. The build specification definition or file to use\. If this value is set, it can be either an inline build spec definition or the path to an alternate build spec file relative to the value of the built\-in `CODEBUILD_SRC_DIR` environment variable\. If this value is not provided or is set to an empty string, then the source code must contain a `buildspec.yml` file in its root directory\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. + + For AWS CodePipeline, do not specify a `location` value for `source`\. CodePipeline ignores `source` 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 value\. 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, or Bitbucket, an invalidInputException is thrown\. - + *gitSubmodulesConfig*: Optional value\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise, 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 value\. Used with GitHub Enterprise only\. Set this value to `true` to ignore SSL warnings while connecting to your GitHub Enterprise 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 value\. 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: + + *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, or Bitbucket, an invalidInputException is thrown\. + + *gitSubmodulesConfig*: Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise, 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 only\. Set this value to `true` to ignore SSL warnings while connecting to your GitHub Enterprise 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 Simple Storage Service \(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 CodeBuild](sample-source-version.md)\. - + *secondarySourceVersions*: Optional value\. An array of `projectSourceVersion` objects\. If `secondarySourceVersions` is specified at the build level, then they take precedence over this\. + + *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 value\. The type of build output artifact\. Valid values include `CODEPIPELINE`, `NO_ARTIFACTS`, and `S3`\. - + *artifacts\-location*: Required value \(unless you set *artifacts\-type* to `CODEPIPELINE` or `NO_ARTIFACTS`\)\. The location of the build output artifact: + + *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*, then this is the name of the output bucket you created or identified in the prerequisites\. - + *path*: Optional value\. The path and name of the build output ZIP file or folder: - + If you specified `CODEPIPELINE` for *artifacts\-type*, then do not specify a `path` for `artifacts`\. + + *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 `S3` for *artifacts\-type*, then 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*, then 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*, then the path and name would be `MyPath/MyArtifact.zip`\. - + *namespaceType*: Optional value\. The path and name of the build output ZIP file or folder: + + 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*, then 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*, then 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*, then the path and name would be `MyPath/build-ID/MyArtifact.zip`\. - + *artifacts\-name*: Required value \(unless you set *artifacts\-type* to `CODEPIPELINE` or `NO_ARTIFACTS`\)\. The path and name of the build output ZIP file or folder: + + *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*, then 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*, then the path and name would be `MyPath/MyArtifact.zip`\. + *override\-artifact\-name*: Optional boolean value\. 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 value\. The type of build output artifact to create: + + *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 value\. Valid values are `S3`, `NO_CACHE`, or `LOCAL_CACHE`\. - + *cache\-location*: Required value only if you set *CacheType* to `S3`\. If you specified Amazon S3 for *CacheType*, this is the ARN of the Amazon S3 bucket and the path prefix\. For example, if your Amazon 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 value 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`\. + + *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 Amazon S3 bucket and the path prefix\. For example, if your Amazon 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\. +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 value\. Valid values are `ENABLED` or `DISABLED`\. If its value is `ENABLED` then 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)\. + + *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)\. + *group\-name*: The name of the CloudWatch Logs group\. + *stream\-name*: The name of the CloudWatch Logs stream\. - + *s3\-logs\-status*: Required value\. 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 Amazon 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 value\. If set to `true` your S3 build log output is not encrypted\. By default S3 build logs are encrypted\. + + *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 value\. 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 artifiact 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 value\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's type property](#cli-artifacts-type)\. - + *artifacts\-location*: Required value\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's location property](#cli-artifacts-location)\. - + *path*: Optional value\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's path property](#cli-artifacts-path)\. - + *namespaceType*: Optional value\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's namespaceType property](#cli-artifacts-namespacetype)\. - + *artifacts\-name*: Required value\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's name property](#cli-artifacts-name)\. - + *packaging*: Optional value\. This setting is also used by the `artifacts` object\. See [CodeBuild artifact object's packaging property](#cli-artifacts-packaging)\. - + *artifact\-identifier*: Required value\. A unique string identifier for a secondary artifact\. + + *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 value\. This setting is also used by the `sources` object\. See [CodeBuild source object's type property](#cli-sources-type)\. - + *source\-location*: Required value\. This setting is also used by the `sources` object\. See [CodeBuild source object's location property](#cli-sources-location)\. - + *gitCloneDepth*: Optional value\. This setting is also used by the `sources` object\. See [CodeBuild source object's gitCloneDepth property](#cli-sources-gitclonedepth)\. - + *buildspec*: Optional value\. This setting is also used by the `sources` object\. See [CodeBuild source object's buildspec property](#cli-sources-buildspec)\. + + *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 gitCloneDepth property](#cli-sources-gitclonedepth)\. + + *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 value\. This setting is also used by the `sources` object\. See [CodeBuild source object's reportBuildStatus property](#cli-sources-reportbuildstatus)\. - + *InsecureSsl*: Optional value\. This setting is also used by the `sources` object\. See [CodeBuild source object's insecureSsl property](#cli-sources-insecuressl)\. - + *source\-identifier*: Required value\. A unique string identifier for a secondary source\. - + *serviceRole*: Required value\. 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`\)\. + + *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 value\. The VPC ID that CodeBuild uses\. Run this command to get a list of all Amazon VPC IDs in your region: + + *vpcId*: Required\. The VPC ID that CodeBuild uses\. Run this command to get a list of all Amazon VPC IDs in your region: ``` aws ec2 describe-vpcs ``` - + *subnets*: Required value\. The subnet IDs that include resources used by CodeBuild\. Run this command to get these IDs: + + *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 value\. The security group IDs used by CodeBuild to allow access to resources in the VPCs\. Run this command to get these IDs: + If you are using an AWS 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\. + If you are using an AWS 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 name of a directory in your build container that mounts the file system\. 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 value\. The type of build environment\. Valid values are `ARM_CONTAINER`, `LINUX_CONTAINER`, `LINUX_GPU_CONTAINER`, and `WINDOWS_CONTAINER`\. - + *image*: Required value\. 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:2.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 value\. A category corresponding 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, and BUILD_GENERAL1_2XLARGE`\. `BUILD_GENERAL1_2XLARGE` is only supported with the `LINUX_CONTAINER` environment type\. - + *certificate*: Optional value\. 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 Amazon 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\. + + *environment\-type*: Required\. The type of build environment\. Valid values are `ARM_CONTAINER`, `LINUX_CONTAINER`, `LINUX_GPU_CONTAINER`, and `WINDOWS_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:2.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 corresponding 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, and 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*\. - 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 *environmentVariable\-name* and *environmentVariable\-value*, and then set *environmentVariable\-type* to `PLAINTEXT`\. + 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\. @@ -462,31 +491,33 @@ The value in the build spec 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** -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 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 created service role includes permission to decrypt all secrets under the `/CodeBuild/` namespace in the Secrets Manager\. +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`\. + + *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 value\. The type of credentials CodeBuild uses to pull images in your build\. There are two valid values: + + *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\. This requires that you modify 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 build spec by running the following build commands\. Do not run these commands if you specified a build environment image provided by CodeBuild with Docker support\. + + 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** +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 value\. 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 value\. 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 value\. The alias or ARN of the AWS KMS customer managed key \(CMK\) CodeBuild uses 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\. + + *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\) CodeBuild uses 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 that contains a `key` and `value` value of *tag\-key* and *tag\-value*\. For an example, see [To create the build project ](getting-started-cli-create-build-project.md#getting-started-cli-create-build-project-cli)\. @@ -551,7 +582,7 @@ If you choose **New service role**, the created service role includes permission + 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 represents the ARN of the build project\. + + 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)\. diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 4f0a2f4..6bb7360 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -11,6 +11,11 @@ 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\. + 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)\. + 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*\. **Topics** diff --git a/doc_source/delete-builds.md b/doc_source/delete-builds.md index 7916da1..6dbf8be 100644 --- a/doc_source/delete-builds.md +++ b/doc_source/delete-builds.md @@ -29,12 +29,12 @@ Information similar to the following appears in the output: { "buildsNotDeleted": [ { - "id": "arn:aws:codebuild:us-west-2:123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX", + "id": "arn:aws:codebuild:us-west-2::123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX", "statusCode": "BUILD_IN_PROGRESS" } ], "buildsDeleted": [ - "arn:aws:codebuild:us-west-2:123456789012:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" + "arn:aws:codebuild:us-west-2::123456789012n:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" ] } ``` diff --git a/doc_source/getting-started-build-log-console.md b/doc_source/getting-started-build-log-console.md index bffc48e..7a63299 100644 --- a/doc_source/getting-started-build-log-console.md +++ b/doc_source/getting-started-build-log-console.md @@ -2,7 +2,13 @@ \(Previous step: [Step 7: View Summarized Build Information](getting-started-monitor-build-console.md)\) -In this step, you view detailed information about your build in CloudWatch Logs\. +In this step, you view detailed information about your build in CloudWatch Logs\. + +**Note** + 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)\. **To view detailed build information** diff --git a/doc_source/getting-started-cli-build-log.md b/doc_source/getting-started-cli-build-log.md index df83df7..50ff575 100644 --- a/doc_source/getting-started-cli-build-log.md +++ b/doc_source/getting-started-cli-build-log.md @@ -2,7 +2,13 @@ \(Previous step: [Step 7: View Summarized Build Information](getting-started-cli-monitor-build.md)\) -In this step, you view detailed information about your build in CloudWatch Logs\. +In this step, you view detailed information about your build in CloudWatch Logs\. + +**Note** + 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)\. **To view detailed build information** diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 6319ce4..381f1c3 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -1,6 +1,6 @@ # Step 5: Create the Build Project -\(Previous step: [Step 4: Upload the Source Code and the Build Spec](getting-started-cli-upload-source-code.md)\) +\(Previous step: [Step 4: Upload the Source Code and the Buildspec File](getting-started-cli-upload-source-code.md)\) In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. @@ -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/standard:2.0", + "image": "aws/codebuild/amazonlinux2-x86_64-standard:2.0", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "serviceIAMRole" diff --git a/doc_source/getting-started-cli-create-build-spec.md b/doc_source/getting-started-cli-create-build-spec.md index 24dda34..22a546e 100644 --- a/doc_source/getting-started-cli-create-build-spec.md +++ b/doc_source/getting-started-cli-create-build-spec.md @@ -1,4 +1,4 @@ -# Step 3: Create the Build Spec +# Step 3: Create the Buildspec File \(Previous step: [Step 2: Create the Source Code](getting-started-cli-create-source-code.md)\) @@ -32,7 +32,7 @@ artifacts: Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. **Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. +Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. In this build spec declaration: + `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. @@ -41,7 +41,7 @@ In this build spec declaration: In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. + `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. -For more information, see the [Build Spec Reference](build-spec-ref.md)\. +For more information, see the [Buildspec Reference](build-spec-ref.md)\. At this point, your directory structure should look like this\. @@ -60,4 +60,4 @@ At this point, your directory structure should look like this\. ## Next Step -[Step 4: Upload the Source Code and the Build Spec](getting-started-cli-upload-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-create-source-code.md b/doc_source/getting-started-cli-create-source-code.md index cf660d4..111ec62 100644 --- a/doc_source/getting-started-cli-create-source-code.md +++ b/doc_source/getting-started-cli-create-source-code.md @@ -119,4 +119,4 @@ At this point, your directory structure should look like this\. ## Next Step -[Step 3: Create the Build Spec](getting-started-cli-create-build-spec.md) \ No newline at end of file +[Step 3: 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-upload-source-code.md b/doc_source/getting-started-cli-upload-source-code.md index 691dd60..6b68365 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 Build Spec +# Step 4: Upload the Source Code and the Buildspec File -\(Previous step: [Step 3: Create the Build Spec](getting-started-cli-create-build-spec.md)\) +\(Previous step: [Step 3: Create the Buildspec File](getting-started-cli-create-build-spec.md)\) In this step, you add the source code and build spec file to the input bucket\. @@ -29,7 +29,7 @@ Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID **Important** For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. +If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. ## Next Step diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md index ab5531a..a0e1b3c 100644 --- a/doc_source/getting-started-cli.md +++ b/doc_source/getting-started-cli.md @@ -10,8 +10,8 @@ The steps in this tutorial require you to create resources \(for example, an S3 ## 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 Build Spec](getting-started-cli-create-build-spec.md) -+ [Step 4: Upload the Source Code and the Build Spec](getting-started-cli-upload-source-code.md) ++ [Step 3: Create the Buildspec File](getting-started-cli-create-build-spec.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) diff --git a/doc_source/getting-started-create-build-project-console.md b/doc_source/getting-started-create-build-project-console.md index 8833729..b1c8017 100644 --- a/doc_source/getting-started-create-build-project-console.md +++ b/doc_source/getting-started-create-build-project-console.md @@ -1,6 +1,6 @@ # Step 5: Create the Build Project -\(Previous step: [Step 4: Upload the Source Code and the Build Spec](getting-started-upload-source-code-console.md)\) +\(Previous step: [Step 4: Upload the Source Code and the Buildspec File](getting-started-upload-source-code-console.md)\) In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. @@ -32,7 +32,7 @@ An IAM user in your AWS account with the `AWSCodeBuildAdminAccess`, `AmazonS3Rea 1. For **Runtime\(s\)**, choose **Standard**\. -1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. +1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. 1. In **Service role**, leave **New service role** selected, and leave **Role name** unchanged\. diff --git a/doc_source/getting-started-create-build-spec-console.md b/doc_source/getting-started-create-build-spec-console.md index 77897e6..2d1e312 100644 --- a/doc_source/getting-started-create-build-spec-console.md +++ b/doc_source/getting-started-create-build-spec-console.md @@ -1,4 +1,4 @@ -# Step 3: Create the Build Spec +# Step 3: Create the Buildspec File \(Previous step: [Step 2: Create the Source Code](getting-started-create-source-code-console.md)\) @@ -32,7 +32,7 @@ artifacts: Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. **Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. +Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. In this build spec declaration: + `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. @@ -41,7 +41,7 @@ In this build spec declaration: In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. + `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. -For more information, see the [Build Spec Reference](build-spec-ref.md)\. +For more information, see the [Buildspec Reference](build-spec-ref.md)\. At this point, your directory structure should look like this\. @@ -60,4 +60,4 @@ At this point, your directory structure should look like this\. ## Next Step -[Step 4: Upload the Source Code and the Build Spec](getting-started-upload-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-create-source-code-console.md b/doc_source/getting-started-create-source-code-console.md index 83e06a9..4b463ab 100644 --- a/doc_source/getting-started-create-source-code-console.md +++ b/doc_source/getting-started-create-source-code-console.md @@ -119,4 +119,4 @@ At this point, your directory structure should look like this\. ## Next Step -[Step 3: Create the Build Spec](getting-started-create-build-spec-console.md) \ No newline at end of file +[Step 3: Create the Buildspec File](getting-started-create-build-spec-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-upload-source-code-console.md b/doc_source/getting-started-upload-source-code-console.md index 761f5eb..5ddf1b3 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 Build Spec +# Step 4: Upload the Source Code and the Buildspec File -\(Previous step: [Step 3: Create the Build Spec](getting-started-create-build-spec-console.md)\) +\(Previous step: [Step 3: Create the Buildspec File](getting-started-create-build-spec-console.md)\) In this step, you add the source code and build spec file to the input bucket\. @@ -29,7 +29,7 @@ Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID **Important** For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. +If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. ## Next Step diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index 9d84969..e79392c 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -10,8 +10,8 @@ The steps in this tutorial require you to create resources \(for example, an S3 ## 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 Build Spec](getting-started-create-build-spec-console.md) -+ [Step 4: Upload the Source Code and the Build Spec](getting-started-upload-source-code-console.md) ++ [Step 3: Create the Buildspec File](getting-started-create-build-spec-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) diff --git a/doc_source/history.md b/doc_source/history.md index 7f611c5..9b03fde 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,16 +2,16 @@ 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: **December 23, 2019 ++ **Latest documentation update: **February 14, 2020 | Change | Description | Date | | --- |--- |--- | | [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 [Build Spec Syntax](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec-ref-syntax)\. | November 6, 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 [Build Spec 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 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 | @@ -34,7 +34,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 build spec file](#history) | The CodeBuild documentation was updated with details about the optional `finally` block in a build spec file\. Commands in the finally block always execute after the commands in its corresponding commands block\. For more information, see [Build Spec 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 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 | | [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 @@ -60,20 +60,20 @@ The following table describes important changes in each release of the *AWS Code | 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 [Use AWS Config with AWS CodeBuild 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 build spec 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 | +| 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 build spec | AWS CodeBuild now makes it easier to use a build spec 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. | August 10, 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | June 29, 2017 | -| Alternate build spec file names and locations supported | You can now specify an alternate file name or location of a build spec file to use for a build project, instead of a default build spec file named buildspec\.yml at the root of the source code\. For more information, see [Build Spec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. | June 27, 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.md#run-build-console) or the `sourceVersion` value in [Run a Build \(AWS CLI\)](run-build.md#run-build-cli)\. | June 6, 2017 | -| Build specification version updated | A new version of the build spec 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 | +| 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic 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 an CodeBuild Test Action to a Pipeline \(CodePipeline Console\)](how-to-create-pipeline.md#how-to-create-pipeline-add-test)\. | March 8, 2017 | -| Build specs support fetching build output from within selected top\-level directories | Build specs 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. | February 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic 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 | diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index b041d40..6f4fac5 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -47,7 +47,7 @@ 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 build spec file, but you can declare one when you define a build project later in this topic\. For more information, see the [Build Spec 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, 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)\. **Important** If you plan to use the pipeline to deploy built source code, then the build output artifact must be compatible with the deployment system you use\. For CodeDeploy, see the [CodeDeploy Sample](sample-codedeploy.md) in this guide and see [Prepare a Revision for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-revision.html) in the *CodeDeploy User Guide*\. @@ -607,7 +607,7 @@ To store and retrieve sensitive values, we recommend your build commands use the 1. For **Input artifacts**, select the value for **Output artifact** that you noted in step 4 of this procedure\. -1. \(Optional\) If you want your test action to produce an output artifact, and you set up your build spec accordingly, then for **Output artifact**, enter the value you want to assign to the output artifact\. +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**\. diff --git a/doc_source/index.md b/doc_source/index.md index 617406a..a48ea48 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,7 +1,7 @@ # AWS CodeBuild User Guide ----- -*****Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** +*****Copyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** ----- Amazon's trademarks and trade dress may not be used in @@ -20,8 +20,8 @@ Amazon's trademarks and trade dress may not be used in + [Getting Started with CodeBuild in 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 Build Spec](getting-started-create-build-spec-console.md) - + [Step 4: Upload the Source Code and the Build Spec](getting-started-upload-source-code-console.md) + + [Step 3: Create the Buildspec File](getting-started-create-build-spec-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) @@ -32,8 +32,8 @@ Amazon's trademarks and trade dress may not be used in + [Getting Started with 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 Build Spec](getting-started-cli-create-build-spec.md) - + [Step 4: Upload the Source Code and the Build Spec](getting-started-cli-upload-source-code.md) + + [Step 3: Create the Buildspec File](getting-started-cli-create-build-spec.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) @@ -109,7 +109,9 @@ Amazon's trademarks and trade dress may not be used in + [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 (AWS CloudFormation)](test-report-group-create-cfn.md) - + [Specify Export Settings](report-group-export-settings.md) + + [Update a Report Group](report-group-export-settings.md) + + [Update a Report Group (Console)](update-report-group-console.md) + + [Update a Report Group (CLI)](update-report-group-cli.md) + [Specify Test Files](report-group-test-cases.md) + [Specify Test Commands](report-group-test-case-commands.md) + [Report Group Naming](test-report-group-naming.md) diff --git a/doc_source/planning.md b/doc_source/planning.md index 14f5b26..cc27ff0 100644 --- a/doc_source/planning.md +++ b/doc_source/planning.md @@ -2,11 +2,11 @@ Before you run your build with CodeBuild, you must answer these questions: -1. **Where is the source code located?** CodeBuild currently supports building from the following source code repository providers\. The source code must contain a build specification \(build spec\) file, or the build spec must be declared as part of a build project definition\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. +1. **Where is the source code located?** CodeBuild currently supports building from the following source code repository providers\. The source code must contain a build specification \(buildspec\) file, or the buildspec must be declared as part of a build project definition\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/planning.html) -1. **Which build commands do you need to run and in what order?** By default, CodeBuild downloads the build input from the provider you specify and uploads the build output to the bucket you specify\. You use the build spec to instruct how to turn the downloaded build input into the expected build output\. For more information, see the [Build Spec Reference](build-spec-ref.md)\. +1. **Which build commands do you need to run and in what order?** By default, CodeBuild downloads the build input from the provider you specify and uploads the build output to the bucket you specify\. You use the buildspec to instruct how to turn the downloaded build input into the expected build output\. For more information, see the [Buildspec Reference](build-spec-ref.md)\. 1. **Which runtimes and tools do you need to run the build?** For example, are you building for Java, Ruby, Python, or Node\.js? Does the build need Maven or Ant or a compiler for Java, Ruby, or Python? Does the build need Git, the AWS CLI, or other tools? diff --git a/doc_source/report-group-export-settings.md b/doc_source/report-group-export-settings.md index 9421694..83797ff 100644 --- a/doc_source/report-group-export-settings.md +++ b/doc_source/report-group-export-settings.md @@ -1,37 +1,14 @@ -# Specify Export Settings +# Update a Report Group | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You can specify information about whether to export the raw test result data to files in an S3 bucket\. If you choose to export to an S3 bucket, specify the following when you create your report group: + When you update a report group, you can specify information about whether to export the raw test result data to files in an 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\. -**To update export settings for a report group** - -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 naviagation pane, choose **Report groups**\. - -1. Choose the report group you want to update\. - -1. Choose **Edit**\. - -1. Select or clear **Backup to Amazon S3**\. If you selected this option, specify your export settings: - - 1. For **S3 bucket name**, enter the name of the S3 bucket\. - - 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. 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\.\) - For more information, see [Data Encryption](security-encryption.md)\. \ No newline at end of file diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 4aac929..21306c1 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -38,6 +38,8 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll 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**\. @@ -45,13 +47,13 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll + From **Certificate**, choose a different setting\. Under **Buildspec**, you can: - + Choose **Use a buildspec file** to use the buildspec\.yml in the source code root directory\. + + 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 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\. 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 build spec file to override any name specified in the console, select **Enable semantic versioning**\. The name in a build spec 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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 Amazon S3 bucket for your output artifacts\. @@ -88,7 +90,7 @@ Do not set any environment variable with a name that begins with `CODEBUILD_`\. 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 build spec declaration takes lowest precedence\. +The value in the buildspec declaration takes lowest precedence\. 1. Choose **Start build**\. @@ -112,7 +114,7 @@ For more information about using the AWS CLI with CodeBuild, see the [Command Li aws codebuild start-build --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, build spec, or default build timeout period\. + 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 command with the `--project-name` option, replace *project\-name* 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)\. @@ -174,7 +176,7 @@ For more information about using the AWS CLI with CodeBuild, see the [Command Li + *namespaceType*: Optional string\. The build output artifact path type that overrides for this build the one defined in the build project\. + *name*: Optional string\. The build output artifact name that overrides for this build the one defined in the build project\. + *packaging*: Optional string\. The build output artifact packaging type that overrides for this build the one defined in the build project\. - + *buildspecOverride*: Optional string\. A build spec declaration that overrides for this build the one defined in the build project\. If this value is set, it can be either an inline build spec definition or the path to an alternate build spec file relative to the value of the built\-in `CODEBUILD_SRC_DIR` environment variable\. + + *buildspecOverride*: Optional string\. A build spec declaration that overrides for this build the one defined in the build project\. 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 S3 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)\. + The following placeholders are for `cacheOveride`\. + *cacheOverride\-location*: Optional string\. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `location` is required in a `ProjectCache` object\. + *cacheOverride\-type*: Optional string\. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `type` is required in a `ProjectCache` object\. @@ -204,7 +206,7 @@ Do not set any environment variable with a name that begins with `CODEBUILD_`\. If an environment variable with the same name is defined in multiple places, the environment variable's 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 build spec declaration takes lowest precedence\. +The value in the buildspec file declaration takes lowest precedence\. For information about valid values for these placeholders, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. For a list of the latest settings for a build project, see [View a Build Project's Details](view-project-details.md)\. diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 4ed8bb4..fa75327 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -36,14 +36,14 @@ When you use the console to create or update a build project, you can create a C + 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 [Build Spec Reference](build-spec-ref.md)\. + 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 build output artifacts, choose **No artifacts**\. + To store the build output in an Amazon 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 0e34f84..481240b 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -39,7 +39,7 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a 1. Create or identify a topic in Amazon SNS\. AWS CodeBuild will use CloudWatch Events to send build notifications to this topic through Amazon SNS\. To create a topic: - 1. Open the Amazon SNS console, at [https://console\.aws\.amazon\.com/sns](https://console.aws.amazon.com/sns)\. + 1. Open the Amazon SNS console, at [https://console\.aws\.amazon\.com/sns/home](https://console.aws.amazon.com/sns/home)\. 1. Choose **Create topic**\. @@ -258,7 +258,7 @@ To stop using a rule to send build notifications, in the CloudWatch console, cho To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. -### Related Resources +### Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. @@ -275,21 +275,21 @@ Build state change notifications use the following format: "id": "c030038d-8c4d-6141-9545-00ff7b7153EX", "detail-type": "CodeBuild Build State Change", "source": "aws.codebuild", - "account": "123456789012", + "account": ":123456789012", "time": "2017-09-01T16:14:28Z", "region": "us-west-2", "resources":[ - "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" + "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" ], "detail":{ "build-status": "SUCCEEDED", "project-name": "my-sample-project", - "build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", + "build-id": "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", "additional-information": { "artifact": { "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", "sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX", - "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" + "location": "arn:aws:s3:::codebuild-:123456789012-output-bucket/my-output-artifact.zip" }, "environment": { "image": "aws/codebuild/standard:2.0", @@ -303,7 +303,7 @@ Build state change notifications use the following format: "initiator": "MyCodeBuildDemoUser", "build-start-time": "Sep 1, 2017 4:12:29 PM", "source": { - "location": "codebuild-123456789012-input-bucket/my-input-artifact.zip", + "location": "codebuild-:123456789012-input-bucket/my-input-artifact.zip", "type": "S3" }, "logs": { @@ -405,22 +405,22 @@ Build phase change notifications use the following format: "id": "43ddc2bd-af76-9ca5-2dc7-b695e15adeEX", "detail-type": "CodeBuild Build Phase Change", "source": "aws.codebuild", - "account": "123456789012", + "account": ":123456789012", "time": "2017-09-01T16:14:21Z", "region": "us-west-2", "resources":[ - "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" + "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" ], "detail":{ "completed-phase": "COMPLETED", "project-name": "my-sample-project", - "build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", + "build-id": "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", "completed-phase-context": "[]", "additional-information": { "artifact": { "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", "sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX", - "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" + "location": "arn:aws:s3:::codebuild-:123456789012-output-bucket/my-output-artifact.zip" }, "environment": { "image": "aws/codebuild/standard:2.0", @@ -434,7 +434,7 @@ Build phase change notifications use the following format: "initiator": "MyCodeBuildDemoUser", "build-start-time": "Sep 1, 2017 4:12:29 PM", "source": { - "location": "codebuild-123456789012-input-bucket/my-input-artifact.zip", + "location": "codebuild-:123456789012-input-bucket/my-input-artifact.zip", "type": "S3" }, "logs": { diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index c7d1189..c0e61d1 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -166,7 +166,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 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`\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index 4b9db5b..036c157 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -2,7 +2,7 @@ You can disable the encryption of artifacts in a build\. You might want to do this so that you can publish artifacts to a location that is configured to host a website\. \(You cannot publish encrypted artifacts\.\) This sample shows how you can use webhooks to trigger a build and publish its artifacts to an Amazon S3 bucket that is configured to be a website\. -1. Follow the instructions in [Setting Up a Static Website](https://docs.aws.amazon.com/AmazonS3/latest/dev//HostingWebsiteOnS3Setup.html) to configure an Amazon S3 bucket to function like a website\. +1. Follow the instructions in [Setting Up a Static Website](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html) to configure an Amazon S3 bucket to function like a website\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -32,7 +32,7 @@ When you use the console to create or update a build project, you can create a C + 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 [Build Spec Reference](build-spec-ref.md)\. + For more information, see the [Buildspec Reference](build-spec-ref.md)\. 1. In **Artifacts**, for ** Type**, choose **Amazon S3** to store the build output in an Amazon S3 bucket\. @@ -46,4 +46,4 @@ When you use the console to create or update a build project, you can create a C 1. Choose **Create build project**\. On the build project page, in **Build history**, choose **Start build** to run the build\. -1. \(Optional\) Follow the instructions in [Example: Speed Up Your Website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev//website-hosting-cloudfront-walkthrough.html)\. \ No newline at end of file +1. \(Optional\) Follow the instructions in [Example: Speed Up Your Website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-cloudfront-walkthrough.html)\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 0446f8d..8baf3d0 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -11,7 +11,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Running the Sample](#sample-docker-custom-image-running) + [Directory Structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w48aac11c41c34c17) ++ [Related Resources](#w58aac11c41c34c17) ## Running the Sample @@ -46,6 +46,8 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" } ``` +**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\. 1. To see the build results, look in the build's log for the string `Hello, World!`\. For more information, see [View Build Details](view-build-details.md)\. @@ -97,7 +99,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 4781859..181555c 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -4,7 +4,7 @@ This sample produces as build output a Docker image and then pushes the Docker i To learn how to build a Docker image by using a custom Docker build image instead \(`docker:dind` in Docker Hub\), see our [Docker in Custom Image Sample](sample-docker-custom-image.md)\. -This sample was tested referencing `golang:1.12` +This sample was tested referencing `golang:1.12`\. This sample uses the new multi\-stage Docker builds feature, which produces a Docker image as build output\. It then pushes the Docker image to an Amazon ECR image repository\. Multi\-stage Docker image builds help to reduce the size of the final Docker image\. For more information, see [Use multi\-stage builds with Docker](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)\. @@ -16,7 +16,7 @@ Running this sample may result in charges to your AWS account\. These include po + [Directory Structure](#sample-docker-dir) + [Files](#sample-docker-files) + [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w48aac11c41c19c23) ++ [Related Resources](#w58aac11c41c19c23) ## Running the Sample @@ -44,7 +44,7 @@ To run this sample: **Note** The IAM entity that modifies this policy must have permission in IAM to modify policies\. -1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS region where you will be creating your build environment and running your build\. For more information, see [Creating a Repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you will specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. +1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS Region where you will be creating your build environment and running your build\. For more information, see [Creating a Repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you will specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. 1. Add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the policy you attached to your AWS CodeBuild service role\. This statement enables CodeBuild to upload Docker images to Amazon ECR repositories\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. @@ -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 Amazon 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 informatoin\. +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\. If you use the console to create your project: @@ -89,6 +89,8 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 1. For **Image**, choose **aws/codebuild/standard:2\.0**\. 1. Because you use this build project to build a Docker image, select **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\. 1. Add the following environment variables: + AWS\_DEFAULT\_REGION with a value of *region\-ID* @@ -305,7 +307,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index aabef48..b85d6c1 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 6b08cce..7208ccc 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -2,41 +2,50 @@ You might want to create your AWS CodeBuild builds on Amazon EFS\. Amazon EFS is a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What Is Amazon Elastic File System](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html)\. - This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system\. Before you begin, you must have a Java application ready to build that is uploaded to an Amazon S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repository\. + This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to a file system created in Amazon EFS\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repository\. + +Data in transit for your file system is encrypted\. To encrypt data in transit using a different image, see [Encrypting Data in Transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)\. ## Amazon Elastic File System and AWS CodeBuild Sample High\-Level Steps This sample covers the three high\-level steps required to use Amazon EFS with AWS CodeBuild: -1. Create an Amazon VPC\. +1. Create a virtual private cloud \(VPC\) in your AWS account\. + +1. Create a file system that uses this VPC\. -1. Create an Amazon EFS that uses this Amazon VPC\. +1. Create and build a CodeBuild project that uses the VPC\. The CodeBuild project uses the following to identify the file system: + + A unique file system identifier\. You choose the identifier when you specify the file system in your build project\. + + The file system ID\. The ID is displayed when you view your file system in the Amazon EFS console\. + + A mount point\. This is a directory in your Docker container that mounts the file system\. + + Mount options\. These include details about how to mount the file system\. -1. Create and build a CodeBuild project that uses the Amazon VPC\. Instructions that include how to mount an Amazon Elastic File System file system are entered into the buildspec editor when you build the project\. +**Note** + A file system created in Amazon EFS is supported on Linux platforms only\. -## Create an Amazon VPC Using AWS CloudFormation +## Create a VPC Using AWS CloudFormation - Create your Amazon VPC with an AWS CloudFormation template\. + Create your VPC with an AWS CloudFormation template\. -1. Follow the instructions here, [AWS CloudFormation VPC Template](cloudformation-vpc-template.md), to use AWS CloudFormation to create an Amazon VPC\. For more information, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide//Welcome.html)\. +1. Follow the instructions in [AWS CloudFormation VPC Template](cloudformation-vpc-template.md) to use AWS CloudFormation to create a VPC\. **Note** - The Amazon VPC created by this AWS CloudFormation template has two private subnets and two public subnets\. You must only use private subnets when you use AWS CodeBuild to mount Amazon EFS\. If you use one of the public subnets, the build fails\. + The VPC created by this AWS CloudFormation template has two private subnets and two public subnets\. You must only use private subnets when you use AWS CodeBuild to mount the file system you created in Amazon EFS\. If you use one of the public subnets, the build fails\. 1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console\.aws\.amazon\.com/vpc/](https://console.aws.amazon.com/vpc/)\. -1. Choose the Amazon VPC you created with AWS CloudFormation\. +1. Choose the VPC you created with AWS CloudFormation\. -1. Make a note of the VPC ID displayed on the **Summary** tab\. This ID is required when you create your AWS CodeBuild project later in this sample\. +1. On the **Description** tab, make a note of the name and ID of your VPC\. You need the name and ID when you create your AWS CodeBuild project later in this sample\. -## Create an Amazon Elastic File System File System with Your Amazon VPC +## Create a File System with Your VPC - Create a simple Amazon EFS file system for this sample using the Amazon VPC you created earlier\. + Create a simple file system for this sample using the VPC you created earlier\. 1. Sign in to the AWS Management Console and open the Amazon EFS console at [ https://console\.aws\.amazon\.com/efs/](https://console.aws.amazon.com/efs/)\. 1. Choose **Create file system**\. -1. From **VPC**, choose the VPC ID you noted earlier in this sample\. +1. From **VPC**, choose the VPC name you noted earlier in this sample\. 1. Leave the Availability Zones associated with your subnets selected\. @@ -44,15 +53,15 @@ 1. In **Add tags**, for the default **Name** key, in **Value**, enter the name of your Amazon EFS file system\. -1. Keep **General Purpose** and **Bursting** selected as your default performance and throughput modes, and then choose **Next Step**\. +1. Keep **Bursting** and **General Purpose** selected as your default performance and throughput modes, and then choose **Next Step**\. -1. Choose **Create File System**\. +1. For **Configure client access**, choose **Next Step**\. -1. Choose the name of the file system you created from the list\. Make a note of the DNS name\. You enter this in the buildspec file that is used to build your AWS CodeBuild project\. +1. Choose **Create File System**\. ## Create a CodeBuild Project to Use with Amazon EFS - Create a AWS CodeBuild project that uses the Amazon VPC you created earlier in this sample\. This CodeBuild project does not use a source and does not create an artifact\. When the build is run, it mounts the Amazon EFS file system created earlier in this sample and caches the Maven dependency to it\. + Create a 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\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -68,55 +77,56 @@ 1. From **Operating system**, choose **Amazon Linux 2**\. -1. From **Runtime\(s\)**, choose **Standard**\. +1. From **Runtime\(s\)**, choose **Standard**\. + +1. From **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. -1. From **Runtime version** choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:1\.0**\. +1. From **Environment type**, choose **Linux**\. 1. Select **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\. 1. Under **Service role**, choose **New service role**\. In **Role name**, enter a name for the role CodeBuild creates for you\. -1. For **Build specification**, choose **Insert build commands** and then choose **Switch to editor**\. +1. Expand **Additional configuration**\. + +1. From **VPC**, choose the VPC ID\. + +1. From **Subnets**, choose one or more of the private subnets associated with your VPC\. You must use private subnets in a build that mounts an Amazon EFS file system\. If you use a public subnet, the build fails\. + +1. From **Security Groups**, choose the default security group\. -1. Enter the following buildspec commands into the editor\. For the `EFS_DNS`, enter the DNS name of your file system\. +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 name of a directory in your build container that mounts the file system\. 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`\)\. ``` version: 0.2 - - env: - variables: - EFS_DIR: "/efs" - M3_HOME: ".m2" - EFS_DNS: "fs-11223344.efs.us-east-1.amazonaws.com" phases: install: runtime-versions: - java: openjdk11 - commands: - - mkdir -p $EFS_DIR - - apt-get update && apt-get install -y nfs-common - pre_build: - commands: - - mount -t nfs4 -o nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2 $EFS_DNS:/ $EFS_DIR - - df -h - - mkdir -p $EFS_DIR/$M3_HOME/ + java: corretto11 build: commands: - - mvn compile -Dgpg.skip=true -Dmaven.repo.local=$EFS_DIR/$M3_HOME/ + - mvn compile -Dgpg.skip=true -Dmaven.repo.local=$CODEBUILD_file-system-identifier ``` -1. Expand **Additional configuration**\. - -1. From **VPC**, choose the VPC ID\. - -1. From **Subnets**, choose one or more of the private subnets associated with your Amazon VPC\. You must use private subnets in a build that mounts an Amazon EFS file system\. If you use a public subnet, the build fails\. - -1. From **Security Groups**, choose the security group that works with your Amazon VPC\. - -1. Use the default values for all other settings, and then choose **Create build project**\. When your build is complete, you are on the console page for your project\. +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\. 1. Choose **Start build**\. ## CodeBuild and Amazon EFS Sample Summary - After your AWS CodeBuild project is built, you have a \.jar file created by your Java application\. The \.jar file is built to your Amazon EFS file system in a directory called `/efs/.m2`\. CodeBuild uses the mount command, `mount -t nfs4 -o nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2`, to mount the Amazon EFS file system\. For more information, see [Mounting File Systems](https://docs.aws.amazon.com/efs/latest/ug/mounting-fs.html)\. \ No newline at end of file + 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 diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 9886947..29387ee 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -51,7 +51,7 @@ In this scenario, you create and upload the source code\. You then use the AWS C ### Step A1: Add Files to the Source Code -In this step, you add an Elastic Beanstalk configuration file and a build spec file to the code in [Create the Source Code](#sample-elastic-beanstalk-prepare-source)\. You then upload the source code to an Amazon S3 input bucket or an AWS CodeCommit or GitHub repository \. +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 Amazon S3 input bucket or an AWS CodeCommit or GitHub repository \. 1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. @@ -139,7 +139,7 @@ In this scenario, you complete the steps to prepare and upload the source code\. ### Step B1: Add a Build Spec File to the Source Code -In this step, you create and add a build spec file to the code you created in [Create the Source Code](#sample-elastic-beanstalk-prepare-source)\. You then upload the source code to an Amazon S3 input bucket or a CodeCommit or GitHub repository\. +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 Amazon S3 input bucket or a CodeCommit or GitHub repository\. 1. Create a file named `buildspec.yml` with the following contents\. Store the file in the `(root directory name)/my-web-app` directory\. @@ -238,7 +238,7 @@ In this scenario, you complete the steps to prepare and upload the source code\. ### Step C1: Add Files to the Source Code -In this step, you add an Elastic Beanstalk configuration file and a build spec file to the code you created in [Create the Source Code](#sample-elastic-beanstalk-prepare-source)\. You also create or identify a service role for the build spec file\. +In this step, you add an Elastic Beanstalk configuration file and a buildspec file to the code you created in [Create the Source Code](#sample-elastic-beanstalk-prepare-source)\. You also create or identify a service role for the buildspec file\. 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)\. @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a build spec f If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index a8cfc2e..149849b 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -77,12 +77,10 @@ When you use the console to create or update a build project, you can create a C 1. Expand **Additional configuration**\. - In **VPC**, do one of the following: - + If you are not using a VPC for your project, choose **No 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\. + 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 CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. @@ -90,27 +88,27 @@ When you use the console to create or update a build project, you can create a C + 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 [Build Spec Reference](build-spec-ref.md)\. + 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 build output artifacts, choose **No artifacts**\. + To store the build output in an Amazon 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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. 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 Amazon S3 bucket where the cache is stored\. + + 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\. 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\. 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. For more information about caching, see [Build Caching in CodeBuild](build-caching.md)\. + 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 CodeBuild](build-caching.md)\. 1. Choose **Create build project**\. On the build project page, choose **Start build**\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 5c156c8..0cdc021 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -44,14 +44,14 @@ When you use the console to create or update a build project, you can create a C + 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 [Build Spec Reference](build-spec-ref.md)\. + 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 build output artifacts, choose **No artifacts**\. + To store the build output in an Amazon 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + 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\. @@ -71,7 +71,7 @@ When you use the console to create or update a build project, you can create a C 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 AWS CodeBuild region has been authorized\. +1. In your GitHub profile settings, under **Personal settings**, **Applications**, **Authorized OAuth Apps**, you should see that your AWS Region has been authorized\. ![\[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 diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index d02a246..ad6c073 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -6,7 +6,7 @@ You can use AWS CodeBuild to package and deploy serverless applications that fol 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 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*\. -## Related Resources +## Related Resources + For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. + For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. + For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ 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 fb9155d..37b0841 100644 --- a/doc_source/sample-pipeline-multi-input-output.md +++ b/doc_source/sample-pipeline-multi-input-output.md @@ -103,7 +103,7 @@ An AWS CodeBuild project can take more than one input source\. It can also creat In this JSON file: + 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. ++ 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)\. + ``` diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 4e05f37..8d74a97 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -114,7 +114,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co + 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:1\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. 1. Choose **Start build**\. @@ -176,7 +176,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co + 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:1\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. 1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index b46e276..eed6747 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -30,7 +30,7 @@ To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git 1. Create a build project\. For information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings: + In **Source**: - + For **Source provider**, choose **GitHub**\. If you are not connected to GitHub, ollow the instructions to connect\. + + For **Source provider**, choose **GitHub**\. If you are not connected to GitHub, follow the instructions to connect\. + For **Repository**, choose **Public repository**\. + For **Repository URL**, enter **https://github\.com/aws/aws\-sdk\-ruby\.git**\. + In **Environment**: diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 2bc9a15..63e6979 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -16,8 +16,8 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re + [Run and View Results of a Report](#sample-test-report-cli-run-and-view-report-results) ## Prerequisites -+ 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 format of your test cases can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create test files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and 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*\. ++ 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 format of your test cases can be JUnit XML, Cucumber JSON, Visual Studio TRX, or TestNG XML\. Create your test cases with any test framework that can create test files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and 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*\. + Make a note of the ARN of the IAM role you use\. You need the ARN when you create your build project\. + If your role does not have the following permissions, add them\. @@ -73,7 +73,7 @@ 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", + "arn": "arn:aws:codebuild:us-west-2::123456789012:report-group/report-name", "name": "report-name", "type": "TEST", "exportConfig": { @@ -82,7 +82,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "bucket": "s3-bucket-name", "path": "folder-path", "packaging": "NONE", - "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" + "encryptionKey": "arn:aws:kms:us-west-2::123456789012:alias/aws/s3" } }, "created": 1570837165.885, diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md index aace1bd..079001c 100644 --- a/doc_source/test-report-group-create-buildspec.md +++ b/doc_source/test-report-group-create-buildspec.md @@ -5,7 +5,7 @@ | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | -A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Specify Export Settings](report-group-export-settings.md)\. +A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Update a Report Group](report-group-export-settings.md)\. **To create a report group using a buildspec file** diff --git a/doc_source/test-report-group-create-cfn.md b/doc_source/test-report-group-create-cfn.md index 33e6c4b..89658e9 100644 --- a/doc_source/test-report-group-create-cfn.md +++ b/doc_source/test-report-group-create-cfn.md @@ -7,7 +7,7 @@ **To create a test report using the AWS CloudFormation template** - You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide//Welcome.html)\. + You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. The following AWS CloudFormation YAML template creates a report group that does not export raw test result files\. diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index b9c4017..4a04459 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -8,7 +8,7 @@ **To create a test report using the AWS CLI** + Create a file named `CreateReportGroup.json`\. -1. Depending on your requirements, copy one of the following JSON code snippets into `CreateReportGroup`: +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 S3 bucket\. ``` @@ -27,7 +27,7 @@ } ``` - 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 [Specify Export Settings](report-group-export-settings.md)\. + 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)\. + Use the following JSON to specify that your test report does not export raw test files: ``` diff --git a/doc_source/test-report-group-naming.md b/doc_source/test-report-group-naming.md index d05db0e..b214cd6 100644 --- a/doc_source/test-report-group-naming.md +++ b/doc_source/test-report-group-naming.md @@ -16,4 +16,4 @@ If you use the ARN of the report group named `my-report-group` in both projects, and then run builds of each project, you still have one report group \(`my-report-group`\)\. That report group contains test reports with results of tests run by both build projects\. - If you a choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. + If you a choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. \ No newline at end of file diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md index a1cc90a..134cb7d 100644 --- a/doc_source/test-report-group.md +++ b/doc_source/test-report-group.md @@ -13,7 +13,7 @@ A *report group* contains test reports and specifies shared settings\. You use t **Topics** + [Create a Report Group](report-group-create.md) -+ [Specify Export Settings](report-group-export-settings.md) ++ [Update a Report Group](report-group-export-settings.md) + [Specify Test Files](report-group-test-cases.md) + [Specify Test Commands](report-group-test-case-commands.md) + [Report Group Naming](test-report-group-naming.md) diff --git a/doc_source/test-report.md b/doc_source/test-report.md index 012423d..8252ea8 100644 --- a/doc_source/test-report.md +++ b/doc_source/test-report.md @@ -7,7 +7,7 @@ A report contains the results of test cases that are specified for one report group\. A test report is created during the run of a build project\. You specify a report group, test case files, and commands to run the test cases in its buildspec file\. Each time the test cases run, a new test report is created in the report group\. - A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Specify Export Settings](report-group-export-settings.md)\. + A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Update a Report Group](report-group-export-settings.md)\. The status of a test report can be one of the following: + `GENERATING`: The run of the test cases is still in progress\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 8c5e65e..5bca181 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting CodeBuild -Use the information in this topic to help you identify, diagnose, and address issues\. +Use the information in this topic to help you identify, diagnose, and address issues\. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see [Logging and Monitoring](security-incident-response.md)\. **Topics** + [Error: "CodeBuild is not authorized to perform: sts:AssumeRole" when creating or updating a build project](#troubleshooting-assume-role) @@ -92,6 +92,8 @@ artifacts: 1. Specify your environment image, operating system, runtime, and image\. These should match your settings for the build that failed\. 1. Select **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\. 1. Choose **Update environment**\. @@ -101,9 +103,9 @@ artifacts: **Issue:** When you run a build, the build log contains the warning, "Skipping install of runtimes\. Runtime version selection is not supported by this build image\." -**Possible cause:** Your build does not use version 1\.0 or later of the Amazon Linux \(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\. +**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 \(AL2\) standard image or later or the Ubuntu standard image version 2\.0 or later\. +**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: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build @@ -176,7 +178,7 @@ artifacts: **Possible cause:** In buildspec file version 0\.1, AWS CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. By default, then, you cannot run a single command that relies on the state of any previous commands\. -**Recommended solutions:** We recommend you use build spec version 0\.2, which solves this issue\. If you must use build spec version 0\.1 for some reason, we recommend using the shell command chaining operator \(for example, `&&` in Linux\) to combine multiple commands into a single command\. Or include a shell script in your source code that contains multiple commands, and then call that shell script from a single command in the buildspec file\. For more information, see [Shells and Commands in Build Environments](build-env-ref-cmd.md) and [Environment Variables in Build Environments](build-env-ref-env-vars.md)\. +**Recommended solutions:** We recommend you use build spec version 0\.2, which solves this issue\. If you must use buildspec version 0\.1 for some reason, we recommend using the shell command chaining operator \(for example, `&&` in Linux\) to combine multiple commands into a single command\. Or include a shell script in your source code that contains multiple commands, and then call that shell script from a single command in the buildspec file\. For more information, see [Shells and Commands in Build Environments](build-env-ref-cmd.md) and [Environment Variables in Build Environments](build-env-ref-env-vars.md)\. ## Apache Maven Builds Reference Artifacts from the Wrong Repository @@ -254,7 +256,7 @@ artifacts: **Possible cause:** Your build is using environment variables that are too large for AWS CodeBuild\. CodeBuild can raise errors once 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. +**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: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image @@ -359,7 +361,7 @@ pre_build: + The cache has recently been invalidated via the `InvalidateProjectCache` API\. + The service role being used by CodeBuild does not have `s3:GetObject` and `s3:PutObject` permissions to the Amazon S3 bucket that is holding the cache\. -**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the Amazon S3 bucket that is holding the cache\. For more information, see [Specifying S3 permissions\.](https://docs.aws.amazon.com/AmazonS3/latest/dev//using-with-s3-actions.html) +**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the Amazon S3 bucket that is holding the cache\. For more information, see [Specifying S3 permissions\.](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html) ## Error: "Unable to download cache: RequestError: send request failed caused by: x509: failed to load system roots and no roots provided" @@ -469,7 +471,7 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u 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)\. 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)\. -+ 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 [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. ++ 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)\. ``` version: 0.2 diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index c82a027..95fe9ad 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -149,7 +149,7 @@ sudo cat squid.key squid.crt | sudo tee squid.pem sudo service squid restart ``` - 1. Add `proxy` to your buildspec file\. For more information, see [Build Spec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + 1. Add `proxy` to your buildspec file\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. ``` version: 0.2 diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index b55e300..8bf127d 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -1,6 +1,6 @@ # Use CodeBuild with Amazon Virtual Private Cloud -Typically, resources in an VPC are not accessible by AWS CodeBuild\. To enable access, you must provide additional VPC\-specific configuration information as part of your CodeBuild project configuration\. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs\. VPC\-enabled builds are then able to access resources inside your VPC\. For more information about setting up a VPC in Amazon VPC, see the [VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Introduction.html)\. +Typically, resources in an VPC are not accessible by AWS CodeBuild\. To enable access, you must provide additional VPC\-specific configuration information as part of your CodeBuild project configuration\. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs\. VPC\-enabled builds are then able to access resources inside your VPC\. For more information about setting up a VPC in Amazon VPC, see the [VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. **Note** VPC connectivity from CodeBuild is not supported in Windows\. @@ -65,15 +65,15 @@ Replace us\-east\-1 with your region\. ## Best Practices for VPCs Use this checklist when setting 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)\. ++ 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)\. **Important** You need a NAT gateway or NAT instance in order to use CodeBuild with your Amazon 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\. + Include multiple Availability Zones with your VPC\. -+ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security Groups Rules](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_SecurityGroups.html#SecurityGroupRules)\. ++ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security Groups Rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. + Set up separate subnets for your builds\. + When you set up your CodeBuild projects to access your VPC, choose private subnets only\. -For more information about setting up a VPC in Amazon VPC, see the [Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Introduction.html)\. +For more information about setting up a VPC in Amazon VPC, see the [Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. For more information about using AWS CloudFormation to configure an Amazon VPC to use the CodeBuild VPC feature, see the [AWS CloudFormation VPC Template](cloudformation-vpc-template.md)\. @@ -83,17 +83,17 @@ When troubleshooting VPC issues, use the information that appears in the error m The following are some guidelines to assist you when troubleshooting a common CodeBuild VPC error: "Build does not have internet connectivity\. Please check subnet network configuration"\. -1. [Make sure that your internet gateway is attached to VPC](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. +1. [Make sure that your internet gateway is attached to VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. -1. [Make sure that the route table for your public subnet points to the internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Route_Tables.html#route-tables-internet-gateway)\. +1. [Make sure that the route table for your public subnet points to the internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#route-tables-internet-gateway)\. -1. [Make sure that your network ACLs allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_SecurityGroups.html#SecurityGroupRules)\. +1. [Make sure that your network ACLs allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. -1. [Make sure that your security groups allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_SecurityGroups.html#SecurityGroupRules)\. +1. [Make sure that your security groups allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. -1. [Troubleshoot your NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide//vpc-nat-gateway.html#nat-gateway-troubleshooting)\. +1. [Troubleshoot your NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html#nat-gateway-troubleshooting)\. -1. [Make sure that the route table for private subnets points to the NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide//VPC_Route_Tables.html#route-tables-nat)\. +1. [Make sure that the route table for private subnets points to the NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#route-tables-nat)\. 1. Make sure that the service role used by CodeBuild to interact with services on behalf of the IAM user has the permissions in [ this policy](https://docs.aws.amazon.com/codebuild/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html#customer-managed-policies-example-create-vpc-network-interface)\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. diff --git a/doc_source/welcome.md b/doc_source/welcome.md index fd84949..9fe38b7 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -33,7 +33,7 @@ The CodeBuild console also provides a way to quickly search for your resources, ## Pricing for CodeBuild -For information, see [CodeBuild Pricing](http://aws.amazon.com/codebuild/pricing)\. +For information, see [CodeBuild Pricing](https://aws.amazon.com/codebuild/pricing)\. ## How Do I Get Started with CodeBuild? From c27c057b1248583b129bcaa8ff377e7ad426de64 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Tue, 3 Mar 2020 04:57:19 +0000 Subject: [PATCH 027/156] Periodic update, March 2, 2020 --- doc_source/build-env-ref-available.md | 23 +++------- doc_source/build-spec-ref.md | 18 ++++---- doc_source/change-project.md | 2 +- doc_source/create-project.md | 2 +- doc_source/history.md | 2 +- doc_source/planning.md | 2 - doc_source/report-create.md | 2 +- doc_source/report-group-test-cases.md | 2 +- .../sample-disable-artifact-encryption.md | 6 +-- doc_source/sample-runtime-versions.md | 41 ++++++++++++----- .../test-report-group-create-buildspec.md | 2 +- doc_source/troubleshooting.md | 38 ---------------- doc_source/update-report-group-cli.md | 44 +++++++++++++++++++ doc_source/update-report-group-console.md | 24 ++++++++++ doc_source/use-codebuild-agent.md | 2 +- 15 files changed, 120 insertions(+), 90 deletions(-) create mode 100644 doc_source/update-report-group-cli.md create mode 100644 doc_source/update-report-group-console.md diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index d8aa1bb..d982088 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -15,26 +15,13 @@ AWS CodeBuild manages the following Docker images that are available in the Code 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.0-1.0.0`\. - The standard image of the Ubuntu 18\.04 and Amazon Linux 2 platforms contain the following runtimes\. If you use the Amazon Linux 2 standard image 1\.0 or later or the Ubuntu standard image 2\.0 or later, you must specify your runtime in the `runtime-versions` section of your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](build-spec-ref.md#runtime-versions-buildspec-file)\. + 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 its major version, its major version with the latest minor version, or the latest major and minor version\. The following table lists the available runtimes and how to specify them\. -| Runtime name | Version/versions | How to specify in the buildspec file | -| --- | --- | --- | -| android | 28, 29 | android: 28, android: 29 | -| docker | 18 | docker: 18 | -| dotnet | 2\.2 | dotnet: 2\.2 | -| dotnet \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 3\.0 | dotnet: 3\.0 | -| dotnet | 3\.1 | dotnet: 3\.1 | -| golang | 1\.12, 1\.13 | golang: 1\.12, golang: 1\.13 | -| nodejs | 8, 10 | nodejs: 8, nodejs: 10 | -| nodejs \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 10\.18, 12\.14 | nodejs: 10, nodejs: 12 | -| java \(Ubuntu only\) | openjdk8, openjdk11 | java: openjdk8, java: openjdk11 | -| java \(Amazon Linux 2 only\) | corretto8, corretto11 | java: corretto8, java: corretto11 | -| php | 7\.3 | php: 7\.3 | -| php | 7\.4 | php: 7\.4 | -| python | 3\.7 | python: 3\.7 | -| python \(Amazon Linux 2:2\.0 and Ubuntu Standard:3\.0 only\) | 3\.8 | python: 3\.8 | -| ruby | 2\.6 | ruby: 2\.6 | + +**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\)\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 1e7ae1d..31dc9ec 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -1,6 +1,6 @@ # Build Specification Reference for CodeBuild -This topic provides important reference information about build specification \(build spec\) files\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project\. For information about how a build spec works, see [How CodeBuild Works](concepts.md#concepts-how-it-works)\. +This topic provides important reference information about build specification \(buildspec\) files\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project\. For information about how a build spec works, see [How CodeBuild Works](concepts.md#concepts-how-it-works)\. **Topics** + [Buildspec File Name and Storage Location](#build-spec-ref-name-storage) @@ -33,9 +33,6 @@ If a command contains a character, or a string of characters, that is not suppor "export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')" ``` -**Important** -If you use the Ubuntu standard image 2\.0 or later, or the Amazon Linux 2 \(AL2\) standard image 1\.0 or later, you must specify `runtime-versions` in your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](#runtime-versions-buildspec-file)\. - The buildspec has the following syntax: ``` @@ -186,23 +183,24 @@ In buildspec version 0\.1, CodeBuild runs each command in a separate instance of The allowed build phase names are: + `install`: Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. - + `runtime-versions`: Required if using the Ubuntu standard image 2\.0 or later, or the Amazon Linux 2\.0 \(AL2\) standard image 1\.0 or later\. A runtime version is not supported with a custom image or the Ubuntu standard image 1\.0\. If specified, at least one runtime must be included in this section\. Specify a runtime using a major version only, such as "java: openjdk11" or "ruby: 2\.6\." You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, version 29 of Android, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. + + `runtime-versions`: Optional sequence\. A runtime version is supported with the Ubuntu standard image 2\.0 or later and the Amazon Linux 2 standard image 1\.0 or later\. If specified, at least one runtime must be included in this section\. Specify a runtime using a specific version, a major version followed by `.x` to specify that CodeBuild uses that major version with its latest minor version, or `latest` to use the most recent major and minor version \(for example, `java: openjdk11`, `ruby: 2.6`, `nodejs: 12.x`, or `java: latest`\)\. You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. ``` phases: install: runtime-versions: java: corretto8 - android: 29 + python: 3.x ruby: "$MY_RUBY_VAR" ``` - + Some runtimes must include specific versions of other runtimes\. If a required runtime is not specified, the build fails\. For example, if you use any supported version of `android`, then version 8 of Java is required\. If you use the Ubuntu standard image 2\.0, you specify this using `java: openjdk8`\. If you use the Amazon Linux 2 standard image 2\.0, you specify this using `java: corretto8`\. + + 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\. + + 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) **Note** 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\." - + `commands`: Required sequence unless you specify `runtime-versions`\. Optional if you specify `runtime-versions`\. 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\. + + `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\. + `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\. + `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\. + `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\. @@ -226,7 +224,7 @@ Commands in some build phases might not be run if commands in earlier build phas + `CucumberJson` + `VisualStudioTrx` + `TestNGXml` -+ `artifacts`: Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the Amazon 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\. ++ `artifacts`: Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the Amazon 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\. + `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`\)\. + A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. diff --git a/doc_source/change-project.md b/doc_source/change-project.md index 5002ae7..9183483 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -75,7 +75,7 @@ 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 build spec 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, 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\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 140f04b..9df4181 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -117,7 +117,7 @@ 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 build spec 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, 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\. diff --git a/doc_source/history.md b/doc_source/history.md index 9b03fde..bb07363 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **February 14, 2020 ++ **Latest documentation update: **March 2, 2020 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/planning.md b/doc_source/planning.md index cc27ff0..7692ae2 100644 --- a/doc_source/planning.md +++ b/doc_source/planning.md @@ -11,8 +11,6 @@ Before you run your build with CodeBuild, you must answer these questions: 1. **Which runtimes and tools do you need to run the build?** For example, are you building for Java, Ruby, Python, or Node\.js? Does the build need Maven or Ant or a compiler for Java, Ruby, or Python? Does the build need Git, the AWS CLI, or other tools? CodeBuild runs builds in build environments that use Docker images\. These Docker images must be stored in a repository type supported by CodeBuild\. These include the CodeBuild Docker image repository, Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\)\. For more information about the CodeBuild Docker image repository, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. -**Important** -If you use the Ubuntu standard image 2\.0 or later, or the Amazon Linux 2 \(AL2\) standard image 1\.0 or later, you must specify `runtime-versions` in your buildspec file\. For more information, see [Specify Runtime Versions in the Buildspec File](build-spec-ref.md#runtime-versions-buildspec-file)\. 1. **Do you need AWS resources that aren't provided automatically by CodeBuild? If so, which security policies will those resources need?** For example, you might need to modify the CodeBuild service role to allow CodeBuild to work with those resources\. diff --git a/doc_source/report-create.md b/doc_source/report-create.md index fa42a0d..dfccf8e 100644 --- a/doc_source/report-create.md +++ b/doc_source/report-create.md @@ -13,7 +13,7 @@ 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 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. 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)\. diff --git a/doc_source/report-group-test-cases.md b/doc_source/report-group-test-cases.md index c56ace9..6e608aa 100644 --- a/doc_source/report-group-test-cases.md +++ b/doc_source/report-group-test-cases.md @@ -5,7 +5,7 @@ | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports Syntax in the Buildspec File](build-spec-ref.md#reports-buildspec-file)\. + You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports Syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. The following is a sample `reports` section that specifies two report groups for a build project\. One is specified with its ARN, the other with a name\. The `files` section specifies the files that contain the test case results\. The optional `base-directory` section specifies the directory where the test case files are located\. The optional `discard-paths` section specifies whether paths to test result files uploaded to an S3 bucket are discarded\. diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index 036c157..f0b3851 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -36,11 +36,11 @@ When you use the console to create or update a build project, you can create a C 1. In **Artifacts**, for ** Type**, choose **Amazon S3** to store the build output in an Amazon S3 bucket\. -1. Select **Disable artifacts encryption**\. - 1. For **Bucket name**, choose the name of the Amazon S3 bucket you configured to function as a website in step 1\. -1. If you chose **Insert build commands** in **Environment**, then for **Output files**, enter the locations of the files from the build that you want to put into the output bucket\. If you have more than one location, use a comma to separate each location \(for example, "appspec\.yml, target/my\-app\.jar"\)\. +1. If you chose **Insert build commands** in **Buildspec**, then in the `files` section in `artifacts` of your commands, enter the locations of the files from the build that you want to put into the output bucket\. If you have more than one location, use a comma to separate each location \(for example, "appspec\.yml, target/my\-app\.jar"\)\. For more information, see [Artifacts reference-key in the buildspec file](build-spec-ref.md#artifacts-build-spec)\. + +1. Select **Disable artifacts encryption**\. 1. Expand **Additional configuration** and set options as appropriate\. diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 8d74a97..bda6169 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -1,6 +1,6 @@ # 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 must specify at least one runtime and its version 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, then your build must run in privileged mode\. For more information, see [Run a Build in CodeBuild](run-build.md) and [Create a Build Project in CodeBuild](create-project.md)\. @@ -123,8 +123,12 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 1. After the build is complete, view the build output on the **Build logs** tab\. You should see output similar to the following: ``` - [Container] 2019/05/14 20:45:07 Entering phase INSTALL - [Container] Date Time Running command echo "Installing Java version 8 ..." + [Container] Date Time Phase is DOWNLOAD_SOURCE + [Container] Date Time CODEBUILD_SRC_DIR=/codebuild/output/src460614277/src + [Container] Date Time YAML location is /codebuild/output/src460614277/src/buildspec.yml + [Container] Date Time Processing environment variables + [Container] Date Time Selecting 'java' runtime version 'corretto8' based on manual selections... + [Container] Date Time Running command echo "Installing Java version 8 ..." Installing Java version 8 ... [Container] Date Time Running command export JAVA_HOME="$JAVA_8_HOME" @@ -147,8 +151,11 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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] 2019/05/14 20:45:07 Entering phase INSTALL - [Container] Date Time Running command echo "Installing Java version 11 ..." + [Container] Date Time Phase is DOWNLOAD_SOURCE + [Container] Date Time CODEBUILD_SRC_DIR=/codebuild/output/src460614277/src + [Container] Date Time YAML location is /codebuild/output/src460614277/src/buildspec.yml + [Container] Date Time Processing environment variables + [Container] Date Time Selecting 'java' runtime version 'corretto11' based on manual selections... Installing Java version 11 ... [Container] Date Time Running command export JAVA_HOME="$JAVA_11_HOME" @@ -162,9 +169,9 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co ## 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 must also specify Java version 8\. + 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 must also specify Java version 8\. +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)\. @@ -209,7 +216,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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 INSTALL + [Container] 2019/05/14 23:21:42 Entering phase DOWNLOAD_SOURCES [Container] Date Time Running command echo "Installing Android version 29 ..." Installing Android version 29 ... @@ -337,16 +344,26 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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 Entering phase INSTALL + [Container] Date Time Processing environment variables + [Container] Date Time Selecting 'golang' runtime version '1.12' based on manual selections... + [Container] Date Time Selecting 'nodejs' runtime version '10' based on manual selections... [Container] Date Time Running command echo "Installing Go version 1.12 ..." Installing Go version 1.12 ... [Container] Date Time Running command echo "Installing Node.js version 10 ..." Installing Node.js version 10 ... - [Container] Date Time Running command n 10.15.3 - - [Container] Date Time Phase complete: INSTALL State: SUCCEEDED + [Container] Date Time Running command n 10.15.3 + + [Container] Date Time Moving to directory /codebuild/output/src819694850/src + [Container] Date Time Registering with agent + [Container] Date Time Phases found in YAML: 2 + [Container] Date Time INSTALL: 0 commands + [Container] Date Time BUILD: 1 commands + [Container] Date Time Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED + [Container] Date Time Phase context status code: Message: + [Container] Date Time Entering phase INSTALL + [Container] Date Time Phase complete: INSTALL State: SUCCEEDED [Container] Date Time Phase context status code: Message: [Container] Date Time Entering phase PRE_BUILD [Container] Date Time Phase complete: PRE_BUILD State: SUCCEEDED diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md index 079001c..f3722c8 100644 --- a/doc_source/test-report-group-create-buildspec.md +++ b/doc_source/test-report-group-create-buildspec.md @@ -21,7 +21,7 @@ A report group created using the buildspec does not export raw test result files base-directory: 'surefire/target/surefire-reports' ``` - For more information, see [Specify Test Files](report-group-test-cases.md) and [Reports Syntax in the Buildspec File](build-spec-ref.md#reports-buildspec-file)\. + For more information, see [Specify Test Files](report-group-test-cases.md) and [Reports Syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. 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)\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 5bca181..4144193 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -4,7 +4,6 @@ Use the information in this topic to help you identify, diagnose, and address is **Topics** + [Error: "CodeBuild is not authorized to perform: sts:AssumeRole" when creating or updating a build project](#troubleshooting-assume-role) -+ [Error: "This build image requires selecting at least one runtime version\."](#troubleshooting-build-must-specify-runtime) + [Error: "Cannot connect to the Docker daemon" when running a build](#troubleshooting-cannot-connect-to-docker-daemon) + [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: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build](#troubleshooting-input-bucket-different-region) @@ -20,7 +19,6 @@ Use the information in this topic to help you identify, diagnose, and address is + [Builds Might Fail When File Names Have Non\-U\.S\. English Characters](#troubleshooting-utf-8) + [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) -+ [Procedures in This Guide Do Not Match the CodeBuild Console](#troubleshooting-old-console) + ["Access denied" error message when attempting to download cache](#troubleshooting-dependency-caching) + [Error: "Unable to download cache: RequestError: send request failed caused by: x509: failed to load system roots and no roots provided"](#troubleshooting-cache-image) + [Error: "Unable to download certificate from S3\. AccessDenied"](#troubleshooting-certificate-in-S3) @@ -45,34 +43,6 @@ Use the information in this topic to help you identify, diagnose, and address is + Make sure the target CodeBuild service role exists in your AWS account\. If you are not using the console, make sure you did not misspell the Amazon Resource Name \(ARN\) of the service role when you created or updated the build project\. + Make sure the target CodeBuild service role has sufficient permissions to trust CodeBuild\. For more information, see the trust relationship policy statement in [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. -## 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\." - -**Possible cause:** Your build uses 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 not specified in the buildspec file\. - -**Recommended solution:** If you use the `aws/codebuild/standard:2.0` CodeBuild managed image, you must specify a runtime version in the `runtime-versions` section of the buildspec file\. For example, you might use the following buildspec file for a project that uses PHP: - -``` -version: 0.2 - -phases: - install: - runtime-versions: - php: 7.3 - build: - commands: - - php --version -artifacts: - files: - - README.md -``` - -**Note** - 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\." - - For more information, see [Specify Runtime Versions in the Buildspec File](build-spec-ref.md#runtime-versions-buildspec-file)\. - ## Error: "Cannot connect to the Docker daemon" when running a build **Issue: **Your build fails and you receive an error similar to `Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running?` in the build log\. @@ -344,14 +314,6 @@ pre_build: **Recommended solution:** To migrate a branch filter created prior to the introduction of webhook filters, create a webhook filter groups 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)\. -## Procedures in This Guide Do Not Match the CodeBuild Console - -**Issue:** This guide supports procedures in the new console design\. - - **Possible cause:** You are using the old console design\. This guide supports the new consolde design\. If you choose to use the older version of the console, you will find many of the concepts and basic procedures in this guide still apply\. To access help in the new console, choose the information icon\. - -**Recommended solution:** Use the latest console design\. - ## "Access denied" error message when attempting to download cache **Issue:** When attempting to download the cache on a build project that has cache enabled, you receive the following generic error: "Access denied"\. diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md new file mode 100644 index 0000000..4b30f86 --- /dev/null +++ b/doc_source/update-report-group-cli.md @@ -0,0 +1,44 @@ +# Update a Report Group \(CLI\) + +**To update a report group** + +1. Create a file named `UpdateReportGroupInput.json`\. + +1. Copy the following into `UpdateReportGroupInput.json`: + + ``` + { + "arn": "", + "exportConfig": { + "type": "S3", + "s3": { + "bucket": "bucket-name", + "path": "path", + "packaging": "NONE | ZIP", + "encryptionDisabled": "false", + "encryptionKey": "your-key" + } + } + } + ``` + +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 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\)\. + + 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: + + ``` + { + "exportConfig": { + "type": "NO_EXPORT" + } + } + ``` + +1. Run the following command: + + ``` + aws codebuild upate-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 new file mode 100644 index 0000000..c2a6d97 --- /dev/null +++ b/doc_source/update-report-group-console.md @@ -0,0 +1,24 @@ +# Update a Report Group \(Console\) + +**To update a report group** + +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 naviagation pane, choose **Report groups**\. + +1. Choose the report group you want to update\. + +1. Choose **Edit**\. + +1. Select or clear **Backup to Amazon S3**\. If you selected this option, specify your export settings: + + 1. For **S3 bucket name**, enter the name of the S3 bucket\. + + 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. 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 diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 531742e..b3eb2b9 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -14,7 +14,7 @@ codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] ``` - 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 `2c2b0a6b3595abfb5408cfa263d91ef280a910e2a03e920f65c3ffb9a97d0550`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + 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 `94467b3eeac4184d28a38feb27a1530691527dd49c17e30ad1b6331d791e82f5`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: ``` docker inspect amazon/aws-codebuild-local From faea3fc4391e943b7d56cb949ebe383f8433cd48 Mon Sep 17 00:00:00 2001 From: Shariq Mustaquim Date: Fri, 6 Mar 2020 01:34:36 +1100 Subject: [PATCH 028/156] Removed 7.4 There is no php7.4 in CodeBuild Linux environment --- doc_source/build-env-ref-available.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index d982088..c08f017 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -35,7 +35,7 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the | golang | 1\.13 | | nodejs | 10\.18, 12\.14 | | java | openjdk11 | -| php | 7\.3, 7\.4 | +| php | 7\.3 | | python | 3\.7 | | ruby | 2\.6 | @@ -51,4 +51,4 @@ CodeBuild frequently updates the list of Docker images\. To get the most current ``` 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)\. From 59ab227641264eb4951ce1c2d6982004f3e277e1 Mon Sep 17 00:00:00 2001 From: Mark Iverson Date: Mon, 16 Mar 2020 18:27:16 +0000 Subject: [PATCH 029/156] Periodic update, March 16, 2020. Included are new supported runtimes, integration with Codecov, and minor updates. --- doc_source/build-env-ref-available.md | 6 +- doc_source/codecov-integration.md | 108 ++++++++++++++++++ doc_source/create-project.md | 2 +- doc_source/data-protection.md | 2 +- ...ng-started-create-build-project-console.md | 3 +- doc_source/history.md | 2 +- doc_source/index.md | 1 + doc_source/run-build.md | 2 +- doc_source/sample-elastic-beanstalk.md | 4 +- doc_source/sample-runtime-versions.md | 2 +- doc_source/sample-source-version.md | 2 +- doc_source/security-encryption.md | 2 +- doc_source/troubleshooting.md | 4 +- 13 files changed, 126 insertions(+), 14 deletions(-) create mode 100644 doc_source/codecov-integration.md diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index c08f017..f31c10d 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -8,9 +8,11 @@ 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: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: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\-aarch64\-standard:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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) | | 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:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | | Windows Server Core 2016 | aws/codebuild/windows\-base:2\.0 | N/A | 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.0-1.0.0`\. @@ -35,7 +37,7 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the | golang | 1\.13 | | nodejs | 10\.18, 12\.14 | | java | openjdk11 | -| php | 7\.3 | +| php | 7\.3, 7\.4 | | python | 3\.7 | | ruby | 2\.6 | @@ -51,4 +53,4 @@ CodeBuild frequently updates the list of Docker images\. To get the most current ``` 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)\. ++ 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 diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md new file mode 100644 index 0000000..2c956b0 --- /dev/null +++ b/doc_source/codecov-integration.md @@ -0,0 +1,108 @@ +# Use AWS CodeBuild with Codecov + +Codecov is a tool that measures the test coverage of your code\. Codecov identifies which methods and statements in your code are not tested\. Use the results to determine where to write tests to improve the quality of your code\. Codecov is available for three of the source repositories supported by CodeBuild: GitHub, GitHub Enterprise, and Bitbucket\. If your build project uses GitHub Enterprise, you must use Codecov Enterprise\. + + When you run a build of a CodeBuild project that is integrated Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov Supported Languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. + +## Integrate Codecov into a build project + +**To integrate Codecov with your build project** + +1. Go to [https://codecov\.io/signup](https://codecov.io/signup) and sign up for a GitHub or Bitbucket source repository\. If you use GitHub Enterprise, see [Codecov Enterprise](https://codecov.io/enterprise) on the Codecov website\. + +1. In Codecov, add the repository for which you want coverage\. + +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. Create a text file named `my_script.sh` in your repository\. Enter the following into the file: + + ``` + #/bin/bash + bash <(curl -s https://codecov.io/bash) -t $CODECOV_TOKEN + ``` + +1. Choose the **Python** or **Java** tab, as appropriate for your build project uses, and follow these steps\. + +------ +#### [ Java ] + + 1. Add the following JaCoCo plugin to `pom.xml` in your repository\. + + ``` + + + + org.jacoco + jacoco-maven-plugin + 0.8.2 + + + + prepare-agent + + + + report + test + + report + + + + + + + ``` + + 1. Enter the following commands in your buildspec file\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + ``` + build: + - mvn test -f pom.xml -fn + postbuild: + - echo 'Connect to CodeCov' + - bash my_script.sh + ``` + +------ +#### [ Python ] + + Enter the following commands in your buildspec file\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + + ``` + build: + - pip install coverage + - coverage run -m unittest discover + postbuild: + - echo 'Connect to CodeCov' + - bash my_script.sh + ``` + +------ + +1. Run a build of your build project\. A link to Codecov reports generated for your project appears in your build logs\. Use the link to view the Codecov reports\. For more information, see [Run a Build in CodeBuild](run-build.md) and [Logging CodeBuild API Calls with AWS CloudTrail](cloudtrail.md)\. Codecov information in the build logs looks like the following: + + ``` + [Container] 2020/03/09 16:31:04 Running command bash my_script.sh + + _____ _ + / ____| | | + | | ___ __| | ___ ___ _____ __ + | | / _ \ / _` |/ _ \/ __/ _ \ \ / / + | |___| (_) | (_| | __/ (_| (_) \ V / + \_____\___/ \__,_|\___|\___\___/ \_/ + Bash-20200303-bc4d7e6 + + ·[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 + + [Container] 2020/03/09 16:31:07 Phase complete: POST_BUILD State: SUCCEEDED + ``` + + The reports look like the following: +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-report.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 diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 9df4181..8d0727a 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -374,7 +374,7 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + *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, or Bitbucket, an invalidInputException is thrown\. + *gitSubmodulesConfig*: Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise, 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 only\. Set this value to `true` to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. The default value is `false`\. *InsecureSsl* should be used for testing purposes only\. It should not be used in a production environment\. + + *InsecureSsl*: Optional\. Used with GitHub Enterprise only\. Set this value to `true` to ignore TSL warnings while connecting to your GitHub Enterprise 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\. diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 6bb7360..a925437 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -4,7 +4,7 @@ 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: + Use multi\-factor authentication \(MFA\) with each account\. -+ Use SSL/TLS to communicate with AWS resources\. ++ Use TLS to communicate with AWS resources\. + Set up API and user activity logging with AWS CloudTrail\. + Use AWS encryption solutions, along with all default security controls in 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\. diff --git a/doc_source/getting-started-create-build-project-console.md b/doc_source/getting-started-create-build-project-console.md index b1c8017..90c9c66 100644 --- a/doc_source/getting-started-create-build-project-console.md +++ b/doc_source/getting-started-create-build-project-console.md @@ -16,9 +16,10 @@ For this build environment, you instruct CodeBuild to use a Docker image that co 1. On the **Create build project** page, in **Project configuration**, for **Project name**, enter a name for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across each AWS account\. If you use a different name, be sure to use it throughout this tutorial\. **Note** -On the **Create build project** page, you might see an error message similar to the following: **User: *user\-ARN* is not authorized to perform: codebuild:ListProjects**\. This is most likely because you signed in to the AWS Management Console as an IAM user who does not have sufficient permissions to use CodeBuild in the console\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: +On the **Create build project** page, you might see an error message similar to the following: **You are not authorized to perform this operation\.**\. This is most likely because you signed in to the AWS Management Console as an IAM user who does not have permissions to create a build project\.\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: 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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. +Both options include administrator permissions that allow you to create a build project so you can complete this tutorial\. We recommend that you always use the minimum permissions required to accomplish your task\. For more information, see [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. 1. In **Source**, for **Source provider**, choose **Amazon S3**\. diff --git a/doc_source/history.md b/doc_source/history.md index bb07363..51e2266 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **March 2, 2020 ++ **Latest documentation update: **March 16, 2020 | Change | Description | Date | | --- |--- |--- | diff --git a/doc_source/index.md b/doc_source/index.md index a48ea48..f25b0dc 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -82,6 +82,7 @@ Amazon's trademarks and trade dress may not be used in + [Use CodeBuild with a Proxy Server](use-proxy-server.md) + [Use CodePipeline with 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 CodeBuild](builds-projects-and-builds.md) + [Working with Build Projects](working-with-build-projects.md) + [Create a Build Project in CodeBuild](create-project.md) diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 21306c1..5af4d49 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -189,7 +189,7 @@ For more information about using the AWS CLI with CodeBuild, see the [Command Li + *gitCloneDepthOverride*: Optional string\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. + *imageOverride*: Optional string\. The name of an image for this build that overrides the one specified in the build project\. + *idempotencyToken*: Optional string\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 12 hours after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. - + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure SSL setting specified in the build project\. The insecure SSL setting determines whether to ignore SSL warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise\. + + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TSL setting specified in the build project\. The insecure TSL setting determines whether to ignore TSL warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise\. + *privilegedModeOverride*: Optional boolean\. If set to true, the build overrides privileged mode in the build project\. + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out\. Its minimum value is five minutes and its maximum value is 480 minutes \(eight hours\)\. + *reportBuildStatusOverride*: Optional boolean that 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, or Bitbucket, an invalidInputException is thrown\. diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 29387ee..aec26af 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -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:1\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + For **Artifacts**: + For **Type**, choose **Amazon S3**\. + For **Bucket name**, enter the name of an Amazon S3 bucket\. @@ -195,7 +195,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:1\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + For **Artifacts**: + For **Type**, choose **Amazon S3**\. + For **Bucket name**, enter the name of an Amazon S3 bucket\. diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index bda6169..43ebcc4 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -333,7 +333,7 @@ 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:1\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. 1. Choose **Create build project**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index eed6747..680ccf5 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -37,7 +37,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:1\.0**\. + + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. 1. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 6c412f8..52f27c5 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -6,5 +6,5 @@ + 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.md#encryptionkey-console) and [Set the Encryption Key Using the CLI](create-project.md#encryptionkey-cli)\. 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 SSL 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/)\. ++ **Encryption of data in\-transit** \- All communication between customers and CodeBuild and between CodeBuild and its downstream dependencies is protected using TSL 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 KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 4144193..7e9a941 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -342,7 +342,7 @@ pre_build: + You have entered the wrong object key for your certificate\. **Recommended solutions:** -+ Edit your project\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. ++ Edit your project\. For **Bucket of certificate**, choose the S3 bucket where your TSL certificate is stored\. + Edit your project\. For **Object key of certificate**, type the name of your S3 object key\. ## Error: "Git Clone Failed: unable to access `'your-repository-URL'`: SSL certificate problem: self signed certificate" @@ -352,7 +352,7 @@ pre_build: **Possible cause:** Your source repository has a self\-signed certificate, but you have not chosen to install the certificate from your S3 bucket as part of your build project\. **Recommended solutions:** -+ Edit your project\. For **Certificate**, choose **Install certificate from S3**\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. For **Object key of certificate**, type the name of your S3 object key\. ++ Edit your project\. For **Certificate**, choose **Install certificate from S3**\. For **Bucket of certificate**, choose the S3 bucket where your TSL certificate is stored\. For **Object key of certificate**, type the name of your S3 object key\. + Edit your project\. Select **Insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. **Note** We recommend that you use **Insecure SSL** for testing only\. It should not be used in a production environment\. From 82013d804582d0a37da57394968029a802187f44 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 15 May 2020 15:23:42 -0700 Subject: [PATCH 030/156] General update. --- doc_source/advanced-topics.md | 10 +- ...ntrol-iam-access-control-identity-based.md | 44 +- ...ntrol-iam-identity-based-access-control.md | 170 +++--- ...nd-access-control-permissions-reference.md | 6 +- .../auth-and-access-control-using-tags.md | 12 +- doc_source/auth-and-access-control.md | 26 +- doc_source/build-caching.md | 36 +- doc_source/build-env-ref-available.md | 12 +- doc_source/build-env-ref-background-tasks.md | 2 +- doc_source/build-env-ref-cmd.md | 14 +- doc_source/build-env-ref-compute-types.md | 10 +- doc_source/build-env-ref-env-vars.md | 18 +- doc_source/build-env-ref.md | 20 +- doc_source/build-spec-ref.md | 59 +- doc_source/builds-projects-and-builds.md | 8 +- doc_source/builds-working.md | 20 +- doc_source/change-project.md | 36 +- doc_source/cloudformation-vpc-template.md | 6 +- doc_source/cloudtrail.md | 20 +- doc_source/cmd-ref.md | 32 +- doc_source/codebuild-compliance-validation.md | 2 +- doc_source/codecov-integration.md | 10 +- doc_source/concepts.md | 26 +- doc_source/console-resources.md | 4 +- doc_source/create-project.md | 125 ++--- doc_source/data-protection.md | 10 +- doc_source/delete-builds.md | 14 +- doc_source/delete-project.md | 24 +- doc_source/endpoint-specify.md | 10 +- .../getting-started-build-log-console.md | 12 +- .../getting-started-clean-up-console.md | 8 +- doc_source/getting-started-cli-build-log.md | 12 +- doc_source/getting-started-cli-clean-up.md | 8 +- ...etting-started-cli-create-build-project.md | 16 +- .../getting-started-cli-create-build-spec.md | 14 +- .../getting-started-cli-create-source-code.md | 8 +- .../getting-started-cli-input-bucket.md | 10 +- .../getting-started-cli-monitor-build.md | 8 +- doc_source/getting-started-cli-next-steps.md | 4 +- doc_source/getting-started-cli-output.md | 10 +- doc_source/getting-started-cli-run-build.md | 8 +- .../getting-started-cli-upload-source-code.md | 10 +- doc_source/getting-started-cli.md | 26 +- ...ng-started-create-build-project-console.md | 12 +- ...tting-started-create-build-spec-console.md | 14 +- ...ting-started-create-source-code-console.md | 8 +- .../getting-started-input-bucket-console.md | 10 +- .../getting-started-monitor-build-console.md | 8 +- .../getting-started-next-steps-console.md | 4 +- doc_source/getting-started-output-console.md | 10 +- doc_source/getting-started-overview.md | 6 +- .../getting-started-run-build-console.md | 8 +- ...ting-started-upload-source-code-console.md | 10 +- doc_source/getting-started.md | 28 +- doc_source/glossary.md | 4 +- doc_source/history.md | 131 ++--- doc_source/how-to-create-pipeline.md | 189 +++---- doc_source/how-to-integrate-config.md | 20 +- doc_source/how-to-run.md | 29 +- doc_source/index.md | 260 ++++----- doc_source/infrastructure-security.md | 2 +- doc_source/jenkins-plugin.md | 22 +- doc_source/limits.md | 38 +- doc_source/monitoring-alarms.md | 4 +- doc_source/monitoring-builds.md | 8 +- doc_source/monitoring-metrics.md | 6 +- doc_source/notice.md | 54 +- doc_source/notification-rule-create.md | 23 +- doc_source/planning.md | 18 +- doc_source/project-sharing.md | 47 +- doc_source/report-create.md | 14 +- doc_source/report-group-create.md | 12 +- doc_source/report-group-export-settings.md | 4 +- doc_source/report-group-test-case-commands.md | 2 +- doc_source/report-group-test-cases.md | 4 +- doc_source/report-groups-sharing.md | 36 +- doc_source/run-build.md | 96 ++-- doc_source/sample-access-tokens.md | 18 +- doc_source/sample-bitbucket-pull-request.md | 103 +++- doc_source/sample-build-badges.md | 34 +- doc_source/sample-build-notifications.md | 88 +-- .../sample-buildspec-artifact-naming.md | 14 +- doc_source/sample-codedeploy.md | 40 +- .../sample-disable-artifact-encryption.md | 20 +- doc_source/sample-docker-custom-image.md | 36 +- doc_source/sample-docker.md | 65 +-- doc_source/sample-ecr.md | 52 +- doc_source/sample-efs.md | 24 +- doc_source/sample-elastic-beanstalk.md | 110 ++-- doc_source/sample-github-enterprise.md | 24 +- doc_source/sample-github-pull-request.md | 78 ++- doc_source/sample-lambda.md | 14 +- doc_source/sample-multi-in-out.md | 20 +- .../sample-pipeline-multi-input-output.md | 12 +- doc_source/sample-private-registry.md | 14 +- doc_source/sample-runtime-versions.md | 34 +- doc_source/sample-source-version.md | 12 +- doc_source/sample-test-report-cli.md | 26 +- doc_source/sample-windows.md | 40 +- doc_source/samples.md | 42 +- doc_source/sdk-ref.md | 8 +- doc_source/security-encryption.md | 6 +- doc_source/security-incident-response.md | 6 +- doc_source/security-key-management.md | 8 +- doc_source/security-traffic-privacy.md | 4 +- doc_source/security.md | 10 +- doc_source/setting-up.md | 64 +-- doc_source/stop-build.md | 20 +- doc_source/test-permissions.md | 36 +- .../test-report-group-create-buildspec.md | 10 +- doc_source/test-report-group-create-cfn.md | 6 +- doc_source/test-report-group-create-cli.md | 6 +- .../test-report-group-create-console.md | 6 +- doc_source/test-report-group-naming.md | 2 +- doc_source/test-report-group.md | 14 +- doc_source/test-report.md | 6 +- doc_source/test-reporting.md | 14 +- doc_source/test-view-reports.md | 14 +- doc_source/trigger-create.md | 8 +- doc_source/triggers-edit.md | 10 +- doc_source/troubleshooting.md | 528 ++++++++++-------- doc_source/update-report-group-cli.md | 2 +- doc_source/update-report-group-console.md | 2 +- doc_source/use-case-based-samples.md | 46 +- doc_source/use-codebuild-agent.md | 42 +- doc_source/use-proxy-server.md | 104 ++-- .../use-vpc-endpoints-with-codebuild.md | 20 +- doc_source/view-build-details.md | 26 +- doc_source/view-build-list.md | 18 +- doc_source/view-builds-for-project.md | 20 +- doc_source/view-project-details.md | 24 +- doc_source/view-project-list.md | 18 +- doc_source/vpc-support.md | 70 ++- doc_source/welcome.md | 26 +- doc_source/working-with-build-projects.md | 20 +- 135 files changed, 2147 insertions(+), 2078 deletions(-) diff --git a/doc_source/advanced-topics.md b/doc_source/advanced-topics.md index 69c0201..2a94617 100644 --- a/doc_source/advanced-topics.md +++ b/doc_source/advanced-topics.md @@ -1,9 +1,9 @@ -# Advanced Topics +# Advanced topics This section includes several advanced topics that are useful to more experienced AWS CodeBuild users\. **Topics** -+ [Advanced Setup](setting-up.md) -+ [Command Line Reference for CodeBuild](cmd-ref.md) -+ [AWS SDKs and Tools Reference for CodeBuild](sdk-ref.md) -+ [Specify the CodeBuild Endpoint](endpoint-specify.md) \ No newline at end of file ++ [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 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 b426f7c..8022441 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 @@ -1,19 +1,19 @@ -# Overview of Managing Access Permissions to Your CodeBuild Resources +# Overview of managing access permissions to your AWS CodeBuild resources Every AWS resource is owned by an AWS account, and permissions to create or access a resource are governed by permissions policies\. An account administrator can attach permissions policies to IAM identities \(that is, users, groups, and roles\)\. **Note** -An account administrator \(or administrator user\) is a user with administrator privileges\. For more information, see [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide Guide*\. +An account administrator \(or administrator user\) is a user with administrator privileges\. For more information, see [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*\. When you grant permissions, you decide who is getting the permissions, the resources they can access, and the actions that can be performed on those resources\. **Topics** -+ [CodeBuild Resources and Operations](#arn-formats) -+ [Understanding Resource Ownership](#understanding-resource-ownership) -+ [Managing Access to Resources](#managing-access-resources) -+ [Specifying Policy Elements: Actions, Effects, and Principals](#actions-effects-principals) ++ [AWS CodeBuild resources and operations](#arn-formats) ++ [Understanding resource ownership](#understanding-resource-ownership) ++ [Managing access to resources](#managing-access-resources) ++ [Specifying policy elements: Actions, effects, and principals](#actions-effects-principals) -## CodeBuild Resources and Operations +## AWS CodeBuild resources and operations In AWS CodeBuild, the primary resource is a build project\. In a policy, you use an Amazon Resource Name \(ARN\) to identify the resource the policy applies to\. Builds are also resources and have ARNs associated with them\. For more information, see [Amazon Resource Names \(ARN\) and AWS Service Namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the *Amazon Web Services General Reference*\. @@ -51,28 +51,28 @@ Some CodeBuild API actions accept multiple resources \(for example, `BatchGetPro ] ``` -CodeBuild provides a set of operations to work with the CodeBuild resources\. For a list, see [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. +CodeBuild provides a set of operations to work with the CodeBuild resources\. For a list, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. -## Understanding Resource Ownership +## Understanding resource ownership The AWS account owns the resources that are created in the account, regardless of who created the resources\. Specifically, the resource owner is the AWS account of the [principal entity](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html) \(that is, the root account, an IAM user, or an IAM role\) that authenticates the resource creation request\. The following examples illustrate how this works: + If you use the root account credentials of your AWS account to create a rule, your AWS account is the owner of the CodeBuild resource\. + If you create an IAM user in your AWS account and grant permissions to create CodeBuild resources to that user, the user can create CodeBuild resources\. However, your AWS account, to which the user belongs, owns the CodeBuild resources\. + If you create an IAM role in your AWS account with permissions to create CodeBuild resources, anyone who can assume the role can create CodeBuild resources\. Your AWS account, to which the role belongs, owns the CodeBuild resources\. -## Managing Access to Resources +## Managing access to resources 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 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 Guide*\. +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\. -### Identity\-Based Policies +### Identity\-based policies You can attach policies to IAM identities\. -+ **Attach a permissions policy to a user or a group in your account** – To grant a user permissions to view build projects and other AWS CodeBuild resources in the CodeBuild console, you can attach a permissions policy to a user or group that the user belongs to\. ++ **Attach a permissions policy to a user or a group in your account** – To grant a user permissions to view build projects and other AWS CodeBuild resources in the AWS CodeBuild console, you can attach a permissions policy to a user or group that the user belongs to\. + **Attach a permissions policy to a role \(grant cross\-account permissions\)** – You can attach an identity\-based permissions policy to an IAM role to grant cross\-account permissions\. For example, the administrator in Account A can create a role to grant cross\-account permissions to another AWS account \(for example, Account B\) or an AWS service as follows: 1. Account A administrator creates an IAM role and attaches a permissions policy to the role that grants permissions on resources in Account A\. @@ -81,23 +81,23 @@ You can attach policies to IAM identities\. 1. Account B administrator can then delegate permissions to assume the role to any users in Account B\. Doing this allows users in Account B to create or access resources in Account A\. The principal in the trust policy must also be an AWS service principal if you want to grant an AWS service permissions to assume the role\. - For more information about using IAM to delegate permissions, see [Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide Guide*\. + For more information about using IAM to delegate permissions, see [Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide*\. In CodeBuild, identity\-based policies are used to manage permissions to the resources related to the deployment process\. For example, you can control access to build projects\. -You can create IAM policies to restrict the calls and resources that users in your account have access to, and then attach those policies to IAM users\. For more information about how to create IAM roles and to explore example IAM policy statements for CodeBuild, see [Overview of Managing Access Permissions to Your CodeBuild Resources](#auth-and-access-control-iam-access-control-identity-based)\. +You can create IAM policies to restrict the calls and resources that users in your account have access to, and then attach those policies to IAM users\. For more information about how to create IAM roles and to explore example IAM policy statements for CodeBuild, see [Overview of managing access permissions to your AWS CodeBuild resources](#auth-and-access-control-iam-access-control-identity-based)\. -### Secure Access to Amazon S3 Buckets +### Secure access to S3 buckets -We strongly recommend that you include the following permissions in your IAM role to verify the Amazon 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 be add them yourself\. +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 be add them yourself\. + `s3:GetBucketACL` + `s3:GetBucketLocation` -If the owner of an Amazon 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)\. +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)\. -## Specifying Policy Elements: Actions, Effects, and Principals +## Specifying policy elements: Actions, effects, and principals -For each AWS CodeBuild resource, the service defines a set of API operations\. To grant permissions for these API operations, CodeBuild defines a set of actions that you can specify in a policy\. Some API operations can require permissions for more than one action in order to perform the API operation\. For more information, see [CodeBuild Resources and Operations](#arn-formats) and [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. +For each AWS CodeBuild resource, the service defines a set of API operations\. To grant permissions for these API operations, CodeBuild defines a set of actions that you can specify in a policy\. Some API operations can require permissions for more than one action in order to perform the API operation\. For more information, see [AWS CodeBuild resources and operations](#arn-formats) and [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. The following are the basic policy elements: + **Resource** – You use an Amazon Resource Name \(ARN\) to identify the resource that the policy applies to\. @@ -105,6 +105,6 @@ The following are the basic policy elements: + **Effect** – You specify the effect, either allow or deny, when the user requests the action\. If you don't explicitly grant access to \(allow\) a resource, access is implicitly denied\. You can also explicitly deny access to a resource\. You might do this to make sure a user cannot access a resource, even if a different policy grants access\. + **Principal** – In identity\-based policies \(IAM policies\), the user the policy is attached to is the implicit principal\. For resource\-based policies, you specify the user, account, service, or other entity that you want to receive permissions\. -To learn more 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 Guide*\. +To learn more 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*\. -For a table showing all of the CodeBuild API actions and the resources they apply to, see the [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. \ No newline at end of file +For a table showing all of the CodeBuild API actions and the resources they apply to, see the [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. \ No newline at end of file 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 44bff02..1de8277 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 @@ -1,16 +1,16 @@ -# Using Identity\-Based Policies for CodeBuild +# Using identity\-based policies for AWS CodeBuild This topic provides examples of identity\-based policies that demonstrate how an account administrator can attach permissions policies to IAM identities \(that is, users, groups, and roles\) and thereby grant permissions to perform operations on AWS CodeBuild resources\. **Important** -We recommend that you first review the introductory topics that explain the basic concepts and options available to manage access to your CodeBuild resources\. For more information, see [Overview of Managing Access Permissions to Your CodeBuild Resources](auth-and-access-control-iam-access-control-identity-based.md)\. +We recommend that you first review the introductory topics that explain the basic concepts and options available to manage access to your CodeBuild resources\. For more information, see [Overview of managing access permissions to your AWS CodeBuild resources](auth-and-access-control-iam-access-control-identity-based.md)\. **Topics** -+ [Permissions Required to Use the CodeBuild Console](#console-permissions) -+ [Permissions Required for the CodeBuild Console to Connect to Source Providers](#console-policies) -+ [AWS Managed \(Predefined\) Policies for CodeBuild](#managed-policies) ++ [Permissions required to use the AWS CodeBuild console](#console-permissions) ++ [Permissions required for the AWS CodeBuild console to connect to source providers](#console-policies) ++ [AWS managed \(predefined\) policies for AWS CodeBuild](#managed-policies) + [CodeBuild Managed Policies and Notifications](#notifications-permissions) -+ [Customer\-Managed Policy Examples](#customer-managed-policies) ++ [Customer\-managed policy examples](#customer-managed-policies) The following shows an example of a permissions policy that allows a user to get information about build projects only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: @@ -27,7 +27,7 @@ The following shows an example of a permissions policy that allows a user to get } ``` -## Permissions Required to Use the CodeBuild Console +## Permissions required to use the AWS CodeBuild console A user who uses the AWS CodeBuild console must have a minimum set of permissions that allows the user to describe other AWS resources for the AWS account\. You must have permissions from the following services: + AWS CodeBuild @@ -41,7 +41,7 @@ A user who uses the AWS CodeBuild console must have a minimum set of permissions If you create an IAM policy that is more restrictive than the minimum required permissions, the console won't function as intended\. -## Permissions Required for the CodeBuild Console to Connect to Source Providers +## Permissions required for the AWS CodeBuild console to connect to source providers The AWS CodeBuild console uses the following API actions to connect to source providers \(for example, GitHub repositories\)\. + `codebuild:ListConnectedOAuthAccounts` @@ -49,32 +49,32 @@ The AWS CodeBuild console uses the following API actions to connect to source pr + `codebuild:PersistOAuthToken` + `codebuild:ImportSourceCredentials` -You can associate source providers \(such as GitHub repositories\) with your build projects using the CodeBuild console\. To do this, you must first add the preceding API actions to IAM access policies associated with the IAM user you use to access the CodeBuild console\. +You can associate source providers \(such as GitHub repositories\) with your build projects using the AWS CodeBuild console\. To do this, you must first add the preceding API actions to IAM access policies associated with the IAM user you use to access the AWS CodeBuild console\. The `ListConnectedOAuthAccounts`, `ListRepositories`, and `PersistOAuthToken` API actions are not intended to be called by your code\. Therefore, these API actions are not included in the AWS CLI and AWS SDKs\. -## AWS Managed \(Predefined\) Policies for CodeBuild +## 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\. 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**\. +To access build output artifacts that CodeBuild creates, you must also attach the AWS managed policy named `AmazonS3ReadOnlyAccess`\. -To create and manage CodeBuild service roles, you must also attach the AWS managed policy named **IAMFullAccess**\. +To create and manage CodeBuild service roles, you must also attach the AWS managed policy named `IAMFullAccess`\. You can also create your own custom IAM policies to allow permissions for CodeBuild actions and resources\. You can attach these custom policies to the IAM users or groups that require those permissions\. ## CodeBuild Managed Policies and Notifications -CodeBuild supports notifications, which can notify users of important changes to build projects\. Managed policies for CodeBuild include policy statements for notification functionality\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html)\. +CodeBuild supports notifications, which can notify users of important changes to build projects\. Managed policies for CodeBuild include policy statements for notification functionality\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html)\. ### Permissions Related to Notifications in Full Access Managed Policies -The `AWSCodeBuildFullAccess` managed policy includes the following statements to allow full access to notifications\. Users with this managed policy applied can also create and manage Amazon SNS topics for notifications, subscribe and unsubscribe users to topics, and list topics to choose as targets for notification rules\. +The `AWSCodeBuildFullAccess` managed policy includes the following statements to allow full access to notifications\. Users with this managed policy applied can also create and manage Amazon SNS topics for notifications, subscribe and unsubscribe users to topics, list topics to choose as targets for notification rules, and list AWS Chatbot clients configured for Slack\. ``` { @@ -99,7 +99,8 @@ The `AWSCodeBuildFullAccess` managed policy includes the following statements to "Action": [ "codestar-notifications:ListNotificationRules", "codestar-notifications:ListTargets", - "codestar-notifications:ListTagsforResource" + "codestar-notifications:ListTagsforResource", + "codestar-notifications:ListEventTypes" ], "Resource": "*" }, @@ -119,6 +120,14 @@ The `AWSCodeBuildFullAccess` managed policy includes the following statements to "sns:ListTopics" ], "Resource": "*" + }, + { + "Sid": "CodeStarNotificationsChatbotAccess", + "Effect": "Allow", + "Action": [ + "chatbot:DescribeSlackChannelConfigurations" + ], + "Resource": "*" } ``` @@ -142,7 +151,9 @@ The `AWSCodeBuildReadOnlyAccess` managed policy includes the following statement "Sid": "CodeStarNotificationsListAccess", "Effect": "Allow", "Action": [ - "codestar-notifications:ListNotificationRules" + "codestar-notifications:ListNotificationRules", + "codestar-notifications:ListEventTypes", + "codestar-notifications:ListTargets" ], "Resource": "*" } @@ -174,7 +185,8 @@ The `AWSCodeBuildDeveloperAccess` managed policy includes the following statemen "Action": [ "codestar-notifications:ListNotificationRules", "codestar-notifications:ListTargets", - "codestar-notifications:ListTagsforResource" + "codestar-notifications:ListTagsforResource", + "codestar-notifications:ListEventTypes" ], "Resource": "*" }, @@ -185,44 +197,52 @@ The `AWSCodeBuildDeveloperAccess` managed policy includes the following statemen "sns:ListTopics" ], "Resource": "*" + }, + { + "Sid": "CodeStarNotificationsChatbotAccess", + "Effect": "Allow", + "Action": [ + "chatbot:DescribeSlackChannelConfigurations" + ], + "Resource": "*" } ``` For more information about IAM and notifications, see [Identity and Access Management for AWS CodeStar Notifications](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security-iam.html)\. -## Customer\-Managed Policy Examples +## Customer\-managed policy examples -In this section, you can find example user policies that grant permissions for AWS CodeBuild actions\. These policies work when you are using the CodeBuild API, AWS SDKs, or AWS CLI\. When you are using the console, you must grant additional permissions specific to the console\. For information, see [Permissions Required to Use the CodeBuild Console](#console-permissions)\. +In this section, you can find example user policies that grant permissions for AWS CodeBuild actions\. These policies work when you are using the CodeBuild API, AWS SDKs, or AWS CLI\. When you are using the console, you must grant additional permissions specific to the console\. For information, see [Permissions required to use the AWS CodeBuild console](#console-permissions)\. You can use the following sample IAM policies to limit CodeBuild access for your IAM users and roles\. **Topics** -+ [Allow a User to Get Information About Build Projects](#customer-managed-policies-example-batch-get-projects) -+ [Allow a User to Get Information About Report Groups](#customer-managed-policies-get-information-about-report-group) -+ [Allow a User to Get Information About Reports](#customer-managed-policies-get-information-about-reports) -+ [Allow a User to Create Build Projects](#customer-managed-policies-example-create-project) -+ [Allow a User to Create a Report Group](#customer-managed-policies-example-create-report-group) -+ [Allow a User to Delete a Report Group](#customer-managed-policies-example-delete-report-group) -+ [Allow a User to Delete a Report](#customer-managed-policies-example-delete-report) -+ [Allow a User to Delete Build Projects](#customer-managed-policies-example-delete-project) -+ [Allow a User to Get a List of Build Project Names](#customer-managed-policies-example-list-projects) -+ [Allow a User to Change Information About Build Projects](#customer-managed-policies-example-update-project) -+ [Allow a User to Change a Report Group](#customer-managed-policies-example-change-report-group) -+ [Allow a User to Get Information About Builds](#customer-managed-policies-example-batch-get-builds) -+ [Allow a User to Get a List of Build IDs for a Build Project](#customer-managed-policies-example-list-builds-for-project) -+ [Allow a User to Get a List of Build IDs](#customer-managed-policies-example-list-builds) -+ [Allow a User to Get a List of Report Groups](#customer-managed-policies-example-get-list-of-report-groups) -+ [Allow a User to Get a List of Reports](#customer-managed-policies-example-get-list-of-reports) -+ [Allow a User to Get a List of Reports for a Report Group](#customer-managed-policies-example-get-list-of-reports-for-report-group) -+ [Allow a User to Get a List of Test Cases for a Report](#customer-managed-policies-example-get-list-of-test-cases-for-report) -+ [Allow a User to Start Running Builds](#customer-managed-policies-example-start-build) -+ [Allow a User to Attempt to Stop Builds](#customer-managed-policies-example-stop-build) -+ [Allow a User to Attempt to Delete Builds](#customer-managed-policies-example-delete-builds) -+ [Allow a User to Get Information About Docker Images That Are Managed by CodeBuild](#customer-managed-policies-example-list-curated-environment-images) -+ [Allow CodeBuild Access to AWS Services Required to Create a VPC Network Interface](#customer-managed-policies-example-create-vpc-network-interface) -+ [Use a Deny Statement to Prevent CodeBuild from Disconnecting from Source Providers](#customer-managed-policies-example-deny-disconnect) - -### Allow a User to Get Information About Build Projects ++ [Allow a user to get information about build projects](#customer-managed-policies-example-batch-get-projects) ++ [Allow a user to get information about report groups](#customer-managed-policies-get-information-about-report-group) ++ [Allow a user to get information about reports](#customer-managed-policies-get-information-about-reports) ++ [Allow a user to create build projects](#customer-managed-policies-example-create-project) ++ [Allow a user to create a report group](#customer-managed-policies-example-create-report-group) ++ [Allow a user to delete a report group](#customer-managed-policies-example-delete-report-group) ++ [Allow a user to delete a report](#customer-managed-policies-example-delete-report) ++ [Allow a user to delete build projects](#customer-managed-policies-example-delete-project) ++ [Allow a user to get a list of build project names](#customer-managed-policies-example-list-projects) ++ [Allow a user to change information about build projects](#customer-managed-policies-example-update-project) ++ [Allow a user to change a report group](#customer-managed-policies-example-change-report-group) ++ [Allow a user to get information about builds](#customer-managed-policies-example-batch-get-builds) ++ [Allow a user to get a list of build IDs for a build project](#customer-managed-policies-example-list-builds-for-project) ++ [Allow a user to get a list of build IDs](#customer-managed-policies-example-list-builds) ++ [Allow a user to get a list of report groups](#customer-managed-policies-example-get-list-of-report-groups) ++ [Allow a user to get a list of reports](#customer-managed-policies-example-get-list-of-reports) ++ [Allow a user to get a list of reports for a report group](#customer-managed-policies-example-get-list-of-reports-for-report-group) ++ [Allow a user to get a list of test cases for a report](#customer-managed-policies-example-get-list-of-test-cases-for-report) ++ [Allow a user to start running builds](#customer-managed-policies-example-start-build) ++ [Allow a user to attempt to stop builds](#customer-managed-policies-example-stop-build) ++ [Allow a user to attempt to delete builds](#customer-managed-policies-example-delete-builds) ++ [Allow a user to get information about Docker images that are managed by CodeBuild](#customer-managed-policies-example-list-curated-environment-images) ++ [Allow CodeBuild access to AWS services required to create a VPC network interface](#customer-managed-policies-example-create-vpc-network-interface) ++ [Use a deny statement to prevent AWS CodeBuild from disconnecting from source providers](#customer-managed-policies-example-deny-disconnect) + +### Allow a user to get information about build projects The following example policy statement allows a user to get information about build projects in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: @@ -239,7 +259,7 @@ The following example policy statement allows a user to get information about bu } ``` -### Allow a User to Get Information About Report Groups +### Allow a user to get information about report groups The following example policy statement allows a user to get information about report groups in the `us-east-2` Region for account `123456789012`: @@ -256,7 +276,7 @@ The following example policy statement allows a user to get information about re } ``` -### Allow a User to Get Information About Reports +### Allow a user to get information about reports The following example policy statement allows a user to get information about reports in the `us-east-2` Region for account `123456789012`: @@ -273,7 +293,7 @@ The following example policy statement allows a user to get information about re } ``` -### Allow a User to Create Build Projects +### Allow a user to create build projects The following example policy statement allows a user to create build projects with any name but only in the `us-east-2` Region for account `123456789012` and only using the specified CodeBuild service role: @@ -295,9 +315,9 @@ The following example policy statement allows a user to create build projects wi } ``` -### Allow a User to Create a Report Group +### Allow a user to create a report group -The following example policy statement allows a user to create a report group in the `us-east-2`Region for account `123456789012`: +The following example policy statement allows a user to create a report group in the `us-east-2` Region for account `123456789012`: ``` { @@ -312,7 +332,7 @@ The following example policy statement allows a user to create a report group in } ``` -### Allow a User to Delete a Report Group +### Allow a user to delete a report group The following example policy statement allows a user to delete a report group in the `us-east-2` Region for account `123456789012`: @@ -329,7 +349,7 @@ The following example policy statement allows a user to delete a report group in } ``` -### Allow a User to Delete a Report +### Allow a user to delete a report The following example policy statement allows a user to delete a report in the `us-east-2` Region for account `123456789012`: @@ -346,7 +366,7 @@ The following example policy statement allows a user to delete a report in the ` } ``` -### Allow a User to Delete Build Projects +### Allow a user to delete build projects The following example policy statement allows a user to delete build projects in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: @@ -363,7 +383,7 @@ The following example policy statement allows a user to delete build projects in } ``` -### Allow a User to Get a List of Build Project Names +### Allow a user to get a list of build project names The following example policy statement allows a user to get a list of build project names for the same account: @@ -380,7 +400,7 @@ The following example policy statement allows a user to get a list of build proj } ``` -### Allow a User to Change Information About Build Projects +### Allow a user to change information about build projects The following example policy statement allows a user to change information about build projects with any name but only in the `us-east-2` Region for account `123456789012` and only using the specified AWS CodeBuild service role: @@ -402,7 +422,7 @@ The following example policy statement allows a user to change information about } ``` -### Allow a User to Change a Report Group +### Allow a user to change a report group The following example policy statement allows a user to change a report group in the `us-east-2` Region for account `123456789012`: @@ -419,7 +439,7 @@ The following example policy statement allows a user to change a report group in } ``` -### Allow a User to Get Information About Builds +### Allow a user to get information about builds The following example policy statement allows a user to get information about builds in the `us-east-2` Region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: @@ -439,7 +459,7 @@ The following example policy statement allows a user to get information about bu } ``` -### Allow a User to Get a List of Build IDs for a Build Project +### Allow a user to get a list of build IDs for a build project The following example policy statement allows a user to get a list of build IDs in the `us-east-2` Region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: @@ -459,7 +479,7 @@ The following example policy statement allows a user to get a list of build IDs } ``` -### Allow a User to Get a List of Build IDs +### Allow a user to get a list of build IDs The following example policy statement allows a user to get a list of all build IDs for the same account: @@ -476,7 +496,7 @@ The following example policy statement allows a user to get a list of all build } ``` -### Allow a User to Get a List of Report Groups +### Allow a user to get a list of report groups The following example policy statement allows a user to get a list of report groups in the `us-east-2` Region for account `123456789012`: @@ -493,7 +513,7 @@ The following example policy statement allows a user to get a list of report gro } ``` -### Allow a User to Get a List of Reports +### Allow a user to get a list of reports The following example policy statement allows a user to get a list of reports in the `us-east-2` Region for account `123456789012`: @@ -510,7 +530,7 @@ The following example policy statement allows a user to get a list of reports in } ``` -### Allow a User to Get a List of Reports for a Report Group +### Allow a user to get a list of reports for a report group The following example policy statement allows a user to get a list of reports for a report group in the `us-east-2` Region for account `123456789012`: @@ -527,7 +547,7 @@ The following example policy statement allows a user to get a list of reports fo } ``` -### Allow a User to Get a List of Test Cases for a Report +### Allow a user to get a list of test cases for a report The following example policy statement allows a user to get a list of test cases for a report in the `us-east-2` Region for account `123456789012`: @@ -544,7 +564,7 @@ The following example policy statement allows a user to get a list of test cases } ``` -### Allow a User to Start Running Builds +### Allow a user to start running builds The following example policy statement allows a user to run builds in the `us-east-2` Region for account `123456789012` for a build project that starts with the name `my`: @@ -561,7 +581,7 @@ The following example policy statement allows a user to run builds in the `us-ea } ``` -### Allow a User to Attempt to Stop Builds +### Allow a user to attempt to stop builds The following example policy statement allows a user to attempt to stop running builds only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: @@ -578,9 +598,9 @@ The following example policy statement allows a user to attempt to stop running } ``` -### Allow a User to Attempt to Delete Builds +### Allow a user to attempt to delete builds -The following example policy statement allows a user to attempt to delete builds only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: +The following example policy statement allows a user to attempt to delete builds only in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: ``` { @@ -595,7 +615,7 @@ The following example policy statement allows a user to attempt to delete builds } ``` -### Allow a User to Get Information About Docker Images That Are Managed by CodeBuild +### Allow a user to get information about Docker images that are managed by CodeBuild The following example policy statement allows a user to get information about all Docker images that are managed by CodeBuild: @@ -612,9 +632,9 @@ The following example policy statement allows a user to get information about al } ``` -### Allow CodeBuild Access to AWS Services Required to Create a VPC Network Interface +### Allow CodeBuild access to AWS services required to create a VPC network interface -The following example policy statement grants AWS CodeBuild permission to create a network interface in an Amazon VPC with two subnets: +The following example policy statement grants AWS CodeBuild permission to create a network interface in a VPC with two subnets: ``` { @@ -653,9 +673,9 @@ The following example policy statement grants AWS CodeBuild permission to create } ``` -### Use a Deny Statement to Prevent CodeBuild from Disconnecting from Source Providers +### Use a deny statement to prevent AWS CodeBuild from disconnecting from source providers - The following example policy statement uses a deny statement to prevent AWS CodeBuild from disconnecting from source providers\. It uses `codebuild:DeleteOAuthToken`, which is the inverse of `codebuild:PersistOAuthToken` and `codebuild:ImportSourceCredentials`, to connect with source providers\. For more information, see [Permissions Required for the CodeBuild Console to Connect to Source Providers](#console-policies)\. + The following example policy statement uses a deny statement to prevent AWS CodeBuild from disconnecting from source providers\. It uses `codebuild:DeleteOAuthToken`, which is the inverse of `codebuild:PersistOAuthToken` and `codebuild:ImportSourceCredentials`, to connect with source providers\. For more information, see [Permissions required for the AWS CodeBuild console to connect to source providers](#console-policies)\. ``` { diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 2dbe4e5..14d7669 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -1,6 +1,6 @@ -# CodeBuild Permissions Reference +# AWS CodeBuild permissions reference -You can use the following table as a reference when you are setting up [Access Control](auth-and-access-control.md#access-control) and writing permissions policies that you can attach to an IAM identity \(identity\-based policies\)\. +You can use the following table as a reference when you are setting up [Access control](auth-and-access-control.md#access-control) and writing permissions policies that you can attach to an IAM identity \(identity\-based policies\)\. You can use AWS\-wide condition keys in your AWS CodeBuild policies to express conditions\. For a list, see [Available Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#AvailableKeys) in the *IAM User Guide*\. @@ -14,7 +14,7 @@ You specify an ARN, with or without a wildcard character \(\*\), as the resource arn:aws:codebuild:us-east-2:123456789012:project/my* ``` -If you see an expand arrow \(**↗**\) in the upper\-right corner of the table, you can open the table in a new window\. To close the window, choose the close button \(**X**\) in the lower\-right corner\. +Use the scroll bars to see the rest of the table\. **CodeBuild API Operations and Required Permissions for Actions** diff --git a/doc_source/auth-and-access-control-using-tags.md b/doc_source/auth-and-access-control-using-tags.md index 427179c..7714585 100644 --- a/doc_source/auth-and-access-control-using-tags.md +++ b/doc_source/auth-and-access-control-using-tags.md @@ -1,9 +1,9 @@ -# Using Tags to Control Access to CodeBuild Resources +# Using tags to control access to AWS CodeBuild resources -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 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)\. +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** - 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\. +**Example 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,8 +25,8 @@ 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** -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 +**Example 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 ``` { diff --git a/doc_source/auth-and-access-control.md b/doc_source/auth-and-access-control.md index c34a0f8..f3a054a 100644 --- a/doc_source/auth-and-access-control.md +++ b/doc_source/auth-and-access-control.md @@ -1,30 +1,30 @@ -# Identity and Access Management in CodeBuild +# Identity and access management in AWS CodeBuild -Access to AWS CodeBuild requires credentials\. Those credentials must have permissions to access AWS resources, such as storing and retrieving build artifacts in Amazon S3 buckets and viewing Amazon CloudWatch Logs for builds\. The following sections describe how you can use [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) \(IAM\) and CodeBuild to help secure access to your resources: +Access to AWS CodeBuild requires credentials\. Those credentials must have permissions to access AWS resources, such as storing and retrieving build artifacts in S3 buckets and viewing Amazon CloudWatch Logs for builds\. The following sections describe how you can use [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) \(IAM\) and CodeBuild to help secure access to your resources: + [Authentication](#authentication) -+ [Access Control](#access-control) ++ [Access control](#access-control) ## Authentication You can access AWS as any of the following types of identities: + **AWS account root user** – When you sign up for AWS, you provide an email address and password that is associated with your AWS account\. These are your *root credentials* and they provide complete access to all of your AWS resources\. **Important** -For security reasons, we recommend that you use the root credentials only to create an administrator user, which is an IAM user with full permissions to your AWS account\. Then, you can use this administrator user to create other IAM users and roles with limited permissions\. For more information, see [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users) and [Creating an Admin User and Group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide Guide*\. +For security reasons, we recommend that you use the root credentials only to create an administrator user, which is an IAM user with full permissions to your AWS account\. Then, you can use this administrator user to create other IAM users and roles with limited permissions\. For more information, see [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users) and [Creating an Admin User and Group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. + **IAM user** – An [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) is simply an identity in your AWS account that has custom permissions \(for example, permission to create build projects in CodeBuild\)\. You can use an IAM user name and password to sign in to secure AWS webpages like the [AWS Management Console](https://console.aws.amazon.com/), [AWS Discussion Forums](https://forums.aws.amazon.com/), or the [AWS Support Center](https://console.aws.amazon.com/support/home#/)\. In addition to a user name and password, you can also generate [access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for each user\. You can use these keys when you access AWS services programmatically, either through [one of the AWS SDKs](https://aws.amazon.com/tools/) or by using the [AWS Command Line Interface \(AWS CLI\)](https://aws.amazon.com/cli/)\. The AWS SDKs and AWS CLI tools use the access keys to cryptographically sign your request\. If you don’t use the AWS tools, you must sign the request yourself\. CodeBuild supports Signature Version 4, a protocol for authenticating inbound API requests\. For more information about authenticating requests, see the [Signature Version 4 Signing Process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference*\. + **IAM role** – An [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is similar to an IAM user, but it is not associated with a specific person\. An IAM role enables you to obtain temporary access keys that can be used to access AWS services and resources\. IAM roles with temporary credentials are useful in the following situations: - + **Federated user access** – Instead of creating an IAM user, you can use preexisting user identities from AWS Directory Service, your enterprise user directory, or a web identity provider\. These are known as federated users\. AWS assigns a role to a federated user when access is requested through an [identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)\. For more information about federated users, see [Federated Users and Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles) in the *IAM User Guide Guide*\. - + **Cross\-account access** – You can use an IAM role in your account to grant another AWS account permissions to access your account’s resources\. For an example, see [Tutorial: Delegate Access Across AWS Accounts Using IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html) in the *IAM User Guide Guide*\. - + **AWS service access** – You can use an IAM role in your account to grant permissions to an AWS service to access your account’s resources\. For example, you can create a role that allows Amazon Redshift to access an Amazon S3 bucket on your behalf and then load data stored in the bucket into an Amazon Redshift cluster\. For more information, see [Creating a Role to Delegate Permissions to an AWS Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide Guide*\. - + **Applications running on Amazon EC2** – Instead of storing access keys in the Amazon EC2 instance for use by applications running on the instance and making AWS API requests, you can use an IAM role to manage temporary credentials for these applications\. To assign an AWS role to an Amazon EC2 instance and make it available to all of its applications, you can create an instance profile that is attached to the instance\. An instance profile contains the role and enables programs running on the Amazon EC2 instance to get temporary credentials\. For more information, see [Using Roles for Applications on Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) in the *IAM User Guide Guide*\. + + **Federated user access** – Instead of creating an IAM user, you can use preexisting user identities from AWS Directory Service, your enterprise user directory, or a web identity provider\. These are known as federated users\. AWS assigns a role to a federated user when access is requested through an [identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)\. For more information about federated users, see [Federated Users and Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles) in the *IAM User Guide*\. + + **Cross\-account access** – You can use an IAM role in your account to grant another AWS account permissions to access your account’s resources\. For an example, see [Tutorial: Delegate Access Across AWS Accounts Using IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html) in the *IAM User Guide*\. + + **AWS service access** – You can use an IAM role in your account to grant permissions to an AWS service to access your account’s resources\. For example, you can create a role that allows Amazon Redshift to access an S3 bucket on your behalf and then load data stored in the bucket into an Amazon Redshift cluster\. For more information, see [Creating a Role to Delegate Permissions to an AWS Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*\. + + **Applications running on Amazon EC2** – Instead of storing access keys in the Amazon EC2 instance for use by applications running on the instance and making AWS API requests, you can use an IAM role to manage temporary credentials for these applications\. To assign an AWS role to an Amazon EC2 instance and make it available to all of its applications, you can create an instance profile that is attached to the instance\. An instance profile contains the role and enables programs running on the Amazon EC2 instance to get temporary credentials\. For more information, see [Using Roles for Applications on Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) in the *IAM User Guide*\. -## Access Control +## Access control You can have valid credentials to authenticate your requests, but unless you have permissions, you cannot create or access AWS CodeBuild resources\. For example, you must have permissions to create, view, or delete build projects and to start, stop, or view builds\. The following sections describe how to manage permissions for CodeBuild\. We recommend that you read the overview first\. -+ [Overview of Managing Access Permissions to Your CodeBuild Resources](auth-and-access-control-iam-access-control-identity-based.md) -+ [Using Identity\-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) -+ [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md) -+ [Viewing Resources in the Console](console-resources.md) \ No newline at end of file ++ [Overview of managing access permissions to your AWS CodeBuild resources](auth-and-access-control-iam-access-control-identity-based.md) ++ [Using identity\-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) ++ [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md) ++ [Viewing resources in the console](console-resources.md) \ No newline at end of file diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 25d2b04..b069dc8 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -1,4 +1,4 @@ -# Build Caching in CodeBuild +# 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\. @@ -6,17 +6,17 @@ 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\. **Topics** -+ [Amazon S3 Caching](#caching-s3) -+ [Local Caching](#caching-local) ++ [Amazon S3 caching](#caching-s3) ++ [Local caching](#caching-local) -## Amazon S3 Caching +## 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\. + 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\. -## Local Caching +## 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 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, or Bitbucket\), the option is ignored\. ++ 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\. This is not the best option if your builds are infrequent\. If you choose this option and your project does not use a Git repository \(GitHub, GitHub Enterprise, 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\. @@ -26,19 +26,19 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + 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 are overriden if a source item has 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)\. + + Cached directories are linked to your build before it downloads its project sources\. Cached items are overriden if a source item has 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)\. **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)\. +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)\. **Topics** -+ [Specify Local Caching \(CLI\)](#caching-local-cli) -+ [Specify Local Caching \(Console\)](#caching-local-console) -+ [Specify Local Caching \(AWS CloudFormation\)](#caching-local-cfn) ++ [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\. -### Specify Local Caching \(CLI\) +### 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: @@ -57,17 +57,17 @@ The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_G --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE] ``` -For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. +For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. -### Specify Local Caching \(Console\) +### Specify local caching \(console\) You specify a cache in the **Artifacts** section of the console\. For **Cache type**, choose **Amazon S3** or **Local**\. If you choose **Local**, choose one or more of the three local cache options\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.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 Build Project \(Console\)](create-project.md#create-project-console)\. +For more information, see [Create a build project \(console\)](create-project.md#create-project-console)\. -### Specify Local Caching \(AWS CloudFormation\) +### 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`\. @@ -108,4 +108,4 @@ CodeBuildProject: **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\. -For more information, see [Create a Build Project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. \ No newline at end of file +For more information, see [Create a build project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. \ No newline at end of file diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index f31c10d..3954681 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -1,4 +1,4 @@ -# Docker Images Provided by CodeBuild +# Docker images provided by CodeBuild AWS CodeBuild manages the following Docker images that are available in the CodeBuild and AWS CodePipeline consoles\. @@ -17,9 +17,9 @@ AWS CodeBuild manages the following Docker images that are available in the Code 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.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)\. + 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 its major version, its major version with the latest minor version, or the latest major and minor version\. The following table lists the available runtimes and how to specify them\. + 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** @@ -44,13 +44,13 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the **Note** The base image of the Windows Server Core 2016 platform is 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)\. +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)\. 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.md#create-project-console) 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.md#create-project-console) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. + 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)\. \ No newline at end of file diff --git a/doc_source/build-env-ref-background-tasks.md b/doc_source/build-env-ref-background-tasks.md index 4eae49b..b88b3a1 100644 --- a/doc_source/build-env-ref-background-tasks.md +++ b/doc_source/build-env-ref-background-tasks.md @@ -1,4 +1,4 @@ -# Background Tasks in Build Environments +# Background tasks in build environments You can run background tasks in build environments\. To do this, in your buildspec, use the `nohup` command to run a command as a task in the background, even if the build process exits the shell\. Use the disown command to forcibly stop a running background task\. diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index f4bc78c..8fb0fa0 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.md @@ -1,11 +1,11 @@ -# Shells and Commands in Build Environments +# Shells and commands in build environments 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.md#create-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.md#change-project-console)\. -+ 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)\. ++ 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.md#create-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.md#change-project-console)\. ++ 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)\. You can specify any Shell command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: + Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell\. For example, you could include a file named `my-script.sh` in your source code that contains commands such as `cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;`\. Then, in your buildspec file, specify the command `./my-script.sh`\. @@ -13,4 +13,4 @@ You can specify any Shell command\. In buildspec version 0\.1, CodeBuild runs ea 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 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 2016 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 7dd8f23..b1bff7f 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -1,4 +1,4 @@ -# Build Environment Compute Types +# Build environment compute types AWS CodeBuild provides build environments with the following available memory, vCPUs, and disk space: @@ -35,11 +35,11 @@ For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncomp 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.md#create-project-console) 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.md#create-project-cli) 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)\. ++ 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.md#create-project-console) 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.md#create-project-cli) 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 CodeBuild](sample-efs.md)\. If you want to manipulate container disk space during a build, then the build must run in privileged mode\. +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** 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\. \ No newline at end of file diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 75ccafb..afca63e 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -1,4 +1,4 @@ -# Environment Variables in Build Environments +# 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\. @@ -24,28 +24,28 @@ AWS CodeBuild provides several environment variables that you can use in your bu For a GitHub or GitHub Enterprise 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)\. +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, or Bitbucket\. The value's format depends on what type of event triggered the build\. ++ `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, 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 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) -+ [Buildspec Reference](build-spec-ref.md) ++ [Use AWS CodePipeline with AWS 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) ++ [Buildspec reference](build-spec-ref.md) To list all of the available environment variables in a build environment, you can run the `printenv` command \(for Linux\-based build environment\) or `"Get-ChildItem Env:"` \(for Windows\-based build environments\) during a build\. Except for those previously listed, environment variables that start with `CODEBUILD_` are for CodeBuild internal use\. They should not be used in your build commands\. **Important** We strongly discourage the use of environment variables to store sensitive values, especially AWS access key IDs and secret access keys\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. -We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your buildspec\. To store sensitive values, 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)\. \ No newline at end of file +We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your buildspec\. To store sensitive values, 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)\. \ No newline at end of file diff --git a/doc_source/build-env-ref.md b/doc_source/build-env-ref.md index 3e3fa2e..6e63cbe 100644 --- a/doc_source/build-env-ref.md +++ b/doc_source/build-env-ref.md @@ -1,19 +1,19 @@ -# Build Environment Reference for CodeBuild +# Build environment reference for AWS CodeBuild -When you call AWS CodeBuild to run a build, you must provide information about the build environment\. A *build environment* represents a combination of operating system, programming language runtime, and tools that CodeBuild uses to run a build\. For information about how a build environment works, see [How CodeBuild Works](concepts.md#concepts-how-it-works)\. +When you call AWS CodeBuild to run a build, you must provide information about the build environment\. A *build environment* represents a combination of operating system, programming language runtime, and tools that CodeBuild uses to run a build\. For information about how a build environment works, see [How CodeBuild works](concepts.md#concepts-how-it-works)\. A build environment contains a Docker image\. For information, see [the Docker glossary](https://docs.docker.com/glossary/?term=image) on the Docker Docs website\. When you provide information to CodeBuild about the build environment, you specify the identifier of a Docker image in a supported repository type\. These include the CodeBuild Docker image repository, publicly available images in Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\) repositories that your AWS account has permissions to access\. -+ We recommend that you use Docker images stored in the CodeBuild Docker image repository, because they are optimized for use with the service\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. ++ We recommend that you use Docker images stored in the CodeBuild Docker image repository, because they are optimized for use with the service\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. + To get the identifier of a publicly available Docker image stored in Docker Hub, see [Searching for Images](https://docs.docker.com/docker-hub/repos/#searching-for-images) on the Docker Docs website\. -+ To learn how to work with Docker images stored in Amazon ECR repositories in your AWS account, see [Amazon ECR Sample](sample-ecr.md)\. ++ To learn how to work with Docker images stored in Amazon ECR repositories in your AWS account, see [Amazon ECR sample](sample-ecr.md)\. -In addition to a Docker image identifier, you also specify a set of computing resources that the build environment uses\. For more information, see [Build Environment Compute Types](build-env-ref-compute-types.md)\. +In addition to a Docker image identifier, you also specify a set of computing resources that the build environment uses\. For more information, see [Build environment compute types](build-env-ref-compute-types.md)\. **Topics** -+ [Docker Images Provided by CodeBuild](build-env-ref-available.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) \ No newline at end of file ++ [Docker images provided by CodeBuild](build-env-ref-available.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) \ No newline at end of file diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 31dc9ec..3fb9db7 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -1,14 +1,14 @@ -# Build Specification Reference for CodeBuild +# Build specification reference for CodeBuild -This topic provides important reference information about build specification \(buildspec\) files\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project\. For information about how a build spec works, see [How CodeBuild Works](concepts.md#concepts-how-it-works)\. +This topic provides important reference information about build specification \(buildspec\) files\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project\. For information about how a build spec works, see [How CodeBuild works](concepts.md#concepts-how-it-works)\. **Topics** -+ [Buildspec File Name and Storage Location](#build-spec-ref-name-storage) -+ [Buildspec Syntax](#build-spec-ref-syntax) -+ [Buildspec Example](#build-spec-ref-example) -+ [Buildspec Versions](#build-spec-ref-versions) ++ [Buildspec file name and storage location](#build-spec-ref-name-storage) ++ [Buildspec syntax](#build-spec-ref-syntax) ++ [Buildspec example](#build-spec-ref-example) ++ [Buildspec versions](#build-spec-ref-versions) -## Buildspec File Name and Storage Location +## Buildspec file name and storage location If you include a buildspec as part of the source code, by default, the buildspec file must be named `buildspec.yml` and placed in the root of your source directory\. @@ -19,11 +19,11 @@ You can override the default buildspec file name and location\. For example, you You can specify only one buildspec for a build project, regardless of the buildspec file's name\. To override the default buildspec file name, location, or both, do one of the following: -+ Run the AWS CLI `create-project` or `update-project` command, setting the `buildspec` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `create project` operation in the AWS SDKs\. For more information, see [Create a Build Project](create-project.md) or [Change a Build Project's Settings](change-project.md)\. -+ Run the AWS CLI `start-build` command, setting the `buildspecOverride` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `start build` operation in the AWS SDKs\. For more information, see [Run a Build](run-build.md)\. ++ Run the AWS CLI `create-project` or `update-project` command, setting the `buildspec` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `create project` operation in the AWS SDKs\. For more information, see [Create a build project](create-project.md) or [Change a build project's settings](change-project.md)\. ++ Run the AWS CLI `start-build` command, setting the `buildspecOverride` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `start build` operation in the AWS SDKs\. For more information, see [Run a build](run-build.md)\. + In an AWS CloudFormation template, set the `BuildSpec` property of `Source` in a resource of type `AWS::CodeBuild::Project` to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. For more information, see the BuildSpec property in [AWS CodeBuild Project Source](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html) in the *AWS CloudFormation User Guide*\. -## Buildspec Syntax +## Buildspec syntax Buildspec files must be expressed in [YAML](http://yaml.org/) format\. @@ -132,26 +132,31 @@ cache: The buildspec contains the following: + `version`: Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. **Note** -Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec Versions](#build-spec-ref-versions)\. +Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec versions](#build-spec-ref-versions)\. + `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\. + `env`: Optional sequence\. Represents information for one or more custom environment variables\. +**Note** + 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 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)\. + `variables`: Required if `env` is specified, and you want to define custom environment variables in plain text\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable in plain text\. *key* is the name of the custom environment variable, and *value* is that variable's value\. **Important** We strongly discourage the storing of sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. For sensitive values, we recommend that you use `parameter-store` or `secrets-manager` mapping instead, as described later in this section\. 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 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 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. +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 buildspec declaration takes lowest precedence\. + `parameter-store`: Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. **Important** -To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add the `ssm:GetParameters` action to your CodeBuild service role\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. +To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add the `ssm:GetParameters` action to your CodeBuild service role\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Store 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 retrieve 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 retrieve 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 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 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in CodeBuild ](change-project.md)\. +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 buildspec declaration takes lowest precedence\. + `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: @@ -173,17 +178,17 @@ The value in the buildspec declaration takes lowest precedence\. + `git-credential-helper`: Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. **Note** `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. -+ `proxy`: Optional sequence\. Used to represent settings if you run your build in an explicit proxy server\. For more information, see [ Run CodeBuild in an Explicit Proxy Server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. ++ `proxy`: Optional sequence\. Used to represent settings if you run your build in an explicit proxy server\. For more information, see [ Run CodeBuild in an explicit proxy server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. + `upload-artifacts`: Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default is `no`\. + `logs`: Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch logs\. The default is `no`\. + `phases`: Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. **Note** -In buildspec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend the approaches in [Shells and Commands in Build Environments](build-env-ref-cmd.md)\. +In buildspec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend the approaches in [Shells and commands in build environments](build-env-ref-cmd.md)\. + `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\. The allowed build phase names are: + `install`: Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. - + `runtime-versions`: Optional sequence\. A runtime version is supported with the Ubuntu standard image 2\.0 or later and the Amazon Linux 2 standard image 1\.0 or later\. If specified, at least one runtime must be included in this section\. Specify a runtime using a specific version, a major version followed by `.x` to specify that CodeBuild uses that major version with its latest minor version, or `latest` to use the most recent major and minor version \(for example, `java: openjdk11`, `ruby: 2.6`, `nodejs: 12.x`, or `java: latest`\)\. You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. + + `runtime-versions`: Optional sequence\. A runtime version is supported with the Ubuntu standard image 2\.0 or later and the Amazon Linux 2 standard image 1\.0 or later\. If specified, at least one runtime must be included in this section\. Specify a runtime using a specific version, a major version followed by `.x` to specify that CodeBuild uses that major version with its latest minor version, or `latest` to use the most recent major and minor version \(for example, `java: openjdk11`, `ruby: 2.6`, `nodejs: 12.x`, or `java: latest`\)\. You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. ``` phases: @@ -199,7 +204,7 @@ In buildspec version 0\.1, CodeBuild runs each command in a separate instance of **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) **Note** - 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\." + 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`\." + `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\. + `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\. + `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\. @@ -208,9 +213,9 @@ In buildspec version 0\.1, CodeBuild runs each command in a separate instance of + `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\. + `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\. **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)\. +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)\. + `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\. -+ `report-name-or-arn`: Optional sequence\. Represents information about where you want the files with your test results\. A project can have a maximum of five report groups\. Specify a name for a new report group or the ARN of an existing report group\. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format project\-name\-report\-group\-name\-in\-buildspec\. For more information, see [Report Group Naming](test-report-group-naming.md)\. ++ `report-name-or-arn`: Optional sequence\. Represents information about where you want the files with your test results\. A project can have a maximum of five report groups\. Specify a name for a new report group or the ARN of an existing report group\. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format project\-name\-report\-group\-name\-in\-buildspec\. For more information, see [Report group naming](test-report-group-naming.md)\. + `files`: Required sequence\. Represents the locations that contain the raw data of test results generated by the report\. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find test files, relative to the original build location or, if set, the `base-directory`\. Locations can include the following: + A single file \(for example, `my-test-report-file.json`\)\. + A single file in a subdirectory \(for example, `my-subdirectory/my-test-report-file.json` or `my-parent-subdirectory/my-subdirectory/my-test-report-file.json`\)\. @@ -218,7 +223,7 @@ Commands in some build phases might not be run if commands in earlier build phas + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + `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\. - + `discard-paths`: Optional mapping\. Represents whether paths to test result files updloaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TestResult.xml`\. + + `discard-paths`: Optional mapping\. Represents whether paths to test result files uploaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TestResult.xml`\. + `file-format`: Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: + `JunitXml` + `CucumberJson` @@ -235,7 +240,7 @@ Commands in some build phases might not be run if commands in earlier build phas When you specify build output artifact locations, CodeBuild can locate the original build location in the build environment\. You do not have to prepend your build artifact output locations with the path to the original build location or specify `./` or similar\. If you want to know the path to this location, you can run a command such as `echo $CODEBUILD_SRC_DIR` during a build\. The location for each build environment might be slightly different\. + `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.md#create-project-console)\. + + 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.md#create-project-console)\. 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/)\. @@ -253,7 +258,7 @@ Commands in some build phases might not be run if commands in earlier build phas 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)\. + 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 @@ -387,7 +392,7 @@ If you use the AWS CLI, or the AWS SDKs to declare a buildspec when you create o If you use the CodeBuild or AWS CodePipeline consoles instead of a buildspec\.yml file, you can insert commands for the `build` phase only\. Instead of using the preceding syntax, you list, in a single line, all of the commands that you want to run during the build phase\. For multiple commands, separate each command by `&&` \(for example, `mvn test && mvn package`\)\. You can use the CodeBuild or CodePipeline consoles instead of a buildspec\.yml file to specify the locations of the build output artifacts in the build environment\. Instead of using the preceding syntax, you list, in a single line, all of the locations\. For multiple locations, separate each location with a comma \(for example, `buildspec.yml, target/my-app.jar`\)\. -## Buildspec Example +## Buildspec example | | @@ -481,7 +486,7 @@ In these examples: + `arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1` specifies the ARN of a report group\. Test results generated by the test framework are in the `target/tests/reports` directory\. The file format is `JunitXml` and the path is not removed from the files that contain test results\. + `reportGroupCucumberJson` specifies a new report group\. If the name of the project is `my-project`, a report group with the name `my-project-reportGroupCucumberJson` is created when a build is run\.\. Test results generated by the test framework are in `cucumber/target/cucumber-tests.xml`\. The test file format is `CucumberJson` and the path is removed from the files that contain test results\. -## Buildspec Versions +## Buildspec versions The following table lists the buildspec versions and the changes between versions\. diff --git a/doc_source/builds-projects-and-builds.md b/doc_source/builds-projects-and-builds.md index 8079956..c74b519 100644 --- a/doc_source/builds-projects-and-builds.md +++ b/doc_source/builds-projects-and-builds.md @@ -1,7 +1,7 @@ -# Working with Build Projects and Builds in CodeBuild +# 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) -+ [Working with Builds in CodeBuild](builds-working.md) \ No newline at end of file ++ [Working with build projects](working-with-build-projects.md) ++ [Working with builds in AWS CodeBuild](builds-working.md) \ No newline at end of file diff --git a/doc_source/builds-working.md b/doc_source/builds-working.md index 0d0ac2d..e3c4a1a 100644 --- a/doc_source/builds-working.md +++ b/doc_source/builds-working.md @@ -1,11 +1,11 @@ -# Working with Builds in CodeBuild +# Working with builds in AWS CodeBuild 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 [Build Limits](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 [Build Limits](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 CodeBuild](run-build.md)\. ++ 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\. **Note** @@ -14,9 +14,9 @@ You can access the history of a build for one year\. You can perform these tasks when working with builds: **Topics** -+ [Run a Build in CodeBuild](run-build.md) -+ [View Build Details in CodeBuild](view-build-details.md) -+ [View a List of Build IDs in CodeBuild](view-build-list.md) -+ [View a List of Build IDs for a Build Project in CodeBuild](view-builds-for-project.md) -+ [Stop a Build in CodeBuild](stop-build.md) -+ [Delete Builds in CodeBuild](delete-builds.md) \ No newline at end of file ++ [Run a build in AWS CodeBuild](run-build.md) ++ [View build details in AWS CodeBuild](view-build-details.md) ++ [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) ++ [Delete builds in AWS CodeBuild](delete-builds.md) \ No newline at end of file diff --git a/doc_source/change-project.md b/doc_source/change-project.md index 9183483..d961b16 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -1,15 +1,15 @@ -# Change a Build Project's Settings in CodeBuild +# Change a build project's settings in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to change a build project's settings\. -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)\. +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\)](#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\) +## 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)\. @@ -23,7 +23,7 @@ If you add test reporting to a build project, make sure your IAM role has the pe Choose **Update configuration**\. - For more information about settings referred to in this procedure, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. + For more information about settings referred to in this procedure, see [Create a build project \(console\)](create-project.md#create-project-console)\. 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** @@ -31,7 +31,7 @@ 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)\. + 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**\)\. @@ -52,7 +52,7 @@ When you use the console to create or update a build project, you can create a C 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 CodeBuild](sample-efs.md)\. +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**\. @@ -73,7 +73,7 @@ Do not set any environment variable with a name that begins with `CODEBUILD_`\. 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 build spec declaration takes lowest 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** @@ -98,10 +98,10 @@ If you choose **New service role**, the service role includes permission to decr **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: +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 Amazon S3 bucket where the cache is stored\. + + 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**\. @@ -123,9 +123,9 @@ Do not append a forward slash \(/\) to the end of **Path prefix**\. 1. Choose **Update artifacts**\. -## Change a Build Project's Settings \(AWS CLI\) +## 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)\. +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: @@ -133,7 +133,7 @@ For information about using the AWS CLI with AWS CodeBuild, see the [Command Lin 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.md#create-project-cli), and save your results\. + 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.md#create-project-cli), 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\. @@ -143,8 +143,8 @@ In the JSON\-formatted data, you must provide the name of the build project\. Al aws codebuild update-project --cli-input-json file://update-project.json ``` -1. If successful, data similar to that as described in [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli) appears in the output\. +1. If successful, data similar to that described in [Create a build project \(AWS CLI\)](create-project.md#create-project-cli) appears in the output\. -## Change a Build Project's Settings \(AWS SDKs\) +## 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 +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/cloudformation-vpc-template.md b/doc_source/cloudformation-vpc-template.md index e78db74..0ec2130 100644 --- a/doc_source/cloudformation-vpc-template.md +++ b/doc_source/cloudformation-vpc-template.md @@ -1,8 +1,8 @@ -# AWS CloudFormation VPC Template +# AWS CloudFormation VPC template -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)\. +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 an Amazon VPC to use the AWS CodeBuild VPC feature\. +The following is an AWS CloudFormation YAML template for configuring a VPC to use AWS CodeBuild\. ``` Description: This template deploys a VPC, with a pair of public and private subnets spread diff --git a/doc_source/cloudtrail.md b/doc_source/cloudtrail.md index 52a0c4e..2866004 100644 --- a/doc_source/cloudtrail.md +++ b/doc_source/cloudtrail.md @@ -1,14 +1,14 @@ -# Logging CodeBuild API Calls with AWS CloudTrail +# Logging AWS CodeBuild API calls with AWS CloudTrail -AWS CodeBuild is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in CodeBuild\. CloudTrail captures all API calls for CodeBuild as events, including calls from the CodeBuild console and from code calls to the CodeBuild APIs\. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for CodeBuild\. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**\. Using the information collected by CloudTrail, you can determine the request that was made to CodeBuild, the IP address from which the request was made, who made the request, when it was made, and additional details\. +AWS CodeBuild is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in CodeBuild\. CloudTrail captures all API calls for CodeBuild as events, including calls from the CodeBuild console and from code calls to the CodeBuild APIs\. If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including events for CodeBuild\. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**\. Using the information collected by CloudTrail, you can determine the request that was made to CodeBuild, the IP address from which the request was made, who made the request, when it was made, and additional details\. To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)\. -## CodeBuild Information in CloudTrail +## AWS CodeBuild information in CloudTrail -CloudTrail is enabled on your AWS account when you create the account\. When activity occurs in CodeBuild, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**\. You can view, search, and download recent events in your AWS account\. For more information, see [Viewing Events with CloudTrail Event History](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)\. +CloudTrail is enabled on your AWS account when you create the account\. When activity occurs in CodeBuild, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**\. You can view, search, and download recent events in your AWS account\. For more information, see [Viewing Events with CloudTrail Event History](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*\. -For an ongoing record of events in your AWS account, including events for CodeBuild, create a trail\. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket\. By default, when you create a trail in the console, the trail applies to all regions\. The trail logs events from all regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify\. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs\. For more information, see: +For an ongoing record of events in your AWS account, including events for CodeBuild, create a trail\. A trail enables CloudTrail to deliver log files to an S3 bucket\. By default, when you create a trail in the console, the trail applies to all regions\. The trail logs events from all regions in the AWS partition and delivers the log files to the S3 bucket that you specify\. You can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs\. For more information, see: + [Overview for Creating a Trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [CloudTrail Supported Services and Integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) + [Configuring Amazon SNS Notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html) @@ -21,17 +21,17 @@ Every event or log entry contains information about who generated the request\. + Whether the request was made with temporary security credentials for a role or federated user\. + Whether the request was made by another AWS service\. -For more information, see the [CloudTrail userIdentity Element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)\. +For more information, see the [CloudTrail userIdentity Element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)in the *AWS CloudTrail User Guide*\. -## Understanding CodeBuild Log File Entries +## Understanding AWS CodeBuild log file entries -A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify\. CloudTrail log files contain one or more log entries\. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on\. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order\. +A trail is a configuration that enables delivery of events as log files to an S3 bucket that you specify\. CloudTrail log files contain one or more log entries\. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on\. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order\. **Note** 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*\. + 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\. 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)\. + Strings specified using AWS Secrets Manager\. For more information, see [Key management](security-key-management.md)\. The following example shows a CloudTrail log entry that demonstrates creating a build project in CodeBuild\. diff --git a/doc_source/cmd-ref.md b/doc_source/cmd-ref.md index 6445a0e..bc66842 100644 --- a/doc_source/cmd-ref.md +++ b/doc_source/cmd-ref.md @@ -1,12 +1,12 @@ -# Command Line Reference for CodeBuild +# Command line reference for AWS CodeBuild The AWS CLI provides commands for automating AWS CodeBuild\. Use the information in this topic as a supplement to the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/) and the [AWS CLI Reference for AWS CodeBuild](https://docs.aws.amazon.com/cli/latest/reference/codebuild/)\. -Not what you're looking for? If you want to use the AWS SDKs to call CodeBuild, see the [AWS SDKs and Tools Reference](sdk-ref.md)\. +Not what you're looking for? If you want to use the AWS SDKs to call CodeBuild, see the [AWS SDKs and tools reference](sdk-ref.md)\. -To use the information in this topic, you should have already installed the AWS CLI and configured it for use with CodeBuild, as described in [Install and Configure the AWS CLI](setting-up.md#setting-up-cli)\. +To use the information in this topic, you should have already installed the AWS CLI and configured it for use with CodeBuild, as described in [Install and configure the AWS CLI](setting-up.md#setting-up-cli)\. - To use the AWS CLI to specify the endpoint for CodeBuild, see [Specify the CodeBuild Endpoint \(AWS CLI\)](endpoint-specify.md#endpoint-specify-cli)\. + To use the AWS CLI to specify the endpoint for CodeBuild, see [Specify the AWS CodeBuild endpoint \(AWS CLI\)](endpoint-specify.md#endpoint-specify-cli)\. Run this command to get a list of CodeBuild commands\. @@ -21,15 +21,15 @@ aws codebuild command-name help ``` CodeBuild commands include: -+ `batch-delete-builds`: Deletes one or more builds in CodeBuild\. For more information, see [Delete Builds \(AWS CLI\)](delete-builds.md#delete-builds-cli)\. -+ `batch-get-builds`: Gets information about multiple builds in CodeBuild\. For more information, see [View Build Details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. -+ `batch-get-projects`: Gets information about one or more specified build projects\. For more information, see [View a Build Project's Details \(AWS CLI\)](view-project-details.md#view-project-details-cli)\. -+ `create-project`: Creates a build project\. For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. -+ `delete-project`: Deletes a build project\. For more information, see [Delete a Build Project \(AWS CLI\)](delete-project.md#delete-project-cli)\. -+ `list-builds`: Lists Amazon Resource Names \(ARNs\) for builds in CodeBuild\. For more information, see [View a List of Build IDs \(AWS CLI\)](view-build-list.md#view-build-list-cli)\. -+ `list-builds-for-project`: Gets a list of build IDs that are associated with a specified build project\. For more information, see [View a List of Build IDs for a Build Project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli)\. -+ `list-curated-environment-images`: Gets a list of Docker images managed by CodeBuild that you can use for your builds\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. -+ `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.md#run-build-cli)\. -+ `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 ++ `batch-delete-builds`: Deletes one or more builds in CodeBuild\. For more information, see [Delete builds \(AWS CLI\)](delete-builds.md#delete-builds-cli)\. ++ `batch-get-builds`: Gets information about multiple builds in CodeBuild\. For more information, see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. ++ `batch-get-projects`: Gets information about one or more specified build projects\. For more information, see [View a build project's details \(AWS CLI\)](view-project-details.md#view-project-details-cli)\. ++ `create-project`: Creates a build project\. For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. ++ `delete-project`: Deletes a build project\. For more information, see [Delete a build project \(AWS CLI\)](delete-project.md#delete-project-cli)\. ++ `list-builds`: Lists Amazon Resource Names \(ARNs\) for builds in CodeBuild\. For more information, see [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-build-list-cli)\. ++ `list-builds-for-project`: Gets a list of build IDs that are associated with a specified build project\. For more information, see [View a list of build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli)\. ++ `list-curated-environment-images`: Gets a list of Docker images managed by CodeBuild that you can use for your builds\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. ++ `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.md#run-build-cli)\. ++ `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 diff --git a/doc_source/codebuild-compliance-validation.md b/doc_source/codebuild-compliance-validation.md index 6e1bc88..020e52f 100644 --- a/doc_source/codebuild-compliance-validation.md +++ b/doc_source/codebuild-compliance-validation.md @@ -1,4 +1,4 @@ -# Compliance Validation for AWS CodeBuild +# Compliance validation for AWS CodeBuild Third\-party auditors assess the security and compliance of AWS CodeBuild as part of multiple AWS compliance programs\. These include SOC, PCI, FedRAMP, HIPAA, and others\. diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index 2c956b0..56802a5 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -2,7 +2,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identifies which methods and statements in your code are not tested\. Use the results to determine where to write tests to improve the quality of your code\. Codecov is available for three of the source repositories supported by CodeBuild: GitHub, GitHub Enterprise, and Bitbucket\. If your build project uses GitHub Enterprise, you must use Codecov Enterprise\. - When you run a build of a CodeBuild project that is integrated Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov Supported Languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. + When you run a build of a CodeBuild project that is integrated with Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov Supported Languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. ## Integrate Codecov into a build project @@ -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.md#change-project-console)\. 1. Create a text file named `my_script.sh` in your repository\. Enter the following into the file: @@ -57,7 +57,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif ``` - 1. Enter the following commands in your buildspec file\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + 1. Enter the following commands in your buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. ``` build: @@ -70,7 +70,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif ------ #### [ Python ] - Enter the following commands in your buildspec file\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + Enter the following commands in your buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. ``` build: @@ -83,7 +83,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif ------ -1. Run a build of your build project\. A link to Codecov reports generated for your project appears in your build logs\. Use the link to view the Codecov reports\. For more information, see [Run a Build in CodeBuild](run-build.md) and [Logging CodeBuild API Calls with AWS CloudTrail](cloudtrail.md)\. Codecov information in the build logs looks like the following: +1. Run a build of your build project\. A link to Codecov reports generated for your project appears in your build logs\. Use the link to view the Codecov reports\. For more information, see [Run a build in AWS CodeBuild](run-build.md) and [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md)\. Codecov information in the build logs looks like the following: ``` [Container] 2020/03/09 16:31:04 Running command bash my_script.sh diff --git a/doc_source/concepts.md b/doc_source/concepts.md index c48e1ba..90d30ab 100644 --- a/doc_source/concepts.md +++ b/doc_source/concepts.md @@ -1,35 +1,35 @@ -# AWS CodeBuild Concepts +# AWS CodeBuild concepts The following concepts are important for understanding how CodeBuild works\. **Topics** -+ [How CodeBuild Works](#concepts-how-it-works) -+ [Next Steps](#concepts-next-steps) ++ [How CodeBuild works](#concepts-how-it-works) ++ [Next steps](#concepts-next-steps) -## How CodeBuild Works +## 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) + + [Create a build project](create-project.md) + + [Build environment reference](build-env-ref.md) 1. CodeBuild uses the build project to create the build environment\. -1. CodeBuild downloads the source code into the build environment and then uses the build specification \(buildspec\), as defined in the build project or included directly in the source code\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. For more information, see the [Buildspec Reference](build-spec-ref.md)\. +1. CodeBuild downloads the source code into the build environment and then uses the build specification \(buildspec\), as defined in the build project or included directly in the source code\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. For more information, see the [Buildspec reference](build-spec-ref.md)\. -1. If there is any build output, the build environment uploads its output to an Amazon S3 bucket\. The build environment can also perform tasks that you specify in the buildspec \(for example, sending build notifications to an Amazon SNS topic\)\. For an example, see [Build Notifications Sample](sample-build-notifications.md)\. +1. If there is any build output, the build environment uploads its output to an S3 bucket\. The build environment can also perform tasks that you specify in the buildspec \(for example, sending build notifications to an Amazon SNS topic\)\. For an example, see [Build notifications sample](sample-build-notifications.md)\. 1. While the build is running, the build environment sends information to CodeBuild and Amazon CloudWatch Logs\. -1. While the build is running, you can use the CodeBuild console, AWS CLI, or AWS SDKs, to get summarized build information from CodeBuild and detailed build information from Amazon CloudWatch Logs\. If you use AWS CodePipeline to run builds, you can get limited build information from CodePipeline\. +1. While the build is running, you can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to get summarized build information from CodeBuild and detailed build information from Amazon CloudWatch Logs\. If you use AWS CodePipeline to run builds, you can get limited build information from CodePipeline\. -## Next Steps +## Next steps -Now that you know more about AWS CodeBuild, we recommend that you complete the following steps: +Now that you know more about AWS CodeBuild, we recommend these next steps: -1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting Started in the Console](getting-started.md)\. +1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting started using the console](getting-started.md)\. -1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a Build](planning.md)\. \ No newline at end of file +1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a build](planning.md)\. \ No newline at end of file diff --git a/doc_source/console-resources.md b/doc_source/console-resources.md index edde35a..89a8fb8 100644 --- a/doc_source/console-resources.md +++ b/doc_source/console-resources.md @@ -1,6 +1,6 @@ -# Viewing Resources in the Console +# Viewing resources in the console -The CodeBuild console requires the `ListRepositories` permission to display a list of repositories for your AWS account in the AWS Region where you are signed in\. The console also includes a **Go to resource** function to quickly perform a case insensitive search for resources\. This search is performed in your AWS account in the AWS Region where you are signed in\. The following resources are displayed across the following services: +The AWS CodeBuild console requires the `ListRepositories` permission to display a list of repositories for your AWS account in the AWS Region where you are signed in\. The console also includes a **Go to resource** function to quickly perform a case insensitive search for resources\. This search is performed in your AWS account in the AWS Region where you are signed in\. The following resources are displayed across the following services: + AWS CodeBuild: Build projects + AWS CodeCommit: Repositories + AWS CodeDeploy: Applications diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 8d0727a..c65763e 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -1,19 +1,19 @@ -# Create a Build Project in CodeBuild +# Create a build project in AWS CodeBuild -You can use the CodeBuild console, AWS CLI, or AWS SDKs to create a build project\. +You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to create a build project\. **Topics** + [Prerequisites](#create-project-prerequisites) -+ [Create a Build Project \(Console\)](#create-project-console) -+ [Create a Build Project \(AWS CLI\)](#create-project-cli) -+ [Create a Build Project \(AWS SDKs\)](#create-project-sdks) -+ [Create a Build Project \(AWS CloudFormation\)](#create-project-cloud-formation) ++ [Create a build project \(console\)](#create-project-console) ++ [Create a build project \(AWS CLI\)](#create-project-cli) ++ [Create a build project \(AWS SDKs\)](#create-project-sdks) ++ [Create a build project \(AWS CloudFormation\)](#create-project-cloud-formation) ## Prerequisites -Answer the questions in [Plan a Build](planning.md)\. +Answer the questions in [Plan a build](planning.md)\. -## Create a Build Project \(Console\) +## 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)\. @@ -27,7 +27,7 @@ Answer the questions in [Plan a Build](planning.md)\. In **Description**, enter an optional description for your project\. - Select **Build badge** to make your project's build status visible and embeddable\. For more information, see [Build Badges Sample](sample-build-badges.md)\. + 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\. @@ -56,7 +56,7 @@ CodeBuild does not support Bitbucket Server\. 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/) + + 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** @@ -82,7 +82,7 @@ When you use the console to create or update a build project, you can create a C + 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 CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. + 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`\. @@ -115,7 +115,7 @@ Do not set any environment variable with a name that begins with `CODEBUILD_`\. 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 build spec declaration takes lowest 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** @@ -130,7 +130,7 @@ If you choose **New service role**, the service role includes permission to decr + 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)\. + For more information, see the [Buildspec reference](build-spec-ref.md)\. 1. In **Artifacts**: @@ -138,9 +138,9 @@ If you choose **New service role**, the service role includes permission to decr + 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)\. + + 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 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: @@ -170,7 +170,7 @@ Do not append a trailing slash \(/\) to the end of the path prefix\. **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 CodeBuild](build-caching.md)\. + 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\. @@ -193,9 +193,9 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro 1. On the **Review** page, choose **Start build**\. -## Create a Build Project \(AWS CLI\) +## Create a build project \(AWS CLI\) -For information about using the AWS CLI with CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +For information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md)\. 1. Run the create\-project command: @@ -347,10 +347,10 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + *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`, then 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\-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 build spec \(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 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\. @@ -368,20 +368,20 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + 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 `source` because when you create a pipeline in CodePipeline, you specify the source code location in the Source stage of the pipeline\. + + 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)\. + + *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, or Bitbucket, an invalidInputException is thrown\. - + *gitSubmodulesConfig*: Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise, 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 only\. Set this value to `true` to ignore TSL warnings while connecting to your GitHub Enterprise project repository\. The default value is `false`\. *InsecureSsl* should be used for testing purposes only\. It should not be used in a production environment\. + + *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, or Bitbucket, an `invalidInputException` is thrown\. + + *gitSubmodulesConfig*: Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise, 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 only\. Set this value to `true` to ignore TLS warnings while connecting to your GitHub Enterprise 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 Simple Storage Service \(Amazon S3\): the version ID of the object that represents the build input ZIP file to use\. + + 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 CodeBuild](sample-source-version.md)\. + 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\. @@ -390,49 +390,50 @@ For information about using the AWS CLI with CodeBuild, see the [Command Line Re + *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*, then this is the name of the output bucket you created or identified in the prerequisites\. + + 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 `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*, then 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*, then the path and name would be `MyPath/MyArtifact.zip`\. + + 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*, then the path and name would be `MyPath/build-ID/MyArtifact.zip`\. + + 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*, then 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*, then the path and name would be `MyPath/MyArtifact.zip`\. - + *override\-artifact\-name*: Optional boolean value\. 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)\. + + 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\. + + 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 Amazon S3 bucket and the path prefix\. For example, if your Amazon 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\-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)\. + + *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 value\. If set to `true`, your S3 build log output is not encrypted\. By default, S3 build logs are encrypted\. + + *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 artifiact 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)\. + + *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 gitCloneDepth property](#cli-sources-gitclonedepth)\. + + *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)\. @@ -440,7 +441,7 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro + *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 Amazon VPC IDs in your region: + + *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 @@ -451,14 +452,14 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region us-east-1 ``` - If you are using an AWS Region other than `us-east-1`, be sure to use it when you run the command\. + 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 an AWS Region other than `us-east-1`, be sure to use it when you run the command\. + 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*\. @@ -467,9 +468,9 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro + *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`, and `WINDOWS_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:2.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 corresponding 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, and 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\. + + *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:2.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, and 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`\. @@ -487,7 +488,7 @@ Do not set any environment variable with a name that begins with `CODEBUILD_`\. 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 build spec declaration takes lowest 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** @@ -501,9 +502,9 @@ If you choose **New service role**, the service role includes permission to decr 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\. This requires that you modify your Amazon ECR repository policy to trust the CodeBuild service principal\. + + 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\. @@ -515,14 +516,12 @@ By default, Docker containers do not allow access to any devices\. Privileged mo - 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)\. + + *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\) CodeBuild uses 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\. + + *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 that contains a `key` and `value` value of *tag\-key* and *tag\-value*\. - For an example, see [To create the build project ](getting-started-cli-create-build-project.md#getting-started-cli-create-build-project-cli)\. - -1. Switch to the directory that contains the file you just saved, and run the create\-projectcommand again: +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 @@ -585,16 +584,16 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + 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)\. +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)\. -To start running a build, see [Run a Build \(AWS CLI\)](run-build.md#run-build-cli)\. +To start running a build, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. -If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start Running Builds Automatically \(AWS CLI\)](run-build.md#run-build-cli-auto-start)\. +If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start running builds automatically \(AWS CLI\)](run-build.md#run-build-cli-auto-start)\. -## Create a Build Project \(AWS SDKs\) +## Create a build project \(AWS SDKs\) -For information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and Tools Reference](sdk-ref.md)\. +For information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. -## Create a Build Project \(AWS CloudFormation\) +## Create a build project \(AWS CloudFormation\) For information about using AWS CodeBuild with AWS CloudFormation, see [the AWS CloudFormation template for CodeBuild](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-project.html) in the *AWS CloudFormation User Guide*\. \ No newline at end of file diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index a925437..950407b 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -1,4 +1,4 @@ -# Data Protection in AWS CodeBuild +# 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\. @@ -14,11 +14,11 @@ We strongly recommend that you never put sensitive identifying information, such 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)\. ++ Strings specified using AWS Secrets Manager\. 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*\. **Topics** -+ [Data Encryption](security-encryption.md) -+ [Key Management](security-key-management.md) -+ [Traffic Privacy](security-traffic-privacy.md) \ No newline at end of file ++ [Data encryption](security-encryption.md) ++ [Key management](security-key-management.md) ++ [Traffic privacy](security-traffic-privacy.md) \ No newline at end of file diff --git a/doc_source/delete-builds.md b/doc_source/delete-builds.md index 6dbf8be..9924d01 100644 --- a/doc_source/delete-builds.md +++ b/doc_source/delete-builds.md @@ -1,8 +1,8 @@ -# Delete Builds in CodeBuild +# Delete builds in AWS CodeBuild -To delete builds in CodeBuild, you can use the AWS CLI, or the AWS SDKs\. +You can use the AWS CLI or the AWS SDKs to delete builds in AWS CodeBuild\. -## Delete Builds \(AWS CLI\) +## Delete builds \(AWS CLI\) Run the `batch-delete-builds` command: @@ -12,8 +12,8 @@ aws codebuild batch-delete-builds --ids ids In the preceding command, replace the following placeholder: + *ids*: Required string\. The IDs of the builds to delete\. To specify multiple builds, separate each build ID with a space\. 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 Build IDs for a Build Project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) + + [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-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) If successful, a `buildsDeleted` array appears in the output, containing the Amazon Resource Name \(ARN\) of each build that was successfully deleted\. Information about builds that were not successfully deleted appears in output within a `buildsNotDeleted` array\. @@ -39,6 +39,6 @@ Information similar to the following appears in the output: } ``` -## Delete Builds \(AWS SDKs\) +## Delete builds \(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 +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/delete-project.md b/doc_source/delete-project.md index d21e916..dca3946 100644 --- a/doc_source/delete-project.md +++ b/doc_source/delete-project.md @@ -1,16 +1,16 @@ -# Delete a Build Project in AWS CodeBuild +# Delete a build project in AWS CodeBuild You can use the CodeBuild console, AWS CLI, or AWS SDKs to delete a build project in CodeBuild\. If you delete a project, its builds are not deleted\. **Warning** -You cannot delete a project that has builds and a resource policy\. To delete a project with a resource policy and builds, remove the resource policy or delete its builds first\. +You cannot delete a project that has builds and a resource policy\. To delete a project with a resource policy and builds, you must first remove the resource policy and delete its builds\. **Topics** -+ [Delete a Build Project \(Console\)](#delete-project-console) -+ [Delete a Build Project \(AWS CLI\)](#delete-project-cli) -+ [Delete a Build Project \(AWS SDKs\)](#delete-project-sdks) ++ [Delete a build project \(console\)](#delete-project-console) ++ [Delete a build project \(AWS CLI\)](#delete-project-cli) ++ [Delete a build project \(AWS SDKs\)](#delete-project-sdks) -## Delete a Build Project \(Console\) +## Delete 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)\. @@ -22,9 +22,7 @@ You cannot delete a project that has builds and a resource policy\. To delete a **Note** By default, only the most recent 10 build projects are displayed\. To view more build projects, choose a different value for **Projects per page** or use the back and forward arrows for viewing projects\. -## Delete a Build Project \(AWS CLI\) - -For more information about using the AWS CLI with AWS CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +## Delete a build project \(AWS CLI\) 1. Run the `delete-project` command: @@ -33,10 +31,12 @@ For more information about using the AWS CLI with AWS CodeBuild, see the [Comman ``` Replace the following placeholder: - + *name*: Required string\. The name of the build project to delete\. To get a list of available build projects, run the `list-projects` command\. For more information, see [View a List of Build Project Names \(AWS CLI\)](view-project-list.md#view-project-list-cli)\. + + *name*: Required string\. The name of the build project to delete\. To get a list of available build projects, run the `list-projects` command\. For more information, see [View a list of build project names \(AWS CLI\)](view-project-list.md#view-project-list-cli)\. 1. If successful, no data and no errors appear in the output\. -## Delete a Build Project \(AWS SDKs\) +For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. + +## Delete 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 +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/endpoint-specify.md b/doc_source/endpoint-specify.md index bc34755..4734bb3 100644 --- a/doc_source/endpoint-specify.md +++ b/doc_source/endpoint-specify.md @@ -1,4 +1,4 @@ -# Specify the CodeBuild Endpoint +# Specify the AWS CodeBuild endpoint You can use the AWS Command Line Interface \(AWS CLI\) or one of the AWS SDKs to specify the endpoint used by AWS CodeBuild\. There is an endpoint for each region in which CodeBuild is available\. In addition to a regional endpoint, four regions also have a Federal Information Processing Standards \(FIPS\) endpoint\. For more information about FIPS endpoints, see [FIPS 140\-2 Overview](https://aws.amazon.com/compliance/fips/)\. @@ -10,10 +10,10 @@ For endpoints that can be used with CodeBuild, see [CodeBuild Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region)\. **Topics** -+ [Specify the CodeBuild Endpoint \(AWS CLI\)](#endpoint-specify-cli) -+ [Specify the CodeBuild Endpoint \(AWS SDK\)](#endpoint-specify-sdk) ++ [Specify the AWS CodeBuild endpoint \(AWS CLI\)](#endpoint-specify-cli) ++ [Specify the AWS CodeBuild endpoint \(AWS SDK\)](#endpoint-specify-sdk) -## Specify the CodeBuild Endpoint \(AWS CLI\) +## Specify the AWS CodeBuild endpoint \(AWS CLI\) You can use the AWS CLI to specify the endpoint through which AWS CodeBuild is accessed by using the `--endpoint-url` argument in any CodeBuild command\. For example, run this command to get a list of project build names using the Federal Information Processing Standards \(FIPS\) endpoint in the US East \(N\. Virginia\) Region: @@ -25,7 +25,7 @@ Include the `https://` at the begining of the endpoint\. The `--endpoint-url` AWS CLI argument is available to all AWS services\. For more information about this and other AWS CLI arguments, see [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/)\. -## Specify the CodeBuild Endpoint \(AWS SDK\) +## Specify the AWS CodeBuild endpoint \(AWS SDK\) You can use an AWS SDK to specify the endpoint through which AWS CodeBuild is accessed\. Although this example uses the [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/), you can specify the endpoint with the other AWS SDKs\. diff --git a/doc_source/getting-started-build-log-console.md b/doc_source/getting-started-build-log-console.md index 7a63299..78b399a 100644 --- a/doc_source/getting-started-build-log-console.md +++ b/doc_source/getting-started-build-log-console.md @@ -1,14 +1,14 @@ -# Step 8: View Detailed Build Information +# Step 8: View detailed build information -\(Previous step: [Step 7: View Summarized Build Information](getting-started-monitor-build-console.md)\) +\(Previous step: [Step 7: View summarized build information](getting-started-monitor-build-console.md)\) In this step, you view detailed information about your build in CloudWatch Logs\. **Note** 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*\. + 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\. 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)\. + Strings specified using AWS Secrets Manager\. For more information, see [Key management](security-key-management.md)\. **To view detailed build information** @@ -18,6 +18,6 @@ In this step, you view detailed information about your build in CloudWatch Logs\ 1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. -## Next Step +## Next step -[Step 9: Get the Build Output Artifact](getting-started-output-console.md) \ No newline at end of file +[Step 9: Get the build output artifact](getting-started-output-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-clean-up-console.md b/doc_source/getting-started-clean-up-console.md index bc69ed6..b3d3db5 100644 --- a/doc_source/getting-started-clean-up-console.md +++ b/doc_source/getting-started-clean-up-console.md @@ -1,6 +1,6 @@ -# Step 10: Clean Up +# Step 10: Delete the S3 input bucket -\(Previous step: [Step 9: Get the Build Output Artifact](getting-started-output-console.md)\) +\(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*\. @@ -27,6 +27,6 @@ The ellipses \(\.\.\.\) in this statement are used for brevity\. Do not remove a } ``` -## Next Step +## Next step -[Wrapping Up](getting-started-next-steps-console.md) \ No newline at end of file +[Wrapping up](getting-started-next-steps-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-build-log.md b/doc_source/getting-started-cli-build-log.md index 50ff575..fc5a2bc 100644 --- a/doc_source/getting-started-cli-build-log.md +++ b/doc_source/getting-started-cli-build-log.md @@ -1,14 +1,14 @@ -# Step 8: View Detailed Build Information +# Step 8: View detailed build information -\(Previous step: [Step 7: View Summarized Build Information](getting-started-cli-monitor-build.md)\) +\(Previous step: [Step 7: View summarized build information](getting-started-cli-monitor-build.md)\) In this step, you view detailed information about your build in CloudWatch Logs\. **Note** 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*\. + 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\. 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)\. + Strings specified using AWS Secrets Manager\. For more information, see [Key management](security-key-management.md)\. **To view detailed build information** @@ -71,6 +71,6 @@ These portions of a CloudWatch Logs log stream pertain to this tutorial\. In this example, CodeBuild successfully completed the pre\-build, build, and post\-build build phases\. It ran the unit tests and successfully built the `messageUtil-1.0.jar` file\. -## Next Step +## Next step -[Step 9: Get the Build Output Artifact](getting-started-cli-output.md) \ No newline at end of file +[Step 9: Get the build output artifact](getting-started-cli-output.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-clean-up.md b/doc_source/getting-started-cli-clean-up.md index 7384968..2239494 100644 --- a/doc_source/getting-started-cli-clean-up.md +++ b/doc_source/getting-started-cli-clean-up.md @@ -1,6 +1,6 @@ -# Step 10: Clean Up +# Step 10: Delete the S3 input bucket -\(Previous step: [Step 9: Get the Build Output Artifact](getting-started-cli-output.md)\) +\(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*\. @@ -27,6 +27,6 @@ The ellipses \(\.\.\.\) in this statement are used for brevity\. Do not remove a } ``` -## Next Step +## Next step -[Wrapping Up](getting-started-cli-next-steps.md) \ No newline at end of file +[Wrapping up](getting-started-cli-next-steps.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 381f1c3..6c9df6d 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -1,6 +1,6 @@ -# Step 5: Create the Build Project +# Step 5: Create the build project -\(Previous step: [Step 4: Upload the Source Code and the Buildspec File](getting-started-cli-upload-source-code.md)\) +\(Previous step: [Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md)\) In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. @@ -38,7 +38,7 @@ For this build environment, you instruct CodeBuild to use a Docker image that co } ``` - Replace *serviceIAMRole* with the Amazon Resource Name \(ARN\) of a CodeBuild service role \(for example, `arn:aws:iam::account-ID:role/role-name`\)\. To create one, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. + Replace *serviceIAMRole* with the Amazon Resource Name \(ARN\) of a CodeBuild service role \(for example, `arn:aws:iam::account-ID:role/role-name`\)\. To create one, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. In this data: + `name` represents a required identifier for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across all build projects in your account\. @@ -49,10 +49,10 @@ For this build environment, you instruct CodeBuild to use a Docker image that co + 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:2.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\. - To find more Docker images you can use in your scenarios, see the [Build Environment Reference](build-env-ref.md)\. + 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`\)\. **Note** -Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this tutorial, so they are not shown here\. For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. +Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this tutorial, so they are not shown here\. For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. 1. Switch to the directory that contains the file you just saved, and then run the create\-project command again\. @@ -105,8 +105,8 @@ Other available values in the original JSON\-formatted data, such as `descriptio **Note** After you run the create\-project command, an error message similar to the following might be output: **User: *user\-ARN* is not authorized to perform: codebuild:CreateProject**\. This is most likely because you configured the AWS CLI with the credentials of an IAM user who does not have sufficient permissions to use CodeBuild to create build projects\. To fix this, configure the AWS CLI with credentials belonging to one of the following IAM entities: 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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. +An IAM user in your AWS account with the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS managed \(predefined\) policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. -## Next Step +## Next step -[Step 6: Run the Build](getting-started-cli-run-build.md) \ No newline at end of file +[Step 6: Run the build](getting-started-cli-run-build.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-spec.md b/doc_source/getting-started-cli-create-build-spec.md index 22a546e..b291c2e 100644 --- a/doc_source/getting-started-cli-create-build-spec.md +++ b/doc_source/getting-started-cli-create-build-spec.md @@ -1,8 +1,8 @@ -# Step 3: Create the Buildspec File +# Step 3: Create the buildspec file -\(Previous step: [Step 2: Create the Source Code](getting-started-cli-create-source-code.md)\) +\(Previous step: [Step 2: Create the source code](getting-started-cli-create-source-code.md)\) -In this step, you create a build specification \(build spec\) file\. A *build spec* 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\. +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\. Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. @@ -32,7 +32,7 @@ artifacts: Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. **Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. +Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. In this build spec declaration: + `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. @@ -41,7 +41,7 @@ In this build spec declaration: In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. + `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. -For more information, see the [Buildspec Reference](build-spec-ref.md)\. +For more information, see the [Buildspec reference](build-spec-ref.md)\. At this point, your directory structure should look like this\. @@ -58,6 +58,6 @@ At this point, your directory structure should look like this\. `-- TestMessageUtil.java ``` -## Next Step +## 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 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-create-source-code.md b/doc_source/getting-started-cli-create-source-code.md index 111ec62..f03efde 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 2: Create the source code -\(Previous step: [Step 1: Create Two S3 Buckets](getting-started-cli-input-bucket.md)\) +\(Previous step: [Step 1: Create two S3 buckets](getting-started-cli-input-bucket.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\. @@ -117,6 +117,6 @@ At this point, your directory structure should look like this\. `-- TestMessageUtil.java ``` -## Next Step +## Next step -[Step 3: Create the Buildspec File](getting-started-cli-create-build-spec.md) \ No newline at end of file +[Step 3: 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 541bd7c..148539c 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 1: Create two S3 buckets -\(Part of: [Getting Started with CodeBuild Using the AWS CLI](getting-started-cli.md)\) +\(Part of: [Getting started with AWS CodeBuild using the AWS CLI](getting-started-cli.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\. @@ -13,8 +13,8 @@ These two buckets must be in the same AWS Region as your builds\. For example, i For more information, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon Simple Storage Service User Guide*\. **Note** -Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a Build](planning.md)\. +Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a build](planning.md)\. -## Next Step +## Next step -[Step 2: Create the Source Code](getting-started-cli-create-source-code.md) \ No newline at end of file +[Step 2: Create the source code](getting-started-cli-create-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 0384752..976a7c3 100644 --- a/doc_source/getting-started-cli-monitor-build.md +++ b/doc_source/getting-started-cli-monitor-build.md @@ -1,6 +1,6 @@ -# Step 7: View Summarized Build Information +# Step 7: View summarized build information -\(Previous step: [Step 6: Run the Build](getting-started-cli-run-build.md)\) +\(Previous step: [Step 6: Run the build](getting-started-cli-run-build.md)\) In this step, you view summarized information about the status of your build\. @@ -79,6 +79,6 @@ 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\. -## Next Step +## Next step -[Step 8: View Detailed Build Information](getting-started-cli-build-log.md) \ No newline at end of file +[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 bb6b116..355849a 100644 --- a/doc_source/getting-started-cli-next-steps.md +++ b/doc_source/getting-started-cli-next-steps.md @@ -1,5 +1,5 @@ -# Wrapping Up +# 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 +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 1c14a11..a8ab3c8 100644 --- a/doc_source/getting-started-cli-output.md +++ b/doc_source/getting-started-cli-output.md @@ -1,6 +1,6 @@ -# Step 9: Get the Build Output Artifact +# Step 9: Get the build output artifact -\(Previous step: [Step 8: View Detailed Build Information](getting-started-cli-build-log.md)\) +\(Previous step: [Step 8: View detailed build information](getting-started-cli-build-log.md)\) In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. @@ -12,8 +12,6 @@ You can use the CodeBuild console or the Amazon S3 console to complete this step 1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. -: - **To get the build output artifact \(Amazon S3 console\)** 1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. @@ -24,6 +22,6 @@ You can use the CodeBuild console or the Amazon S3 console to complete this step 1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. -## Next Step +## Next step -[Step 10: Clean Up](getting-started-cli-clean-up.md) \ No newline at end of file +[Step 10: Delete the S3 input bucket](getting-started-cli-clean-up.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-run-build.md b/doc_source/getting-started-cli-run-build.md index 18cd64b..257ef82 100644 --- a/doc_source/getting-started-cli-run-build.md +++ b/doc_source/getting-started-cli-run-build.md @@ -1,6 +1,6 @@ -# Step 6: Run the Build +# Step 6: Run the build -\(Previous step: [Step 5: Create the Build Project](getting-started-cli-create-build-project.md)\) +\(Previous step: [Step 5: Create the build project](getting-started-cli-create-build-project.md)\) In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. @@ -57,6 +57,6 @@ In this step, you instruct AWS CodeBuild to run the build with the settings in t Make a note of the `id` value\. You need it in the next step\. -## Next Step +## Next step -[Step 7: View Summarized Build Information](getting-started-cli-monitor-build.md) \ No newline at end of file +[Step 7: View summarized build information](getting-started-cli-monitor-build.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 6b68365..0bf1190 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 +# 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 the buildspec file](getting-started-cli-create-build-spec.md)\) In this step, you add the source code and build spec file to the input bucket\. @@ -29,8 +29,8 @@ Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID **Important** For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. +If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. -## Next Step +## Next step -[Step 5: Create the Build Project](getting-started-cli-create-build-project.md) \ No newline at end of file +[Step 5: Create the build project](getting-started-cli-create-build-project.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md index a0e1b3c..11ceb46 100644 --- a/doc_source/getting-started-cli.md +++ b/doc_source/getting-started-cli.md @@ -1,21 +1,21 @@ -# Getting Started with CodeBuild Using the AWS CLI +# Getting started with AWS CodeBuild using the AWS CLI 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 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 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)\. **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 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: Clean Up](getting-started-cli-clean-up.md) -+ [Wrapping Up](getting-started-cli-next-steps.md) \ No newline at end of file ++ [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 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) ++ [Wrapping up](getting-started-cli-next-steps.md) \ No newline at end of file diff --git a/doc_source/getting-started-create-build-project-console.md b/doc_source/getting-started-create-build-project-console.md index 90c9c66..1bdbd0e 100644 --- a/doc_source/getting-started-create-build-project-console.md +++ b/doc_source/getting-started-create-build-project-console.md @@ -1,6 +1,6 @@ -# Step 5: Create the Build Project +# Step 5: Create the build project -\(Previous step: [Step 4: Upload the Source Code and the Buildspec File](getting-started-upload-source-code-console.md)\) +\(Previous step: [Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md)\) In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. @@ -18,8 +18,8 @@ For this build environment, you instruct CodeBuild to use a Docker image that co **Note** On the **Create build project** page, you might see an error message similar to the following: **You are not authorized to perform this operation\.**\. This is most likely because you signed in to the AWS Management Console as an IAM user who does not have permissions to create a build project\.\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: 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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS Managed \(Predefined\) Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. -Both options include administrator permissions that allow you to create a build project so you can complete this tutorial\. We recommend that you always use the minimum permissions required to accomplish your task\. For more information, see [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. +An IAM user in your AWS account with the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS managed \(predefined\) policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. +Both options include administrator permissions that allow you to create a build project so you can complete this tutorial\. We recommend that you always use the minimum permissions required to accomplish your task\. For more information, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. 1. In **Source**, for **Source provider**, choose **Amazon S3**\. @@ -47,6 +47,6 @@ Both options include administrator permissions that allow you to create a build 1. Choose **Create build project**\. -## Next Step +## Next step -[Step 6: Run the Build](getting-started-run-build-console.md) \ No newline at end of file +[Step 6: Run the build](getting-started-run-build-console.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 2d1e312..2015f64 100644 --- a/doc_source/getting-started-create-build-spec-console.md +++ b/doc_source/getting-started-create-build-spec-console.md @@ -1,8 +1,8 @@ -# Step 3: Create the Buildspec File +# Step 3: Create the buildspec file -\(Previous step: [Step 2: Create the Source Code](getting-started-create-source-code-console.md)\) +\(Previous step: [Step 2: Create the source code](getting-started-create-source-code-console.md)\) -In this step, you create a build specification \(build spec\) file\. A *build spec* 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\. +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\. Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. @@ -32,7 +32,7 @@ artifacts: Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. **Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. +Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. In this build spec declaration: + `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. @@ -41,7 +41,7 @@ In this build spec declaration: In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. + `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. -For more information, see the [Buildspec Reference](build-spec-ref.md)\. +For more information, see the [Buildspec reference](build-spec-ref.md)\. At this point, your directory structure should look like this\. @@ -58,6 +58,6 @@ At this point, your directory structure should look like this\. `-- TestMessageUtil.java ``` -## Next Step +## 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 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-create-source-code-console.md b/doc_source/getting-started-create-source-code-console.md index 4b463ab..d1b4b32 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 2: Create the source code -\(Previous step: [Step 1: Create Two S3 Buckets](getting-started-input-bucket-console.md)\) +\(Previous step: [Step 1: Create two S3 buckets](getting-started-input-bucket-console.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\. @@ -117,6 +117,6 @@ At this point, your directory structure should look like this\. `-- TestMessageUtil.java ``` -## Next Step +## Next step -[Step 3: Create the Buildspec File](getting-started-create-build-spec-console.md) \ No newline at end of file +[Step 3: 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 0776340..7cbe469 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 1: Create two S3 buckets -\(Part of: [Getting Started with CodeBuild in the Console](getting-started.md)\) +\(Part of: [Getting started with AWS CodeBuild using the console](getting-started.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\. @@ -13,8 +13,8 @@ These two buckets must be in the same AWS Region as your builds\. For example, i For more information, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon Simple Storage Service User Guide*\. **Note** -Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a Build](planning.md)\. +Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a build](planning.md)\. -## Next Step +## Next step -[Step 2: Create the Source Code](getting-started-create-source-code-console.md) \ No newline at end of file +[Step 2: Create the source code](getting-started-create-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 a1b4310..fea62ff 100644 --- a/doc_source/getting-started-monitor-build-console.md +++ b/doc_source/getting-started-monitor-build-console.md @@ -1,6 +1,6 @@ -# Step 7: View Summarized Build Information +# Step 7: View summarized build information -\(Previous step: [Step 6: Run the Build](getting-started-run-build-console.md)\) +\(Previous step: [Step 6: Run the build](getting-started-run-build-console.md)\) In this step, you view summarized information about the status of your build\. @@ -27,6 +27,6 @@ In this step, you view summarized information about the status of your build\. 1. Next to each build phase, the **Duration** value indicates how long the build phase lasted\. The **End time** value indicates when that build phase ended\. -## Next Step +## Next step -[Step 8: View Detailed Build Information](getting-started-build-log-console.md) \ No newline at end of file +[Step 8: View detailed build information](getting-started-build-log-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-next-steps-console.md b/doc_source/getting-started-next-steps-console.md index 1e2830d..7d63d3c 100644 --- a/doc_source/getting-started-next-steps-console.md +++ b/doc_source/getting-started-next-steps-console.md @@ -1,5 +1,5 @@ -# Wrapping Up +# 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 +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 f82b344..e71a306 100644 --- a/doc_source/getting-started-output-console.md +++ b/doc_source/getting-started-output-console.md @@ -1,6 +1,6 @@ -# Step 9: Get the Build Output Artifact +# Step 9: Get the build output artifact -\(Previous step: [Step 8: View Detailed Build Information](getting-started-build-log-console.md)\) +\(Previous step: [Step 8: View detailed build information](getting-started-build-log-console.md)\) In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. @@ -12,8 +12,6 @@ You can use the CodeBuild console or the Amazon S3 console to complete this step 1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. -: - **To get the build output artifact \(Amazon S3 console\)** 1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. @@ -24,6 +22,6 @@ You can use the CodeBuild console or the Amazon S3 console to complete this step 1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. -## Next Step +## Next step -[Step 10: Clean Up](getting-started-clean-up-console.md) \ No newline at end of file +[Step 10: Delete the S3 input bucket](getting-started-clean-up-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-overview.md b/doc_source/getting-started-overview.md index ebff61d..5ee0384 100644 --- a/doc_source/getting-started-overview.md +++ b/doc_source/getting-started-overview.md @@ -1,8 +1,8 @@ -# Getting Started with CodeBuild +# Getting started with CodeBuild In the following tutorials, you use AWS CodeBuild to build a collection of sample source code input files into a deployable version of the source code\. -Both tutorials have the same input and results, but one uses the CodeBuild console and the other uses the AWS CLI\. You can choose to follow either or both\. +Both tutorials have the same input and results, but one uses the AWS CodeBuild console and the other uses the AWS CLI\. **Important** -It is not recommended that you use your AWS root account to complete this tutorial\. \ No newline at end of file +We do not recommend that you use your AWS root account to complete this tutorial\. \ 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 572efc4..f0bdf65 100644 --- a/doc_source/getting-started-run-build-console.md +++ b/doc_source/getting-started-run-build-console.md @@ -1,6 +1,6 @@ -# Step 6: Run the Build +# Step 6: Run the build -\(Previous step: [Step 5: Create the Build Project](getting-started-create-build-project-console.md)\) +\(Previous step: [Step 5: Create the build project](getting-started-create-build-project-console.md)\) In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. @@ -14,6 +14,6 @@ In this step, you instruct AWS CodeBuild to run the build with the settings in t 1. On the **Start build** page, choose **Start build**\. -## Next Step +## Next step -[Step 7: View Summarized Build Information](getting-started-monitor-build-console.md) \ No newline at end of file +[Step 7: View summarized build information](getting-started-monitor-build-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-upload-source-code-console.md b/doc_source/getting-started-upload-source-code-console.md index 5ddf1b3..31adc7e 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 +# 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 the buildspec file](getting-started-create-build-spec-console.md)\) In this step, you add the source code and build spec file to the input bucket\. @@ -29,8 +29,8 @@ Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID **Important** For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec File Name and Storage Location](build-spec-ref.md#build-spec-ref-name-storage)\. +If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. -## Next Step +## Next step -[Step 5: Create the Build Project](getting-started-create-build-project-console.md) \ No newline at end of file +[Step 5: Create the build project](getting-started-create-build-project-console.md) \ No newline at end of file diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index e79392c..97c30af 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -1,21 +1,21 @@ -# Getting Started with CodeBuild in the Console +# Getting started with AWS CodeBuild using the console 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 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 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)\. **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)\. +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 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: Clean Up](getting-started-clean-up-console.md) -+ [Wrapping Up](getting-started-next-steps-console.md) \ No newline at end of file ++ [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 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) ++ [Wrapping up](getting-started-next-steps-console.md) \ No newline at end of file diff --git a/doc_source/glossary.md b/doc_source/glossary.md index 587d9a2..0fccc48 100644 --- a/doc_source/glossary.md +++ b/doc_source/glossary.md @@ -1,3 +1,3 @@ -# AWS Glossary +# AWS glossary -For the latest AWS terminology, see the [AWS Glossary](https://docs.aws.amazon.com/general/latest/gr/glos-chap.html) in the *AWS General Reference*\. \ No newline at end of file +For the latest AWS terminology, see the [AWS glossary](https://docs.aws.amazon.com/general/latest/gr/glos-chap.html) in the *AWS General Reference*\. \ No newline at end of file diff --git a/doc_source/history.md b/doc_source/history.md index 51e2266..e81a426 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -1,43 +1,44 @@ -# AWS CodeBuild User Guide Document History +# 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: **March 16, 2020 ++ **Latest documentation update: **May 6, 2020 | Change | Description | Date | | --- |--- |--- | -| [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 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 | -| [Updated topic](#history) | CodeBuild now supports using an access token to connect to GitHub \(with a personal access token\) and Bitbucket \(with an app password\) repositories\. For more information, see [Create a Build Project \(Console\)](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html#create-project-console) and [Using Access Tokens with Your Source Provider](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-access-tokens.html)\. | December 6, 2018 | -| [Updated topic](#history) | CodeBuild now supports new build metrics that measure the duration of each phase in a build\. For more information, see [ CodeBuild CloudWatch Metrics](https://docs.aws.amazon.com/codebuild/latest/userguide/monitoring-builds.html#cloudwatch_metrics-codebuild)\. | November 15, 2018 | -| [VPC Endpoint Policy Topic](#history) | Amazon VPC endpoints for CodeBuild now support policies\. For more information, see [ Create a VPC Endpoint Policy for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/use-vpc-endpoints-with-codebuild.html#creating-vpc-endpoint-policy)\. | November 9, 2018 | +| [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 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 | +| [Updated topic](#history) | CodeBuild now supports using an access token to connect to GitHub \(with a personal access token\) and Bitbucket \(with an app password\) repositories\. For more information, see [Create a build project \(console\)](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html#create-project-console) and [Use access tokens with your source provider](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-access-tokens.html)\. | December 6, 2018 | +| [Updated topic](#history) | CodeBuild now supports new build metrics that measure the duration of each phase in a build\. For more information, see [ CodeBuild CloudWatch metrics](https://docs.aws.amazon.com/codebuild/latest/userguide/monitoring-builds.html#cloudwatch_metrics-codebuild)\. | November 15, 2018 | +| [VPC endpoint policy topic](#history) | Amazon VPC endpoints for CodeBuild now support policies\. For more information, see [ Create a VPC endpoint policy for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/use-vpc-endpoints-with-codebuild.html#creating-vpc-endpoint-policy)\. | November 9, 2018 | | [Updated content](#history) | Topics have been updated to reflect the new console experience\. | October 30, 2018 | -| [Amazon EFS sample](#history) | CodeBuild can mount an Amazon EFS file system during a build using commands in a project's buildspec file\. For more information, see [Amazon EFS Sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-efs.html)\. | October 26, 2018 | -| [BitBucket webhooks](#history) | CodeBuild now supports webhooks when you use BitBucket for your repository\. For more information, see [Bitbucket Pull Request Sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html)\. | October 2, 2018 | -| [S3 logs](#history) | CodeBuild now supports build logs in an S3 bucket\. Previously, you could only build logs using CloudWatch Logs\. For more information, see [Create Project](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html)\. | September 17, 2018 | -| [Multiple inpout sources and mulitple output artifacts](#history) | CodeBuild now supports projects that use more than one input source and publish more than one set of artifacts\. For more information, see [ Multiple Input Sources and Output Artifacts Sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html) and [CodePipeline Integration with CodeBuild and Multiple Input Sources and Output Artifacts Sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-pipeline-multi-input-output.html)\. | August 30, 2018 | -| [Semantic versioning sample](#history) | The CodeBuild User Guide now has a use case\-based sample that demonstrates how to use semantic versioning to create artifact names at build time\. For more information, see [ Semantic Versioning Your Build Artifacts Sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-buildspec-artifact-naming.html)\. | August 14, 2018 | -| [New static website sample](#history) | The CodeBuild User Guide now has a use case\-based sample that demonstrates how to host build output in an Amazon S3 bucket\. The sample takes advantage of the recent support of unencrypted build artifiacts\. For more information, see [ Create a Static Website with Build Output Hosted in an Amazon S3 Bucket](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-disable-artifact-encryption.html)\. | August 14, 2018 | +| [Amazon EFS sample](#history) | CodeBuild can mount an Amazon EFS file system during a build using commands in a project's buildspec file\. For more information, see [Amazon EFS sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-efs.html)\. | October 26, 2018 | +| [Bitbucket webhooks](#history) | CodeBuild now supports webhooks when you use Bitbucket for your repository\. For more information, see [Bitbucket pull request sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html)\. | October 2, 2018 | +| [S3 logs](#history) | CodeBuild now supports build logs in an S3 bucket\. Previously, you could only build logs using CloudWatch Logs\. For more information, see [Create project](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html)\. | September 17, 2018 | +| [Multiple inpout sources and multiple output artifacts](#history) | CodeBuild now supports projects that use more than one input source and publish more than one set of artifacts\. For more information, see [ Multiple input sources and input artifacts sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html) and [CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-pipeline-multi-input-output.html)\. | August 30, 2018 | +| [Semantic versioning sample](#history) | The CodeBuild User Guide now has a use case\-based sample that demonstrates how to use semantic versioning to create artifact names at build time\. For more information, see [ Use semantic versioning to name build artifacts sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-buildspec-artifact-naming.html)\. | August 14, 2018 | +| [New static website sample](#history) | The CodeBuild User Guide now has a use case\-based sample that demonstrates how to host build output in an S3 bucket\. The sample takes advantage of the recent support of unencrypted build artifacts\. For more information, see [Create a static website with build output hosted in an S3 bucket](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-disable-artifact-encryption.html)\. | August 14, 2018 | | [Support for overriding an artifact name with semantic versioning](#history) | You can now use semantic versioning to specify a format that CodeBuild uses to name build artifacts\. This is useful because a build artifact with a hard\-coded name overwrites previous build artifacts that use the same hard\-coded name\. For example, if a build is triggered multiple times a day, you can now add a timestamp to its artifact name\. Each build artifact name is unique and does not overwrite the artifacts of previous builds\. | August 7, 2018 | -| [Support of unencrypted build artifacts](#history) | CodeBuild now supports builds with unencrypted build artifacts\. For more information, see [Create a Build Project \(Console\)](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html#create-project-console)\. | July 26, 2018 | -| [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 | -| [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 | +| [Support of unencrypted build artifacts](#history) | CodeBuild now supports builds with unencrypted build artifacts\. For more information, see [Create a build project \(console\)](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html#create-project-console)\. | July 26, 2018 | +| [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 | +| [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 +## Earlier updates The following table describes important changes in each release of the *AWS CodeBuild User Guide* before June 2018\. @@ -46,39 +47,39 @@ 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.md#run-build-cli)\. | 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 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 riggers to schedule builds at regular frequencies\. For more information, see [Create 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 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic in the Amazon Web Services General Reference\. | March 28, 2018 | -| GitHub Enterprise support | CodeBuild can now build from source code stored in a GitHub Enterprise repository\. For more information, see [GitHub Enterprise 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.md#run-build-cli)\. | 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 support | CodeBuild can now build from source code stored in a GitHub Enterprise repository\. For more information, see [GitHub Enterprise 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 [Use AWS Config with AWS CodeBuild 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic 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.md#run-build-console) or the `sourceVersion` value in [Run a Build \(AWS CLI\)](run-build.md#run-build-cli)\. | 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic 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 an 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 the [AWS CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) section of the "AWS Regions and Endpoints" topic 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 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 | +| 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.md#run-build-console) or the `sourceVersion` value in [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. | 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 diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 6f4fac5..e5299fa 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -1,6 +1,6 @@ -# Use CodePipeline with CodeBuild to Test Code and Run Builds +# Use 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 CodeBuild\. +You can automate your release process by using AWS CodePipeline to test your code and run your builds with AWS CodeBuild\. The following table lists tasks and the methods available for performing them\. Using the AWS SDKs to accomplish these tasks is outside the scope of this topic\. @@ -14,20 +14,20 @@ The following table lists tasks and the methods available for performing them\. **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 an CodeBuild Build Action to a Pipeline \(CodePipeline Console\)](#how-to-create-pipeline-add) -+ [Add an CodeBuild Test Action to a Pipeline \(CodePipeline Console\)](#how-to-create-pipeline-add-test) ++ [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)\. +1. Answer the questions in [Plan a build](planning.md)\. -1. If you are using an IAM user to access CodePipeline instead of an AWS root account or an administrator IAM user, attach the managed policy named `AWSCodePipelineFullAccess` to the user \(or to the IAM group to which the user belongs\)\. \(Using an AWS root account is not recommended\.\) This enables the user to create the pipeline in CodePipeline\. For more information, see [Attaching Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) in the *IAM User Guide*\. +1. If you are using an IAM user to access CodePipeline instead of an AWS root account or an administrator IAM user, attach the managed policy named `AWSCodePipelineFullAccess` to the user \(or to the IAM group to which the user belongs\)\. Using an AWS root account is not recommended\. This policy grants the user permission to create the pipeline in CodePipeline\. For more information, see [Attaching Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) in the *IAM User Guide*\. **Note** The IAM entity that attaches the policy to the user \(or to the IAM group to which the user belongs\) must have permission in IAM to attach policies\. For more information, see [Delegating Permissions to Administer IAM Users, Groups, and Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_delegate-permissions.html) in the *IAM User Guide*\. -1. Create a CodePipeline service role, if you do not already have one available in your AWS account\. This service role enables CodePipeline to interact with other AWS services, including AWS CodeBuild, on your behalf\. For example, to use the AWS CLI to create a CodePipeline service role, run the IAM `create-role` command: +1. Create a CodePipeline service role, if you do not already have one available in your AWS account\. CodePipeline uses this service role to interact with other AWS services, including AWS CodeBuild, on your behalf\. For example, to use the AWS CLI to create a CodePipeline service role, run the IAM `create-role` command: For Linux, macOS, or Unix: @@ -43,30 +43,28 @@ The IAM entity that attaches the policy to the user \(or to the IAM group to whi **Note** The IAM entity that creates this CodePipeline service role must have permission in IAM to create service roles\. -1. After you create a CodePipeline service role or identify an existing one, you must add the default CodePipeline service role policy to the service role as described in [Review the Default CodePipeline Service Role Policy](https://docs.aws.amazon.com/codepipeline/latest/userguide/iam-identity-based-access-control.html#how-to-custom-role) in the *CodePipeline User Guide*, if it isn't already a part of the policy for the role\. +1. After you create a CodePipeline service role or identify an existing one, you must add the default CodePipeline service role policy to the service role as described in [Review the Default CodePipeline Service Role Policy](https://docs.aws.amazon.com/codepipeline/latest/userguide/iam-identity-based-access-control.html#how-to-custom-role) in the *AWS CodePipeline User Guide*, if it isn't already a part of the policy for the role\. **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, 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)\. **Important** -If you plan to use the pipeline to deploy built source code, then the build output artifact must be compatible with the deployment system you use\. -For CodeDeploy, see the [CodeDeploy Sample](sample-codedeploy.md) in this guide and see [Prepare a Revision for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-revision.html) in the *CodeDeploy User Guide*\. -For AWS Elastic Beanstalk, see the [Elastic Beanstalk Sample](sample-elastic-beanstalk.md) in this guide and see [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*\. +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\) +## 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 an 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 an 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 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** +**To use the create pipeline wizard in CodePipeline to create a pipeline that uses CodeBuild** -1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. - - You need to have already signed in to the AWS Management Console by using: +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: @@ -96,7 +94,9 @@ To create a pipeline that only tests your source code: opsworks:DescribeLayers ``` -1. In the AWS region selector, choose the region where your build project AWS resources are located\. This region must also support CodeBuild\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the "Regions and Endpoints" topic in the *Amazon Web Services General Reference*\. +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**\. @@ -106,75 +106,30 @@ To create a pipeline that only tests your source code: Choose **New service role**, and in **Role Name**, enter the name for your new service role\. - Choose **Existing service role**, and then choose CodePipeline service role you created or identified as part of this topic's prerequisites\. + 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 Amazon S3 artifact bucket designated as the default, for your pipeline in the region you have selected for your pipeline\. - + Choose **Custom location** if you already have an existing artifact store you have created, such as an Amazon S3 artifact bucket, in the same region as your pipeline\. + + 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 Amazon S3 bucket, is required for each pipeline, in the same region as the pipeline +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 Amazon S3 bucket, choose **Amazon S3**\. For **Bucket**, select the Amazon 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 represents 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 represents the version of the source code you want to build\. + + 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\. -**Note** -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.md#create-project-console) or [Change a Build Project's Settings \(Console\)](change-project.md#change-project-console)\. -**Important** -If you enable webhooks for an AWS 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 build spec\. \(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**\. + 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.md#create-project-console) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. **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 build spec file, choose **Use a buildspec file**\. - + If your source code does not include a build spec 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\. +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\. @@ -186,7 +141,7 @@ To store and retrieve sensitive values, we recommend your build commands use the 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)\. +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/)\. @@ -198,25 +153,25 @@ You can also get the build output artifact by choosing the **Build artifacts** l 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 in step 24 of this procedure\. +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\) +## 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)\. +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.md#create-project-cli)\. +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.md#create-project-cli)\. 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 Amazon S3 input bucket and a build action that uses CodeBuild: +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: ``` { @@ -289,12 +244,12 @@ The build project must define build output artifact settings \(even though CodeP 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 Amazon 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 *CodePipeline User Guide*\. + + 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 Amazon S3 bucket used by this pipeline\. For more information, see [Create a Policy for an Amazon 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 *CodePipeline User Guide*\. + + 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 [CodePipeline Pipeline Structure Reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/pipeline-structure.html) in the *CodePipeline User Guide*\. + 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: @@ -302,7 +257,7 @@ The build project must define build output artifact settings \(even though CodeP aws codepipeline create-pipeline --cli-input-json file://create-pipeline.json ``` **Note** -You must create the pipeline in an AWS Region that supports CodeBuild\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the "Regions and Endpoints" topic in the *Amazon Web Services General Reference*\. +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\. @@ -339,7 +294,7 @@ You must create the pipeline in an AWS Region that supports CodeBuild\. For more 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)\. +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\. @@ -355,11 +310,9 @@ You can also get the build output artifact by choosing the **Build artifacts** l 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 an CodeBuild Build Action to a Pipeline \(CodePipeline Console\) - -1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. +## Add a CodeBuild build action to a pipeline \(CodePipeline console\) - You should have already signed in to the AWS Management Console by using: +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: @@ -389,7 +342,9 @@ You can also get the build output artifact by choosing the **Build artifacts** l opsworks:DescribeLayers ``` -1. In the AWS region selector, choose the region where your pipeline is located\. This region must also support CodeBuild\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the "Regions and Endpoints" topic in the *Amazon Web Services General Reference*\. +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\. @@ -401,8 +356,7 @@ This procedure shows you how to add a build action in a build stage between the 1. Between the **Source** and **Beta** stages, choose **Add stage**\. **Note** -This procedure shows you how to add a build stage 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\. -This procedure shows you how to add a build stage between the **Source** and **Beta** stages\. To add the build stage somewhere else, choose **Add stage** in the desired place\. +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\. @@ -416,10 +370,10 @@ This procedure shows you want how to add the build action inside of a build stag 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\. -**Note** -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.md#create-project-console) or [Change a Build Project's Settings \(Console\)](change-project.md#change-project-console)\. + + 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.md#create-project-console) 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) +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)\. @@ -430,11 +384,11 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui 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 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 build spec\. \(Do not run the following build commands if you chose a build environment image provided by CodeBuild with Docker support\.\) + 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& @@ -459,14 +413,14 @@ We strongly discourage storing sensitive values, especially AWS access key IDs a 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 build spec file, choose **Use a buildspec file**\. - + If your source code does not include a build spec 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\. + + 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 in step 4 of this procedure\. +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**\)\. @@ -478,7 +432,7 @@ To store and retrieve sensitive values, we recommend your build commands use the 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\. +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/)\. @@ -490,17 +444,15 @@ You can also get the build output artifact by choosing the **Build artifacts** l 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 in step 28 of this procedure\. +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 an CodeBuild Test Action to a Pipeline \(CodePipeline Console\) - -1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. +## Add a CodeBuild test action to a pipeline \(CodePipeline console\) - You should have already signed in to the AWS Management Console by using: +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: @@ -530,11 +482,13 @@ You can also get the build output artifact by choosing the **Build artifacts** l opsworks:DescribeLayers ``` -1. In the AWS region selector, choose the region where your pipeline is located\. This region must also support CodeBuild\. For more information, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the "Regions and Endpoints" topic in the *Amazon Web Services General Reference*\. +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**\): +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**\. @@ -542,8 +496,7 @@ This procedure shows you how to add a test action inside of a test stage between 1. Immediately after the **Source** stage, choose **Add stage**\. **Note** -This procedure shows you how to add a test 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\. -This procedure also shows you how to add a test stage immediately after the **Source** stage\. To add the test stage somewhere else, choose **Add stage** in the desired place\. +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\. @@ -558,7 +511,7 @@ This procedure shows you how to add the test action in a test stage\. To add the 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) +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)\. @@ -569,11 +522,11 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui 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 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 build spec\. \(Do not run the following build commands if you chose a build environment image provided by CodeBuild with Docker support\.\) + 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& @@ -598,14 +551,14 @@ We strongly discourage storing sensitive values, especially AWS access key IDs a 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 build spec file, choose **Use a buildspec file**\. - + If your source code does not include a build spec 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\. + + 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 in step 4 of this procedure\. +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\. diff --git a/doc_source/how-to-integrate-config.md b/doc_source/how-to-integrate-config.md index 7f30d1d..0d2fd24 100644 --- a/doc_source/how-to-integrate-config.md +++ b/doc_source/how-to-integrate-config.md @@ -1,4 +1,4 @@ -# Use AWS Config with AWS CodeBuild Sample +# Use AWS Config with CodeBuild sample AWS Config provides an inventory of your AWS resources and a history of configuration changes to these resources\. AWS Config now supports AWS CodeBuild as an AWS resource, which means the service can track your CodeBuild projects\. For more information about AWS Config, see [What Is AWS Config?](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) in the *AWS Config Developer Guide*\. @@ -12,22 +12,22 @@ The procedures in this topic show you how to set up AWS Config and look up and v **Topics** + [Prerequisites](#how-to-create-a-build-project) -+ [Set Up AWS Config](#setup-config) -+ [Look Up AWS CodeBuild Projects](#lookup-projects) -+ [Viewing AWS CodeBuild Configuration Details in the AWS Config Console](#viewing-config-details) ++ [Set up AWS Config](#setup-config) ++ [Look up AWS CodeBuild projects](#lookup-projects) ++ [Viewing AWS CodeBuild configuration details in the AWS Config console](#viewing-config-details) ## Prerequisites -Create your AWS CodeBuild project\(s\)\. For more information, see [Create a Build Project](create-project.md)\. +Create your AWS CodeBuild project\. For instructions, see [Create a build project](create-project.md)\. -## Set Up AWS Config +## Set up AWS Config + [Setting up AWS Config \(Console\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-console.html) + [Setting up AWS Config \(AWS CLI\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-cli.html) **Note** -It can take up to 10 minutes before a user is able to see AWS CodeBuild projects in the AWS Config console\. +After you complete setup, it might take up to 10 minutes before you can see AWS CodeBuild projects in the AWS Config console\. -## Look Up AWS CodeBuild Projects +## Look up AWS CodeBuild projects 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)\. @@ -38,7 +38,7 @@ It can take up to 10 minutes before a user is able to see AWS CodeBuild projects 1. After the list of CodeBuild projects is added, choose the CodeBuild project name link in the **Config timeline** column\. -## Viewing AWS CodeBuild Configuration Details in the AWS Config Console +## Viewing AWS CodeBuild configuration details in the AWS Config console When you look up resources on the **Resource inventory** page, you can choose the AWS Config timeline to view details about your CodeBuild project\. The details page for a resource provides information about the configuration, relationships, and number of changes made to that resource\. @@ -46,6 +46,6 @@ The blocks at the top of the page are collectively called the timeline\. The tim 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:** +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 diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md index 7464cfc..9ed9f28 100644 --- a/doc_source/how-to-run.md +++ b/doc_source/how-to-run.md @@ -1,32 +1,21 @@ -# Run AWS CodeBuild Directly +# Run AWS CodeBuild directly -To set up, run, and monitor builds directly with CodeBuild, you can use the CodeBuild console, AWS CLI, or AWS SDK\. +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 CodeBuild](how-to-create-pipeline.md)\. +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)\. **Topics** + [Prerequisites](#how-to-run-prerequisites) -+ [Run AWS CodeBuild Directly \(Console\)](#how-to-run-console) -+ [Run AWS CodeBuild Directly \(AWS CLI\)](#how-to-run-cli) ++ [Run AWS CodeBuild directly](#how-to-run-console) ## Prerequisites -Answer the questions in [Plan a Build](planning.md)\. +Answer the questions in [Plan a build](planning.md)\. -## Run AWS CodeBuild Directly \(Console\) +## Run AWS CodeBuild directly -1. Create the build project\. For information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. +1. Create the build project\. To use the console, see [Create a build project \(console\)](create-project.md#create-project-console)\. To use the AWS CLI, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. -1. Run the build\. For information, see [Run a Build \(Console\)](run-build.md#run-build-console)\. +1. Run the build\. To use the console, see [Run a build \(console\)](run-build.md#run-build-console)\. To use the AWS CLI, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. -1. Get information about the build\. For information, see [View Build Details \(Console\)](view-build-details.md#view-build-details-console)\. - -## Run AWS CodeBuild Directly \(AWS CLI\) - -For more information about using the AWS CLI with CodeBuild, see the [Command Line Reference](cmd-ref.md)\. - -1. Create the build project\. For information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. - -1. Run the build\. For information, see [Run a Build \(AWS CLI\)](run-build.md#run-build-cli)\. - -1. Get information about the build\. For information, 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)\. \ No newline at end of file diff --git a/doc_source/index.md b/doc_source/index.md index f25b0dc..e8da06b 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,4 +1,4 @@ -# AWS CodeBuild User Guide +# AWS CodeBuild User guide ----- *****Copyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** @@ -14,138 +14,138 @@ Amazon's trademarks and trade dress may not be used in ----- ## Contents -+ [What Is AWS CodeBuild?](welcome.md) - + [AWS CodeBuild Concepts](concepts.md) -+ [Getting Started with CodeBuild](getting-started-overview.md) - + [Getting Started with CodeBuild in 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 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: Clean Up](getting-started-clean-up-console.md) - + [Wrapping Up](getting-started-next-steps-console.md) - + [Getting Started with 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 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: Clean Up](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) - + [Using Access Tokens with Your Source Provider in CodeBuild](sample-access-tokens.md) - + [Amazon ECR Sample for CodeBuild](sample-ecr.md) - + [Runtime Versions in Buildspec File Sample for CodeBuild](sample-runtime-versions.md) - + [Private Registry with AWS Secrets Manager Sample for CodeBuild](sample-private-registry.md) - + [Create a Test Report in CodeBuild Using the AWS CLI Sample](sample-test-report-cli.md) - + [Docker Sample for CodeBuild](sample-docker.md) - + [GitHub Enterprise Sample for CodeBuild](sample-github-enterprise.md) - + [GitHub Pull Request and Webhook Filter Sample for CodeBuild](sample-github-pull-request.md) - + [Bitbucket Pull Request and Webhook Filter Sample for CodeBuild](sample-bitbucket-pull-request.md) - + [Use AWS Config with AWS CodeBuild Sample](how-to-integrate-config.md) - + [Build Badges Sample with CodeBuild](sample-build-badges.md) - + [Build Notifications Sample for CodeBuild](sample-build-notifications.md) - + [Docker in Custom Image Sample for CodeBuild](sample-docker-custom-image.md) - + [Amazon Elastic File System Sample for CodeBuild](sample-efs.md) - + [Multiple Input Sources and Output Artifacts Sample](sample-multi-in-out.md) - + [CodePipeline Integration with CodeBuild and Multiple Input Sources and Output Artifacts Sample](sample-pipeline-multi-input-output.md) - + [Using Semantic Versioning to Name Build Artifacts Sample](sample-buildspec-artifact-naming.md) - + [Create a Static Website with Build Output Hosted in an Amazon S3 Bucket](sample-disable-artifact-encryption.md) - + [CodeDeploy Sample for CodeBuild](sample-codedeploy.md) - + [AWS Lambda Sample for CodeBuild](sample-lambda.md) - + [AWS Elastic Beanstalk Sample for AWS CodeBuild](sample-elastic-beanstalk.md) - + [Source Version Sample with CodeBuild](sample-source-version.md) -+ [Plan a Build for AWS CodeBuild](planning.md) - + [Build Specification Reference for CodeBuild](build-spec-ref.md) - + [Build Environment Reference for CodeBuild](build-env-ref.md) - + [Docker Images Provided by CodeBuild](build-env-ref-available.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 CodeBuild Agent](use-codebuild-agent.md) -+ [Run AWS CodeBuild Directly](how-to-run.md) -+ [Use 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 CodeBuild with a Proxy Server](use-proxy-server.md) -+ [Use CodePipeline with CodeBuild to Test Code and Run Builds](how-to-create-pipeline.md) ++ [What is AWS CodeBuild?](welcome.md) + + [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 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) + + [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 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) + + [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 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) + + [Create a test report in CodeBuild using the AWS CLI sample](sample-test-report-cli.md) + + [Docker in custom image sample for CodeBuild](sample-docker-custom-image.md) + + [Docker sample for CodeBuild](sample-docker.md) + + [GitHub Enterprise sample for CodeBuild](sample-github-enterprise.md) + + [GitHub pull request and webhook filter sample for CodeBuild](sample-github-pull-request.md) + + [Create a static website with build output hosted in an S3 bucket](sample-disable-artifact-encryption.md) + + [Runtime versions in buildspec file sample for CodeBuild](sample-runtime-versions.md) + + [Source version sample with AWS CodeBuild](sample-source-version.md) + + [Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md) + + [Multiple input sources and output artifacts sample](sample-multi-in-out.md) + + [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) + + [Build environment reference for AWS CodeBuild](build-env-ref.md) + + [Docker images provided by CodeBuild](build-env-ref-available.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) ++ [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 CodeBuild](builds-projects-and-builds.md) - + [Working with Build Projects](working-with-build-projects.md) - + [Create a Build Project in CodeBuild](create-project.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) + [Create a Notification Rule](notification-rule-create.md) - + [View a List of Build Project Names in CodeBuild](view-project-list.md) - + [View a Build Project's Details in CodeBuild](view-project-details.md) - + [Build Caching in CodeBuild](build-caching.md) - + [Create CodeBuild Triggers](trigger-create.md) - + [Edit CodeBuild Triggers](triggers-edit.md) - + [Change a Build Project's Settings in CodeBuild](change-project.md) - + [Delete a Build Project in AWS CodeBuild](delete-project.md) - + [Working with Shared Projects](project-sharing.md) - + [Working with Builds in CodeBuild](builds-working.md) - + [Run a Build in CodeBuild](run-build.md) - + [View Build Details in CodeBuild](view-build-details.md) - + [View a List of Build IDs in CodeBuild](view-build-list.md) - + [View a List of Build IDs for a Build Project in CodeBuild](view-builds-for-project.md) - + [Stop a Build in CodeBuild](stop-build.md) - + [Delete Builds in CodeBuild](delete-builds.md) -+ [Working with Test Reporting in CodeBuild](test-reporting.md) - + [Create a Test Report](report-create.md) - + [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 (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) - + [Update a Report Group (CLI)](update-report-group-cli.md) - + [Specify Test Files](report-group-test-cases.md) - + [Specify Test Commands](report-group-test-case-commands.md) - + [Report Group Naming](test-report-group-naming.md) - + [Working with Shared Report Groups](report-groups-sharing.md) - + [Working with Reports](test-report.md) - + [Working with Test Report Permissions](test-permissions.md) - + [View Test Reports](test-view-reports.md) + + [View a list of build project names in AWS CodeBuild](view-project-list.md) + + [View a build project's details in AWS CodeBuild](view-project-details.md) + + [Build caching in AWS CodeBuild](build-caching.md) + + [Create AWS CodeBuild triggers](trigger-create.md) + + [Edit AWS CodeBuild triggers](triggers-edit.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) + + [Working with builds in AWS CodeBuild](builds-working.md) + + [Run a build in AWS CodeBuild](run-build.md) + + [View build details in AWS CodeBuild](view-build-details.md) + + [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) + + [Delete builds in AWS CodeBuild](delete-builds.md) ++ [Working with test reporting in AWS CodeBuild](test-reporting.md) + + [Create a test report](report-create.md) + + [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 (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) + + [Update a report group (CLI)](update-report-group-cli.md) + + [Specify test files](report-group-test-cases.md) + + [Specify test commands](report-group-test-case-commands.md) + + [Report group naming](test-report-group-naming.md) + + [Working with shared report groups](report-groups-sharing.md) + + [Working with reports](test-report.md) + + [Working with test report permissions](test-permissions.md) + + [View test reports](test-view-reports.md) + [Security in AWS CodeBuild](security.md) - + [Data Protection in AWS CodeBuild](data-protection.md) - + [Data Encryption](security-encryption.md) - + [Key Management](security-key-management.md) - + [Traffic Privacy](security-traffic-privacy.md) - + [Identity and Access Management in CodeBuild](auth-and-access-control.md) - + [Overview of Managing Access Permissions to Your CodeBuild Resources](auth-and-access-control-iam-access-control-identity-based.md) - + [Using Identity-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) - + [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md) - + [Using Tags to Control Access to CodeBuild Resources](auth-and-access-control-using-tags.md) - + [Viewing Resources in the Console](console-resources.md) - + [Logging and Monitoring in AWS CodeBuild](security-incident-response.md) - + [Logging CodeBuild API Calls with AWS CloudTrail](cloudtrail.md) + + [Data protection in AWS CodeBuild](data-protection.md) + + [Data encryption](security-encryption.md) + + [Key management](security-key-management.md) + + [Traffic privacy](security-traffic-privacy.md) + + [Identity and access management in AWS CodeBuild](auth-and-access-control.md) + + [Overview of managing access permissions to your AWS CodeBuild resources](auth-and-access-control-iam-access-control-identity-based.md) + + [Using identity-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) + + [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md) + + [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md) + + [Viewing resources in the console](console-resources.md) + + [Logging and monitoring in AWS CodeBuild](security-incident-response.md) + + [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md) + [Monitoring AWS CodeBuild](monitoring-builds.md) - + [Monitoring Builds with CloudWatch Metrics](monitoring-metrics.md) - + [Monitoring Builds with CloudWatch Alarms](monitoring-alarms.md) - + [Compliance Validation for AWS CodeBuild](codebuild-compliance-validation.md) + + [Monitoring builds with CloudWatch metrics](monitoring-metrics.md) + + [Monitoring builds with CloudWatch alarms](monitoring-alarms.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) -+ [Advanced Topics](advanced-topics.md) - + [Advanced Setup](setting-up.md) - + [Command Line Reference for CodeBuild](cmd-ref.md) - + [AWS SDKs and Tools Reference for CodeBuild](sdk-ref.md) - + [Specify the CodeBuild Endpoint](endpoint-specify.md) -+ [Troubleshooting CodeBuild](troubleshooting.md) -+ [Limits for CodeBuild](limits.md) -+ [CodeBuild for Windows—Third Party Notices](notice.md) -+ [AWS CodeBuild User Guide Document History](history.md) -+ [AWS Glossary](glossary.md) \ No newline at end of file + + [Infrastructure security in AWS CodeBuild](infrastructure-security.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) ++ [Troubleshooting AWS CodeBuild](troubleshooting.md) ++ [Quotas for AWS CodeBuild](limits.md) ++ [Third party notices for AWS CodeBuild for Windows](notice.md) ++ [AWS CodeBuild User Guide document history](history.md) ++ [AWS glossary](glossary.md) \ No newline at end of file diff --git a/doc_source/infrastructure-security.md b/doc_source/infrastructure-security.md index af9d3c1..78e1e61 100644 --- a/doc_source/infrastructure-security.md +++ b/doc_source/infrastructure-security.md @@ -1,4 +1,4 @@ -# Infrastructure Security in AWS CodeBuild +# Infrastructure security in AWS CodeBuild As a managed service, AWS CodeBuild is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of Security Processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper\. diff --git a/doc_source/jenkins-plugin.md b/doc_source/jenkins-plugin.md index a2a2c58..73b58aa 100644 --- a/doc_source/jenkins-plugin.md +++ b/doc_source/jenkins-plugin.md @@ -1,22 +1,22 @@ # Use AWS CodeBuild with Jenkins -The Jenkins plugin for AWS CodeBuild enables you to integrate CodeBuild with your Jenkins build jobs\. Instead of sending your build jobs to Jenkins build nodes, you use the plugin to send your build jobs to CodeBuild\. This eliminates the need for you to provision, configure, and manage Jenkins build nodes\. +You can use the Jenkins plugin for AWS CodeBuild to integrate CodeBuild with your Jenkins build jobs\. Instead of sending your build jobs to Jenkins build nodes, you use the plugin to send your build jobs to CodeBuild\. This eliminates the need for you to provision, configure, and manage Jenkins build nodes\. -## Setting Up Jenkins +## Setting up Jenkins -For information about setting up Jenkins with the AWS CodeBuild plugin, see the [ Simplify Your Jenkins Builds with CodeBuild](https://aws.amazon.com/blogs/devops/simplify-your-jenkins-builds-with-aws-codebuild/) blog post on the AWS DevOps Blog\. You can download the CodeBuild Jenkins from [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. +For information about setting up Jenkins with the AWS CodeBuild plugin, see the [ Simplify Your Jenkins Builds with CodeBuild](https://aws.amazon.com/blogs/devops/simplify-your-jenkins-builds-with-aws-codebuild/) blog post on the AWS DevOps Blog\. You can download the CodeBuild Jenkins plugin from [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. -## Installing the Plugin +## Installing the plugin -If you already have a Jenkins set up and would like to only install the AWS CodeBuild plugin, then on your Jenkins instance, in the Plugin Manager, search for "CodeBuild Plugin for Jenkins" \. +If you already have a Jenkins server set up and would like to only install the AWS CodeBuild plugin, on your Jenkins instance, in the Plugin Manager, search for **CodeBuild Plugin for Jenkins**\. -## Using the Plugin +## Using the plugin -**To use AWS CodeBuild with sources from outside of an Amazon VPC** +**To use AWS CodeBuild with sources from outside of a VPC** -1. Create a project in the CodeBuild console\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. - + Choose the region where you want to run the build\. - + \(Optional\) Set the Amazon VPC configuration to allow the CodeBuild build container to access resources in your Amazon VPC\. +1. Create a project in the CodeBuild console\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console)\. + + Choose the AWS Region where you want to run the build\. + + \(Optional\) Set the Amazon VPC configuration to allow the CodeBuild build container to access resources in your VPC\. + Write down the name of your project\. You need it in step 3\. + \(Optional\) If your source repository is not natively supported by CodeBuild, you can set Amazon S3 as the input source type for your project\. @@ -73,7 +73,7 @@ If you already have a Jenkins set up and would like to only install the AWS Code + Choose **Use Jenkins source**\. + Save the configuration and run a build from Jenkins\. -**To use the AWS CodeBuild plugin with the Jenkins Pipeline plugin** +**To use the AWS CodeBuild plugin with the Jenkins pipeline plugin** + On your Jenkins pipeline project page, use the snippet generator to generate a pipeline script that adds CodeBuild as a step in your pipeline\. It should generate a script similar to this: ``` diff --git a/doc_source/limits.md b/doc_source/limits.md index cabe4cf..b7ae588 100644 --- a/doc_source/limits.md +++ b/doc_source/limits.md @@ -1,47 +1,47 @@ -# Limits for CodeBuild +# Quotas for AWS CodeBuild -The following tables list the current limits in CodeBuild\. These limits are for each supported AWS Region for each AWS account, unless otherwise specified\. +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 Project Limits +## Build projects **** -| Resource | Default limit | +| Resource | Default | | --- | --- | -| Maximum number of build projects | 5,000 | -| Length of a build project name | 2 to 255 characters, inclusive | +| Allowed characters in a build project description | Any | | 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 | -| Allowed characters in a build project description | Any | -| Maximum number of build projects you can request information about at any one time by using the AWS CLI or AWS SDKs | 100 | +| 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 subnets you can add under VPC configuration | 1 to 16 | | Number of security groups you can add under VPC configuration | 1 to 5 | -| Maximum number of reports you can add to a project | 5 | +| Number of subnets you can add under VPC configuration | 1 to 16 | -## Build Limits +## Builds **** -| Resource | Default limit | +| Resource | Default | | --- | --- | -| Maximum number of concurrent running builds \* | 60 | -| Maximum number of builds you can request information about at any one time by using the AWS CLI or AWS SDKs | 100 | +| 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\) | -| Maximum time the history of a build can be accessed | 1 year | -\* Limits 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 limit can be between 1 and 5\. To request a higher concurrent build limit or if you get a "Cannot have more than X active builds for the account" error, contact AWS Support\. +\* 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\. -## Report Limits +## Reports **** -| Resource | Default limit | +| Resource | Default | | --- | --- | -| Maximum number of report groups per AWS account | 1000 | | Maximum duration a test report is available after it is created | 30 days | +| Maximum number of report groups per AWS account | 1000 | | Maximum number of test cases per report | 500 | \ No newline at end of file diff --git a/doc_source/monitoring-alarms.md b/doc_source/monitoring-alarms.md index 9ef6a66..3a3a6c6 100644 --- a/doc_source/monitoring-alarms.md +++ b/doc_source/monitoring-alarms.md @@ -1,4 +1,4 @@ -# Monitoring Builds with CloudWatch Alarms +# Monitoring builds with CloudWatch alarms You can create a CloudWatch alarm for your builds\. An alarm watches a single metric over a period of time that you specify and performs one or more actions based on the value of the metric relative to a specified threshold over a number of time periods\. Using native CloudWatch alarm functionality, you can specify any of the actions supported by CloudWatch when a threshold is exceeded\. For example, you can specify that an Amazon SNS notification is sent when more than three builds in your account fail within fifteen minutes\. @@ -18,7 +18,7 @@ 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 **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)\. 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)\. +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/) diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index 9bce333..cd7c906 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.md @@ -12,7 +12,7 @@ Metrics displayed in the CodeBuild console are always from the past three days\. You can use the CloudWatch console to view CodeBuild metrics over different durations\. - For information about creating CloudWatch metrics for CodeBuild, see [Monitoring Builds with CloudWatch Metrics](monitoring-metrics.md)\. + For more information, see [Monitoring builds with CloudWatch metrics](monitoring-metrics.md)\. ## CodeBuild CloudWatch Metrics @@ -38,14 +38,14 @@ | `SucceededBuilds` | Measures the number of successful builds\. Units: Count Valid CloudWatch statistics: Sum | | UploadArtifactsDuration | Measures the duration of the build's UPLOAD\_ARTIFACTS phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -## CodeBuild CloudWatch Dimensions +## CodeBuild CloudWatch dimensions `ProjectName` is the only AWS CodeBuild metrics dimension\. If it is specified, then the metrics are for that project\. If it is not specified, then the metrics are for the current AWS account\. -## CodeBuild CloudWatch Alarms +## CodeBuild CloudWatch alarms You can use the CloudWatch console to create alarms based on CodeBuild metrics so you can react if something goes wrong with your builds\. The two metrics that are most useful with alarms are: + `FailedBuild`\. You can create an alarm that is triggered when a certain number of failed builds are detected within a predetermined number of seconds\. In CloudWatch you specify the number of seconds and how many faild builds trigger an alarm\. + `Duration`\. You can create an alarm that is triggered when a build takes longer than expected\. You specify how many seconds must elapse after a build is started and before a build is completed before the alarm is triggered\. - For information about how to create alarms for CodeBuild metrics, see [Monitoring Builds with CloudWatch Alarms](monitoring-alarms.md)\. For more information about alarms, see [ Creating Amazon CloudWatch Alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html)\. \ No newline at end of file + For information about how to create alarms for CodeBuild metrics, see [Monitoring builds with CloudWatch alarms](monitoring-alarms.md)\. For more information about alarms, see [Creating Amazon CloudWatch Alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/monitoring-metrics.md b/doc_source/monitoring-metrics.md index 99da9b2..7496e8f 100644 --- a/doc_source/monitoring-metrics.md +++ b/doc_source/monitoring-metrics.md @@ -1,10 +1,10 @@ -# Monitoring Builds with CloudWatch Metrics +# Monitoring builds with CloudWatch metrics CodeBuild monitors functions on your behalf and reports metrics through Amazon CloudWatch\. These metrics include the number of total builds, failed builds, successful builds, and the duration of builds\. You can use the CodeBuild console or the CloudWatch console to monitor metrics for CodeBuild\. The following procedures show you how to access metrics\. -## Access Build Metrics \(CodeBuild Console\) +## Access build metrics \(CodeBuild console\) The graphs in the CodeBuild console show three days of metrics\. You cannot customize the metrics or the graphs used to display them\. Use the Amazon CloudWatch console to view your build metrics if you want to edit them\. @@ -24,7 +24,7 @@ The graphs in the CodeBuild console show three days of metrics\. You cannot cust 1. Choose the **Metrics** tab\. -## Access Build Metrics \(Amazon CloudWatch Console\) +## Access build metrics \(Amazon CloudWatch console\) You can customize the metrics and the graphs used to display them\. diff --git a/doc_source/notice.md b/doc_source/notice.md index 406dd52..fa6b90b 100644 --- a/doc_source/notice.md +++ b/doc_source/notice.md @@ -1,21 +1,21 @@ -# CodeBuild for Windows—Third Party Notices +# Third party notices for AWS CodeBuild for Windows -When you use CodeBuild for Windows builds, you have the option to use some third party packages/modules to enable your built application to run on Microsoft Windows operating systems and to interoperate with some third party products\. The following list contains the applicable third\-party legal terms that govern your use of the specified third\-party packages/modules\. +When you use CodeBuild for Windows builds, you have the option to use some third party packages and modules to enable your built application to run on Microsoft Windows operating systems and to interoperate with some third party products\. The following list contains the applicable third\-party legal terms that govern your use of the specified third\-party packages and modules\. **Topics** -+ [1\) Base Docker Image—windowsservercore](#base-docker-image) -+ [2\) windows\-base Docker Image—Choco](#3-windows-base-docker-image) -+ [3\) windows\-base Docker Image—git \-\-version 2\.16\.2](#4-windows-base-docker-image-2-16-2) -+ [4\) windows\-base Docker Image—microsoft\-build\-tools \-\-version 15\.0\.26320\.2](#5-windows-base-docker-image-15-x) -+ [5\) windows\-base Docker Image—nuget\.commandline \-\-version 4\.5\.1](#6-windows-base-docker-image-4-5-1) -+ [7\) windows\-base Docker Image—netfx\-4\.6\.2\-devpack](#7-windows-base-docker-image-4-6-2) -+ [8\) windows\-base Docker Image—visualfsharptools, v 4\.0](#8-windows-base-docker-image-visualfsharptools) -+ [9\) windows\-base Docker Image—netfx\-pcl\-reference\-assemblies\-4\.6](#9-windows-base-docker-image) -+ [10\) windows\-base Docker Image—visualcppbuildtools v 14\.0\.25420\.1](#10-windows-base-docker-image) -+ [11\) windows\-base Docker Image—microsoft\-windows\-netfx3\-ondemand\-package\.cab](#11-windows-base-docker-image) -+ [12\) windows\-base Docker Image—dotnet\-sdk](#12-windows-base-docker-image) - -## 1\) Base Docker Image—windowsservercore ++ [1\) base Docker image—windowsservercore](#base-docker-image) ++ [2\) windows\-base Docker image—choco](#3-windows-base-docker-image) ++ [3\) windows\-base Docker image—git \-\-version 2\.16\.2](#4-windows-base-docker-image-2-16-2) ++ [4\) windows\-base Docker image—microsoft\-build\-tools \-\-version 15\.0\.26320\.2](#5-windows-base-docker-image-15-x) ++ [5\) windows\-base Docker image—nuget\.commandline \-\-version 4\.5\.1](#6-windows-base-docker-image-4-5-1) ++ [7\) windows\-base Docker image—netfx\-4\.6\.2\-devpack](#7-windows-base-docker-image-4-6-2) ++ [8\) windows\-base Docker image—visualfsharptools, v 4\.0](#8-windows-base-docker-image-visualfsharptools) ++ [9\) windows\-base Docker image—netfx\-pcl\-reference\-assemblies\-4\.6](#9-windows-base-docker-image) ++ [10\) windows\-base Docker image—visualcppbuildtools v 14\.0\.25420\.1](#10-windows-base-docker-image) ++ [11\) windows\-base Docker image—microsoft\-windows\-netfx3\-ondemand\-package\.cab](#11-windows-base-docker-image) ++ [12\) windows\-base Docker image—dotnet\-sdk](#12-windows-base-docker-image) + +## 1\) base Docker image—windowsservercore \(license terms available at: [https://hub\.docker\.com/r/microsoft/windowsservercore/\)](https://hub.docker.com/r/microsoft/windowsservercore/) @@ -43,9 +43,9 @@ By using this Supplement, you accept these terms\. If you do not accept them, do As part of the Supplemental License Terms for this Container OS Image for Windows containers, you are also subject to the underlying Windows Server host software license terms, which are located at: [https://www\.microsoft\.com/en\-us/useterms\.](https://www.microsoft.com/en-us/useterms) -## 2\) windows\-base Docker Image—Choco +## 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/chocolatey\.org/blob/master/LICENSE\.txt](https://github.com/chocolatey/chocolatey.org/blob/master/LICENSE.txt)\) Copyright 2011 \- Present RealDimensions Software, LLC @@ -55,13 +55,13 @@ Licensed under the Apache License, version 2\.0 \(the "License"\); you may not u Unless required by applicable law or as agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\. See the License for the specific language governing permissions and limitations under the License\. -## 3\) windows\-base Docker Image—git \-\-version 2\.16\.2 +## 3\) windows\-base Docker image—git \-\-version 2\.16\.2 \(license terms available at: [https://chocolatey\.org/packages/git/2\.16\.2](https://chocolatey.org/packages/git/2.16.2)\) -**Licensed under GNU General Public License, version 2, available at**: [https://www\.gnu\.org/licenses/old\-licenses/gpl\-2\.0\.html](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) +Licensed under GNU General Public License, version 2, available at: [https://www\.gnu\.org/licenses/old\-licenses/gpl\-2\.0\.html](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)\. -## 4\) windows\-base Docker Image—microsoft\-build\-tools \-\-version 15\.0\.26320\.2 +## 4\) windows\-base Docker image—microsoft\-build\-tools \-\-version 15\.0\.26320\.2 \(license terms available at: [https://www\.visualstudio\.com/license\-terms/mt171552/](https://www.visualstudio.com/license-terms/mt171552/)\) @@ -133,7 +133,7 @@ IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW\. EULA ID: VS2015\_Update3\_ShellsRedist\_ -## 5\) windows\-base Docker Image—nuget\.commandline \-\-version 4\.5\.1 +## 5\) windows\-base Docker image—nuget\.commandline \-\-version 4\.5\.1 \(license terms available at: [https://github\.com/NuGet/Home/blob/dev/LICENSE\.txt](https://github.com/NuGet/Home/blob/dev/LICENSE.txt)\) @@ -145,7 +145,7 @@ Licensed under the Apache License, version 2\.0 \(the "License"\); you may not u Unless required by applicable law or as agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\. See the License for the specific language governing permissions and limitations under the License\. -## 7\) windows\-base Docker Image—netfx\-4\.6\.2\-devpack +## 7\) windows\-base Docker image—netfx\-4\.6\.2\-devpack **MICROSOFT SOFTWARE SUPPLEMENTAL LICENSE TERMS** @@ -188,7 +188,7 @@ The following license terms describe additional use terms for this supplement\. 1. **SUPPORT SERVICES FOR SUPPLEMENT**\. Microsoft provides support services for this software as described at [www\.support\.microsoft\.com/common/international\.aspx](http://www.support.microsoft.com/common/international.aspx)\. -## 8\) windows\-base Docker Image—visualfsharptools, v 4\.0 +## 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)\) @@ -200,7 +200,7 @@ Licensed under the Apache License, version 2\.0 \(the "License"\); you may not u Unless required by applicable law or as agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\. See the License for the specific language governing permissions and limitations under the License\. -## 9\) windows\-base Docker Image—netfx\-pcl\-reference\-assemblies\-4\.6 +## 9\) windows\-base Docker image—netfx\-pcl\-reference\-assemblies\-4\.6 **MICROSOFT SOFTWARE LICENSE TERMS** @@ -282,7 +282,7 @@ for this software, unless other terms accompany those items\. If so, those terms It also applies even if Microsoft knew or should have known about the possibility of the damages\. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages\. -## 10\) windows\-base Docker Image—visualcppbuildtools v 14\.0\.25420\.1 +## 10\) windows\-base Docker image—visualcppbuildtools v 14\.0\.25420\.1 \(license terms available at: [https://www\.visualstudio\.com/license\-terms/mt644918/](https://www.visualstudio.com/license-terms/mt644918/)\) @@ -350,7 +350,7 @@ These license terms are an agreement between Microsoft Corporation \(or based on It also applies even if Microsoft knew or should have known about the possibility of the damages\. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages\. -## 11\) windows\-base Docker Image—microsoft\-windows\-netfx3\-ondemand\-package\.cab +## 11\) windows\-base Docker image—microsoft\-windows\-netfx3\-ondemand\-package\.cab **MICROSOFT SOFTWARE SUPPLEMENTAL LICENSE TERMS** @@ -374,7 +374,7 @@ The following license terms describe additional use terms for this supplement\. Notwithstanding any other agreement you may have with Microsoft, if you disclose such benchmark test results, Microsoft shall have the right to disclose the results of benchmark tests it conducts of your products that compete with the applicable \.NET Component, provided it complies with the same conditions set forth at [http://go\.microsoft\.com/fwlink/?LinkID=66406](http://go.microsoft.com/fwlink/?LinkID=66406)\. -## 12\) windows\-base Docker Image—dotnet\-sdk +## 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)\) diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md index 929aecf..abd285a 100644 --- a/doc_source/notification-rule-create.md +++ b/doc_source/notification-rule-create.md @@ -18,32 +18,31 @@ You can use the console or the AWS CLI to create notification rules for AWS Code For more information, see [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. -1. In **Events that trigger notifications**, select the events for which you want to send notifications\. -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/notification-rule-create.html) +1. In **Events that trigger notifications**, select the events for which you want to send notifications\. For more information, see [ Events for Notification Rules on Build Projects](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/concepts.html#events-ref-buildproject)\. -1. In **Targets**, choose **Create SNS topic**\. +1. In **Targets**, do one of the following: + + If you have already configured a resource to use with notifications, in **Choose target type**, choose either **AWS Chatbot \(Slack\)** or **SNS topic**\. In **Choose target**, choose the name of the client \(for a Slack client configured in AWS Chatbot\) or the Amazon Resource Name \(ARN\) of the Amazon SNS topic \(for Amazon SNS topics already configured with the policy required for notifications\)\. + + If you have not configured a resource to use with notifications, choose **Create target**, and then choose **SNS topic**\. Provide a name for the topic after **codestar\-notifications\-**, and then choose **Create**\. **Note** -When you create the topic, the policy that allows CodeBuild to publish events to the topic is applied for you\. Using a topic created specifically for CodeBuild notifications also helps ensure that you only add users to the subscription list for that topic that you want to see notifications about this build project\. - - After the **codestar\-notifications\-** prefix,enter a name for the topic, and then choose **Submit**\. -**Note** -If you want to use an existing Amazon SNS topic instead of creating a new one, in **Targets**, choose its ARN\. Make sure the topic has the appropriate access policy and that the subscriber list contains only those users who are allowed to see information about the build project\. For more information, see [Configure Existing Amazon SNS Topics for Notifications](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/set-up-sns.html) and [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. +If you create the Amazon SNS topic as part of creating the notification rule, the policy that allows the notifications feature to publish events to the topic is applied for you\. Using a topic created for notification rules helps ensure that you subscribe only those users that you want to receive notifications about this resource\. +You cannot create an AWS Chatbot client as part of creating a notification rule\. If you choose AWS Chatbot \(Slack\), you will see a button directing you to configure a client in AWS Chatbot\. Choosing that option opens the AWS Chatbot console\. For more information, see [ Configure Integrations Between Notifications and AWS Chatbot](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/notifications-chatbot.html)\. +If you want to use an existing Amazon SNS topic as a target, you must add the required policy for AWS CodeStar Notifications in addition to any other policies that might exist for that topic\. For more information, see [Configure Amazon SNS Topics for Notifications ](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/set-up-sns.html) and [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. 1. To finish creating the rule, choose **Submit**\. -1. You must subscribe users to the Amazon SNS topic for the rule before they can receive notifications\. For more information, see [Subscribe Users to Amazon SNS Topics That Are Targets](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/subscribe-users-sns.html)\. You can also set up integration between notifications and AWS Chatbot to send notifications to Amazon Chime chatrooms or Slack channels\. For more information, see [Configure Integration Between Notifications and AWS Chatbot](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/notifications-chatbot.html)\. +1. You must subscribe users to the Amazon SNS topic for the rule before they can receive notifications\. For more information, see [Subscribe Users to Amazon SNS Topics That Are Targets](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/subscribe-users-sns.html)\. You can also set up integration between notifications and AWS Chatbot to send notifications to Amazon Chime chatrooms\. For more information, see [Configure Integration Between Notifications and AWS Chatbot](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/notifications-chatbot.html)\. # To create a notification rule \(AWS CLI\) 1. At a terminal or command prompt, run the create\-notification rule command to generate the JSON skeleton: ``` - aws codestar-notifications create-notification-rule --generate-cli-skeleton > rule.json + aws codestarnotifications create-notification-rule --generate-cli-skeleton > rule.json ``` You can name the file anything you want\. In this example, the file is named *rule\.json*\. -1. Open the JSON file in a plain\-text editor and edit it to include the resource, event types, and Amazon SNS target you want for the rule\. The following example shows a notification rule named **MyNotificationRule** for a build project named *MyBuildProject* in an AWS acccount with the ID *123456789012*\. Notifications are sent with the full detail type to an Amazon SNS topic named *codestar\-notifications\-MyNotificationTopic* when builds are successful: +1. Open the JSON file in a plain\-text editor and edit it to include the resource, event types, and target you want for the rule\. The following example shows a notification rule named **MyNotificationRule** for a build project named *MyBuildProject* in an AWS acccount with the ID *123456789012*\. Notifications are sent with the full detail type to an Amazon SNS topic named *codestar\-notifications\-MyNotificationTopic* when builds are successful: ``` { @@ -68,7 +67,7 @@ If you want to use an existing Amazon SNS topic instead of creating a new one, i 1. Using the file you just edited, at the terminal or command line, run the create\-notification\-rule command again to create the notification rule: ``` - aws codestar-notifications create-notification-rule --cli-input-json file://rule.json + aws codestarnotifications create-notification-rule --cli-input-json file://rule.json ``` 1. If successful, the command returns the ARN of the notification rule, similar to the following: diff --git a/doc_source/planning.md b/doc_source/planning.md index 7692ae2..20361d3 100644 --- a/doc_source/planning.md +++ b/doc_source/planning.md @@ -1,21 +1,21 @@ -# Plan a Build for AWS CodeBuild +# Plan a build in AWS CodeBuild -Before you run your build with CodeBuild, you must answer these questions: +Before you use AWS CodeBuild, you must answer these questions: -1. **Where is the source code located?** CodeBuild currently supports building from the following source code repository providers\. The source code must contain a build specification \(buildspec\) file, or the buildspec must be declared as part of a build project definition\. A *build spec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. +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) -1. **Which build commands do you need to run and in what order?** By default, CodeBuild downloads the build input from the provider you specify and uploads the build output to the bucket you specify\. You use the buildspec to instruct how to turn the downloaded build input into the expected build output\. For more information, see the [Buildspec Reference](build-spec-ref.md)\. +1. **Which build commands do you need to run and in what order?** By default, CodeBuild downloads the build input from the provider you specify and uploads the build output to the bucket you specify\. You use the buildspec to instruct how to turn the downloaded build input into the expected build output\. For more information, see the [Buildspec reference](build-spec-ref.md)\. 1. **Which runtimes and tools do you need to run the build?** For example, are you building for Java, Ruby, Python, or Node\.js? Does the build need Maven or Ant or a compiler for Java, Ruby, or Python? Does the build need Git, the AWS CLI, or other tools? - CodeBuild runs builds in build environments that use Docker images\. These Docker images must be stored in a repository type supported by CodeBuild\. These include the CodeBuild Docker image repository, Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\)\. For more information about the CodeBuild Docker image repository, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. + CodeBuild runs builds in build environments that use Docker images\. These Docker images must be stored in a repository type supported by CodeBuild\. These include the CodeBuild Docker image repository, Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\)\. For more information about the CodeBuild Docker image repository, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. -1. **Do you need AWS resources that aren't provided automatically by CodeBuild? If so, which security policies will those resources need?** For example, you might need to modify the CodeBuild service role to allow CodeBuild to work with those resources\. +1. **Do you need AWS resources that aren't provided automatically by CodeBuild? If so, which security policies do those resources need?** For example, you might need to modify the CodeBuild service role to allow CodeBuild to work with those resources\. -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 CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. +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 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 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 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 diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index 51af290..0ea958a 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -1,21 +1,21 @@ -# Working with Shared Projects +# Working with shared projects -Project sharing allows project owners to share their CodeBuild projects with other AWS accounts or users\. In this model, the account that owns the project \(owner\) shares a project with other accounts \(consumers\)\. A consumer cannot edit or run a project\. +Project sharing allows project owners to share their AWS CodeBuild projects with other AWS accounts or users\. In this model, the account that owns the project \(owner\) shares a project with other accounts \(consumers\)\. A consumer cannot edit or run a project\. **Topics** -+ [Prerequisites for Sharing Projects](#project-sharing-prereqs) -+ [Prerequisites for Accessing Shared Projects Shared with You](#project-sharing-access-prereqs) -+ [Related Services](#project-sharing-related) -+ [Sharing a Project](#project-sharing-share) -+ [Unsharing a Shared Project](#project-sharing-unshare) -+ [Identifying a Shared Project](#project-sharing-identify) -+ [Shared Project Permissions](#project-sharing-perms) ++ [Prerequisites for sharing projects](#project-sharing-prereqs) ++ [Prerequisites for accessing shared projects shared with you](#project-sharing-access-prereqs) ++ [Related services](#project-sharing-related) ++ [Sharing a project](#project-sharing-share) ++ [Unsharing a shared project](#project-sharing-unshare) ++ [Identifying a shared project](#project-sharing-identify) ++ [Shared project permissions](#project-sharing-perms) -## Prerequisites for Sharing Projects +## Prerequisites for sharing projects To share a project, your AWS account must own it\. You cannot share a project that has been shared with you\. -## Prerequisites for Accessing Shared Projects Shared with You +## 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: @@ -31,17 +31,17 @@ To access a shared report group, a consumer's IAM role requires the `BatchGetPro } ``` - For more information, see [Using Identity\-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. + For more information, see [Using identity\-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. -## Related Services +## Related services Project sharing integrates with AWS Resource Access Manager \(AWS RAM\), a service that makes it possible for you to share your AWS resources with any AWS account or through AWS Organizations\. With AWS RAM, you share resources by creating a *resource share* that specifies the resources and the consumers to share them with\. Consumers can be individual AWS accounts, organizational units in AWS Organizations, or an entire organization in AWS Organizations\. For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*\. -## Sharing a Project +## Sharing a project -The consumer can use the AWS CLI but not the CodeBuild console to view the project and builds you've shared\. The consumer cannot edit or run the project\. +The consumer can use the AWS CLI but not the AWS CodeBuild console to view the project and builds you've shared\. The consumer cannot edit or run the project\. You can add a project to an existing resource share or you can create one in the [AWS RAM console](https://console.aws.amazon.com/ram)\. @@ -50,7 +50,7 @@ You can add a project to an existing resource share or you can create one in the To share a project with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. -You can use the CodeBuild console, AWS RAM console, or the AWS CLI to share a project that you own\. +You can use the AWS CodeBuild console, AWS RAM console, or the AWS CLI to share a project that you own\. **To share a project that you own \(CodeBuild console\)** @@ -91,7 +91,7 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference } ``` -1. Update `policy.json` with the project ARN and identifiers to share it with\. The following example grants read\-only access to the project with the ARN `arn:aws:codebuild:us-west-2:123456789012:project/my-project` to Alice and the root user for the AWS account identified by 123456789012\. +1. Update `policy.json` with the project ARN and identifiers to share it with\. The following example grants read\-only access to the root user for the AWS account identified by 123456789012\. ``` { @@ -100,7 +100,6 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference "Effect":"Allow", "Principal":{ "AWS": [ - "arn:aws:iam::123456789012:user/Alice", "123456789012" ] }, @@ -119,11 +118,11 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference aws codebuild put-resource-policy --resource-arn project-arn --policy file://policy.json ``` -## Unsharing a Shared Project +## Unsharing a shared project An unshared project, including its builds, can be accessed only by its owner\. If you unshare a project, any AWS account or user you previously shared it with cannot access the project or its builds\. -To unshare a shared project that you own, you must remove it from the resource share\. You can use the CodeBuild console, AWS RAM console, or AWS CLI to do this\. +To unshare a shared project that you own, you must remove it from the resource share\. You can use the AWS CodeBuild console, AWS RAM console, or AWS CLI to do this\. **To unshare a shared project that you own \(AWS RAM console\)** See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. @@ -139,19 +138,19 @@ Run the [delete\-resource\-policy](https://docs.aws.amazon.com/cli/latest/refere aws codebuild delete-resource-policy --resource-arn project-arn ``` -## Identifying a Shared Project +## Identifying a shared project Owners and consumers can use the AWS CLI to identify shared projects\. **To identify projects shared with your AWS account or user \(AWS CLI\)** Use the [list\-shared\-projects](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-shared-projects.html) command to return the projects that are shared with you\. -## Shared Project Permissions +## Shared project permissions -### Permissions for Owners +### Permissions for owners A project owner can edit the project and use it to run builds\. -### Permissions for Consumers +### Permissions for consumers A project consumer can view a project and its builds, but cannot edit a project or use it to run builds\. \ No newline at end of file diff --git a/doc_source/report-create.md b/doc_source/report-create.md index dfccf8e..045b515 100644 --- a/doc_source/report-create.md +++ b/doc_source/report-create.md @@ -1,4 +1,4 @@ -# Create a Test Report +# Create a test report | | @@ -9,16 +9,16 @@ **To create a test report** -1. Create a build project\. For information, see [Create a Build Project in 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. 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 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. 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)\. + 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)\. - 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. 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 CodeBuild](run-build.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 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 6b9535b..7f5b3b4 100644 --- a/doc_source/report-group-create.md +++ b/doc_source/report-group-create.md @@ -1,14 +1,14 @@ -# Create a Report Group +# Create a report group | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You can use the CodeBuild console, the AWS CLI, or a buildspec file to create a report group\. Your IAM role must have the permissions required to create a report group\. For more information, see [Working with Test Report Permissions](test-permissions.md)\. + You can use the AWS CodeBuild console, the AWS CLI, or a buildspec file to create a report group\. Your IAM role must have the permissions required to create a report group\. For more information, see [Working with test report permissions](test-permissions.md)\. **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 \(AWS CloudFormation\)](test-report-group-create-cfn.md) \ No newline at end of file ++ [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 \(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 83797ff..49e404e 100644 --- a/doc_source/report-group-export-settings.md +++ b/doc_source/report-group-export-settings.md @@ -1,4 +1,4 @@ -# Update a Report Group +# Update a report group | | @@ -11,4 +11,4 @@ + A customer master key \(CMK\) for Amazon S3 that is managed by the AWS Key Management Service\. + A CMK that you create and configure\. - For more information, see [Data Encryption](security-encryption.md)\. \ No newline at end of file + For more information, see [Data encryption](security-encryption.md)\. \ No newline at end of file diff --git a/doc_source/report-group-test-case-commands.md b/doc_source/report-group-test-case-commands.md index feccfb5..b6a7086 100644 --- a/doc_source/report-group-test-case-commands.md +++ b/doc_source/report-group-test-case-commands.md @@ -1,4 +1,4 @@ -# Specify Test Commands +# Specify test commands | | diff --git a/doc_source/report-group-test-cases.md b/doc_source/report-group-test-cases.md index 6e608aa..af85125 100644 --- a/doc_source/report-group-test-cases.md +++ b/doc_source/report-group-test-cases.md @@ -1,11 +1,11 @@ -# Specify Test Files +# Specify test files | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports Syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. + You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. The following is a sample `reports` section that specifies two report groups for a build project\. One is specified with its ARN, the other with a name\. The `files` section specifies the files that contain the test case results\. The optional `base-directory` section specifies the directory where the test case files are located\. The optional `discard-paths` section specifies whether paths to test result files uploaded to an S3 bucket are discarded\. diff --git a/doc_source/report-groups-sharing.md b/doc_source/report-groups-sharing.md index 7474119..d6dc552 100644 --- a/doc_source/report-groups-sharing.md +++ b/doc_source/report-groups-sharing.md @@ -1,21 +1,21 @@ -# Working with Shared Report Groups +# Working with shared report groups Report group sharing allows multiple AWS accounts or users to view a report group, its unexpired reports, and the test results of its reports\. In this model, the account that owns the report group \(owner\) shares a report group with other accounts \(consumers\)\. A consumer cannot edit a report group\. A report expires 30 days after it is created\. **Topics** -+ [Prerequisites for Sharing Report Groups](#report-groups-sharing-prereqs) -+ [Prerequisites for Accessing Report Groups Shared with You](#report-groups-sharing-access-prereqs) -+ [Related Services](#report-groups-sharing-related) -+ [Sharing a Report Group](#report-groups-sharing-share) -+ [Unsharing a Shared Report Group](#report-groups-sharing-unshare) -+ [Identifying a Shared Report Group](#report-groups-sharing-identify) -+ [Shared Report Group Permissions](#report-groups-sharing-perms) ++ [Prerequisites for sharing report groups](#report-groups-sharing-prereqs) ++ [Prerequisites for accessing report groups shared with you](#report-groups-sharing-access-prereqs) ++ [Related services](#report-groups-sharing-related) ++ [Sharing a report group](#report-groups-sharing-share) ++ [Unsharing a shared report group](#report-groups-sharing-unshare) ++ [Identifying a shared report group](#report-groups-sharing-identify) ++ [Shared report group permissions](#report-groups-sharing-perms) -## Prerequisites for Sharing Report Groups +## Prerequisites for sharing report groups To share a report group, your AWS account must own it\. You cannot share a report group that has been shared with you\. -## Prerequisites for Accessing Report Groups Shared with You +## Prerequisites for accessing report groups shared with you To access a shared report group, a consumer's IAM role requires the `BatchGetReportGroups` permission\. You can attach the following policy to their IAM role: @@ -31,15 +31,15 @@ To access a shared report group, a consumer's IAM role requires the `BatchGetRep } ``` - For more information, see [Using Identity\-Based Policies for CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. + For more information, see [Using identity\-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. -## Related Services +## Related services Report group sharing integrates with AWS Resource Access Manager \(AWS RAM\), a service that makes it possible for you to share your AWS resources with any AWS account or through AWS Organizations\. With AWS RAM, you share resources that you own by creating a *resource share* that specifies the resources and the consumers to share them with\. Consumers can be individual AWS accounts, organizational units in AWS Organizations, or an entire organization in AWS Organizations\. For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*\. -## Sharing a Report Group +## Sharing a report group When you share a report group, the consumer is granted read\-only access to the report group and its reports\. The consumer can use the AWS CLI to view the report group, its reports, and the test case results for each report\. The consumer cannot: + View a shared report group or its reports in the CodeBuild console\. @@ -119,7 +119,7 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference aws codebuild put-resource-policy --resource-arn report-group-arn --policy file://policy.json ``` -## Unsharing a Shared Report Group +## Unsharing a shared report group An unshared report group, including its reports and their test case results, can be accessed only by its owner\. If you unshare a report group, any AWS account or user you previously shared it with cannot access the report group, its reports, or the results of test cases in the reports\. @@ -139,7 +139,7 @@ Run the [delete\-resource\-policy](https://docs.aws.amazon.com/cli/latest/refere aws codebuild delete-resource-policy --resource-arn report-group-arn ``` -## Identifying a Shared Report Group +## Identifying a shared report group Owners and consumers can use the AWS CLI to identify shared report groups\. @@ -189,12 +189,12 @@ To identify and get information about a shared report group and its reports, use } ``` -## Shared Report Group Permissions +## Shared report group permissions -### Permissions for Owners +### Permissions for owners A report group owner can edit the report group and specify it in a project to run reports\. -### Permissions for Consumers +### Permissions for consumers A report group consumer can view a report group, its reports, and the test case results for its reports\. A consumer cannot edit a report group or its reports, and cannot use it to create reports\. \ No newline at end of file diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 5af4d49..4eb18c0 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -1,17 +1,17 @@ -# Run a Build in CodeBuild +# Run a build in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to run a build in CodeBuild\. **Topics** -+ [Run a Build \(Console\)](#run-build-console) -+ [Run a Build \(AWS CLI\)](#run-build-cli) -+ [Start Running Builds Automatically \(AWS CLI\)](#run-build-cli-auto-start) -+ [Stop Running Builds Automatically \(AWS CLI\)](#run-build-cli-auto-stop) -+ [Run a Build \(AWS SDKs\)](#run-build-sdks) ++ [Run a build \(console\)](#run-build-console) ++ [Run a build \(AWS CLI\)](#run-build-cli) ++ [Start running builds automatically \(AWS CLI\)](#run-build-cli-auto-start) ++ [Stop running builds automatically \(AWS CLI\)](#run-build-cli-auto-stop) ++ [Run a build \(AWS SDKs\)](#run-build-sdks) -## Run a Build \(Console\) +## 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 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 AWS CodePipeline with AWS 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)\. @@ -20,8 +20,8 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll + If you created a build project earlier, in the navigation pane, choose **Build projects**\. Choose the build project, and then choose **Start build**\. 1. On the **Start build** page, do one of the following: - + For Amazon S3, for the optional **Source version** value, type 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 you source code\. For more information, see [Source Version Sample with 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 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 you 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, 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.md#create-project-source-provider)\. @@ -47,22 +47,22 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + From **Certificate**, choose a different setting\. 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 its ARN \(for example, **arn:aws:s3:::my\-codebuild\-sample2/buildspec\.yml**\)\. + + 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\. 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)\. + + 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 Amazon S3 bucket for your output artifacts\. + + 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 Amazon S3 bucket individually \(not compressed\), choose **None**\. + + 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.md#create-project-console)\. + + 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.md#create-project-console)\. Under **Logs**, you can override your log settings by selecting or clearing **CloudWatch Logs** and **S3 logs**\. + If you enable **CloudWatch logs**: @@ -94,13 +94,13 @@ 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)\. + For detailed information about this build, see [View build details \(console\)](view-build-details.md#view-build-details-console)\. -## Run a Build \(AWS CLI\) +## 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)\. -For more information about using the AWS CLI with CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +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)\. +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: @@ -116,9 +116,9 @@ For more information about using the AWS CLI with CodeBuild, see the [Command Li 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 command with the `--project-name` option, replace *project\-name* 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 command with the `--project-name` option, replace *project\-name* 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 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 12 hours 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\-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: @@ -170,30 +170,30 @@ For more information about using the AWS CLI with CodeBuild, see the [Command Li + 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 *sourceVersion* is 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 *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. + The following placeholders are for `artifactsOveride`\. - + *type*: Optional string\. The build output artifact type that overrides for this build the one defined in the build project\. - + *location*: Optional string\. The build output artifact location that overrides for this build the one defined in the build project\. - + *path*: Optional string\. The build output artifact path that overrides for this build the one defined in the build project\. - + *namespaceType*: Optional string\. The build output artifact path type that overrides for this build the one defined in the build project\. - + *name*: Optional string\. The build output artifact name that overrides for this build the one defined in the build project\. - + *packaging*: Optional string\. The build output artifact packaging type that overrides for this build the one defined in the build project\. - + *buildspecOverride*: Optional string\. A build spec declaration that overrides for this build the one defined in the build project\. 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 S3 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)\. + + *type*: Optional\. The build output artifact type that overrides for this build the one defined in the build project\. + + *location*: Optional\. The build output artifact location that overrides for this build the one defined in the build project\. + + *path*: Optional\. The build output artifact path that overrides for this build the one defined in the build project\. + + *namespaceType*: Optional\. The build output artifact path type that overrides for this build the one defined in the build project\. + + *name*: Optional\. The build output artifact name that overrides for this build the one defined in the build project\. + + *packaging*: Optional\. The build output artifact packaging type that overrides for this build the one defined in the build project\. + + *buildspecOverride*: Optional\. A buildspec declaration that overrides for this build the one defined in the build project\. 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 S3 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)\. + The following placeholders are for `cacheOveride`\. - + *cacheOverride\-location*: Optional string\. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `location` is required in a `ProjectCache` object\. - + *cacheOverride\-type*: Optional string\. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `type` is required in a `ProjectCache` object\. - + *certificateOverride*: Optional string\. The name of a certificate for this build that overrides the one specified in the build project\. - + *environmentTypeOverride*: Optional string\. A container type for this build that overrides the one specified in the build project\. The current valid string is `LINUX_CONTAINER`\. + + *cacheOverride\-location*: Optional\. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `location` is required in a `ProjectCache` object\. + + *cacheOverride\-type*: Optional\. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `type` is required in a `ProjectCache` object\. + + *certificateOverride*: Optional\. The name of a certificate for this build that overrides the one specified in the build project\. + + *environmentTypeOverride*: Optional\. A container type for this build that overrides the one specified in the build project\. The current valid string is `LINUX_CONTAINER`\. + The following placeholders are for `environmentVariablesOveride`\. - + *environmentVariablesOverride\-name*: Optional string\. The name of an environment variable in the build project whose value you want to override for this build\. - + *environmentVariablesOverride\-type*: Optional string\. The type of environment variable in the build project whose value you want to override for this build\. - + *environmentVariablesValue*: Optional string\. The value of the environment variable defined in the build project that you want to override for this build\. - + *gitCloneDepthOverride*: Optional string\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. - + *imageOverride*: Optional string\. The name of an image for this build that overrides the one specified in the build project\. - + *idempotencyToken*: Optional string\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 12 hours after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. - + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TSL setting specified in the build project\. The insecure TSL setting determines whether to ignore TSL warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise\. + + *environmentVariablesOverride\-name*: Optional\. The name of an environment variable in the build project whose value you want to override for this build\. + + *environmentVariablesOverride\-type*: Optional\. The type of environment variable in the build project whose value you want to override for this build\. + + *environmentVariablesValue*: Optional\. The value of the environment variable defined in the build project that you want to override for this build\. + + *gitCloneDepthOverride*: Optional\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. + + *imageOverride*: Optional\. The name of an image for this build that overrides the one specified in the build project\. + + *idempotencyToken*: Optional\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 5 minutes after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. + + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project\. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise\. + *privilegedModeOverride*: Optional boolean\. If set to true, the build overrides privileged mode in the build project\. + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out\. Its minimum value is five minutes and its maximum value is 480 minutes \(eight hours\)\. + *reportBuildStatusOverride*: Optional boolean that 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, or Bitbucket, an invalidInputException is thrown\. - + *sourceAuthOverride*: Optional string\. An authorization type for this build that overrides the one defined in the build project\. This override applies only if the build project's source is BitBucket or GitHub\. + + *sourceAuthOverride*: Optional string\. An authorization type for this build that overrides the one defined in the build project\. This override applies only if the build project's source is Bitbucket or GitHub\. + *sourceLocationOverride*: Optional string\. A location that overrides for this build the source location for the one defined in the build project\. + *serviceRoleOverride*: Optional string\. The name of a service role for this build that overrides the one specified in the build project\. + *sourceTypeOverride*: Optional string\. A source input type for this build that overrides the source input defined in the build project\. Valid strings are `NO_SOURCE`, `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `S3`, `BITBUCKET`, and `GITHUB_ENTERPRISE`\. @@ -208,7 +208,7 @@ 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 file declaration takes lowest precedence\. - For information about valid values for these placeholders, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. For a list of the latest settings for a build project, see [View a Build Project's Details](view-project-details.md)\. + For information about valid values for these placeholders, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. For a list of the latest settings for a build project, see [View a build project's details](view-project-details.md)\. 1. Switch to the directory that contains the file you just saved, and run the `start-build` command again\. @@ -218,9 +218,9 @@ The value in the buildspec file declaration takes lowest precedence\. 1. If successful, data similar to that described in the [To run the build](getting-started-cli-run-build.md#getting-started-run-build-cli) procedure appears in the output\. -To work with detailed information about this build, make a note of the `id` value in the output, and then see [View Build Details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. +To work with detailed information about this build, make a note of the `id` value in the output, and then see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. -## Start Running Builds Automatically \(AWS CLI\) +## Start running builds automatically \(AWS CLI\) If your source code is stored in a GitHub or a GitHub Enterprise repository, you can use GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. @@ -252,9 +252,9 @@ For GitHub Enterprise, information similar to the following appears in the outpu 1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. -## Stop Running Builds Automatically \(AWS CLI\) +## Stop running builds automatically \(AWS CLI\) -If your source code is stored in a GitHub or a GitHub Enterprise repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start Running Builds Automatically \(AWS CLI\)](#run-build-cli-auto-start)\. +If your source code is stored in a GitHub or a GitHub Enterprise repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start running builds automatically \(AWS CLI\)](#run-build-cli-auto-start)\. If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: @@ -268,8 +268,8 @@ If this command is successful, no information and no errors appear in the output **Note** This deletes the webhook from your CodeBuild project only\. You should also delete the webhook from your GitHub or GitHub Enterprise repository\. -## Run a Build \(AWS SDKs\) +## 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 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 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 +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/sample-access-tokens.md b/doc_source/sample-access-tokens.md index da37f7f..a414638 100644 --- a/doc_source/sample-access-tokens.md +++ b/doc_source/sample-access-tokens.md @@ -1,8 +1,8 @@ -# Using Access Tokens with Your Source Provider in CodeBuild +# 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, you use a personal access token\. For Bitbucket, you use an app password\. -## Access Token Prerequisites +## Access token prerequisites Before you begin, you must add the proper permission scopes to your access token\. @@ -11,18 +11,18 @@ + **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/)\. +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)\. +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\) +## 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.md#create-project-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.md#create-project-console)\. For GitHub: @@ -50,9 +50,9 @@ CodeBuild does not support Bitbucket Server\. 1. Choose **Save Bitbucket credentials**\. -## Connect Source Providers with Access Tokens \(CLI\) +## 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)\. +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: @@ -95,7 +95,7 @@ Follow these steps to use the AWS CLI to connect your project to GitHub or Bitbu **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.md#create-project-cli)\. + 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.md#create-project-cli)\. 1. To view the connected access tokens, run the list\-source\-credentials command\. diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 32151aa..b453b7f 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -1,21 +1,21 @@ -# Bitbucket Pull Request and Webhook Filter Sample for CodeBuild +# Bitbucket pull request and webhook filter sample for CodeBuild 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\. **Topics** -+ [Bitbucket Pull Request 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](#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) -## Bitbucket Pull Request Prerequisites +## Prerequisites To run this sample you must connect your AWS CodeBuild project with your Bitbucket account\. **Note** CodeBuild has updated its permissions with Bitbucket\. If you previously connected your project to Bitbucket and now receive a Bitbucket connection error, you must reconnect to grant CodeBuild permission to manage your webhooks\. -## Create a Build Project with Bitbucket as the Source Repository and Enable Webhooks +## Create a build project with Bitbucket as the source repository and enable webhooks The following steps describe how to create an AWS CodeBuild project with Bitbucket as a source repository and enable webhooks\. @@ -35,7 +35,7 @@ CodeBuild does not support Bitbucket Server\. 1. Choose **Use a repository in my account**\. You cannot use a webhook if you use a public 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 **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**\. **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/) @@ -44,13 +44,13 @@ CodeBuild does not support Bitbucket Server\. 1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. -## Trigger a Build with a Bitbucket Webhook +## Trigger a build with a Bitbucket webhook For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code\. 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. 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\. @@ -67,7 +67,7 @@ CodeBuild does not support Bitbucket Server\. 1. Navigate to the Bitbucket pull request page to see the status of the build\. -## Filter Bitbucket Webhook Events +## Filter 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 triggered for specified branches only\. @@ -77,19 +77,21 @@ CodeBuild does not support Bitbucket Server\. 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 is found 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 is found in the `name` field of the `new` object in the `push` object of the webhook payload\. For pull request events, the branch name is found 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 is found in the `name` field of the `branch` object in the `destination` object in the webhook payload\. + + `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\)](#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\)](#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\) +### Filter Bitbucket webhook events \(console\) To use the AWS Management Console to filter webhook events: @@ -103,14 +105,14 @@ You must enable the `merged` event in your Bitbucket webhook setting if you crea 1. Choose **Add filter group** to add another filter group\. - For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. + For more information, see [Create a build project \(console\)](create-project.md#create-project-console) 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/master$` and head references that matches `^refs/heads/branch1!`\. ++ 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$`\. ![\[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/) @@ -119,14 +121,22 @@ In this example, a webhook filter group triggers a build for all requests except ![\[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 a change is made by a Bitbucket user that does not have an account ID that matches the regular expression `actor-account-id`\. +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/) -### Filter BitBucket Webhook Events \(SDK\) +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*\. @@ -143,9 +153,9 @@ In this example, a webhook filter group triggers a build only when a change is m ] ``` - 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 are evaluate to true: + 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$` and \. ++ The second filter group specifies push requests on branches with Git reference names that match the regular expression `^refs/heads/myBranch$`\. ``` "filterGroups": [ @@ -214,11 +224,46 @@ You can create a filter that triggers a build only when a change is made by a Bi ] ``` -### Filter Bitbucket Webhook Events \(AWS CloudFormation\) +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\\\]*\. - To use an AWS CloudFormation template to filter webhook events, use the AWS CodeBuild project's `FilterGroups` property\. The following YAML\-formatted portion of a 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 that does not have account ID `12345`\. +``` +"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: @@ -250,4 +295,8 @@ CodeBuildProject: 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/sample-build-badges.md b/doc_source/sample-build-badges.md index fa75327..51aa962 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -1,8 +1,8 @@ -# Build Badges Sample with CodeBuild +# Build badges sample with CodeBuild AWS 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\. This image is accessible through a publicly available URL generated for your CodeBuild project\. This allows anyone to view the status of a CodeBuild project\. Build badges do not contain any security information, so they do not require authentication\. -## Create a Build Project with Build Badges Enabled \(Console\) +## Create a build project with build badges enabled \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -11,20 +11,20 @@ AWS CodeBuild now supports the use of build badges, which provide an embeddable, 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 **Source**, for **Source provider**, choose the source code provider type, and then do one of the following: +**Note** + CodeBuild does not support build badges with the Amazon S3 source provider\. Because AWS CodePipeline uses Amazon S3 for artifact transfers, build badges are not supported for build projects that are part of a pipeline created in CodePipeline\. + If you chose **CodeCommit**, then for **Repository**, choose the name of the repository\. Select **Enable build badge** to make your project's build status visible and embeddable\. + If you chose **GitHub**, follow the instructions to connect \(or reconnect\) with GitHub\. On the GitHub **Authorize application** page, for **Organization access**, choose **Request access** next to each repository you want AWS CodeBuild to be able to access\. After you choose **Authorize application**, back in the AWS CodeBuild console, for **Repository**, choose the name of the repository that contains the source code\. Select **Enable build badge** to make your project's build status visible and embeddable\. + If you chose **Bitbucket**, follow the instructions to connect \(or reconnect\) with Bitbucket\. On the Bitbucket **Confirm access to your account** page, for **Organization access**, choose **Grant access**\. After you choose **Grant access**, back in the AWS CodeBuild console, for **Repository**, choose the name of the repository that contains the source code\. Select **Enable build badge** to make your project's build status visible and embeddable\. **Important** Updating your project source might affect the accuracy of the project's build badges\. -**Note** - CodeBuild does not support build badges with the S3 source provider\. Because AWS CodePipeline uses S3 for artifact transfers, build badges are not supported for build projects that are part of a CodePipeline pipeline 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/) + + 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*\. 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\. @@ -36,33 +36,33 @@ When you use the console to create or update a build project, you can create a C + 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)\. + 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 build output artifacts, choose **No artifacts**\. - + To store the build output in an Amazon S3 bucket, choose **Amazon S3**, and then do the following: + + 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)\. + + 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\. +1. Expand **Additional configuration** and choose options as appropriate\. 1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. -## Create a Build Project with Build Badges Enabled \(CLI\) +## Create a build project with build badges enabled \(CLI\) -For information about creating a build project, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. To include build badges with your AWS CodeBuild project, you must specify *badgeEnabled* with a value of `true` \. +For information about creating a build project, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. To include build badges with your AWS CodeBuild project, you must specify *badgeEnabled* with a value of `true`\. -## Access Your AWS CodeBuild Build Badges +## Access your AWS CodeBuild build badges 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)\. ++ 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 given 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 for the master branch, but you can specify any branch in your source repository that you have used to run a build\. -## Publish Your CodeBuild Build Badges +## Publish your CodeBuild build badges 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\. @@ -72,7 +72,7 @@ Sample markdown code: ![Build Status](https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch=master) ``` -## CodeBuild Badge Statuses +## CodeBuild badge statuses + **PASSING** The most recent build on the given branch passed\. + **FAILING** The most recent build on the given branch timed out, failed, faulted, or was stopped\. + **IN\_PROGRESS** The most recent build on the given branch is in progress\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 481240b..2b9f811 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -1,15 +1,15 @@ -# Build Notifications Sample for CodeBuild +# Build notifications sample for CodeBuild Amazon CloudWatch Events has built\-in support for AWS CodeBuild\. CloudWatch Events is a stream of system events describing changes in your AWS resources\. With CloudWatch Events, you write declarative rules to associate events of interest with automated actions to be taken\. This sample uses Amazon CloudWatch Events and Amazon Simple Notification Service \(Amazon SNS\) to send build notifications to subscribers whenever builds succeed, fail, go from one build phase to another, or any combination of these events\. **Important** -Running this sample may result in charges to your AWS account\. These include possible charges for CodeBuild and for AWS resources and actions related to Amazon CloudWatch and Amazon SNS\. For more information, see [CodeBuild Pricing](http://aws.amazon.com/codebuild/pricing), [Amazon CloudWatch Pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon SNS Pricing](http://aws.amazon.com/sns/pricing)\. +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 CloudWatch and Amazon SNS\. For more information, see [CodeBuild Pricing](http://aws.amazon.com/codebuild/pricing), [Amazon CloudWatch Pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon SNS Pricing](http://aws.amazon.com/sns/pricing)\. -## Running the Sample +## Running the sample -To run this sample: +**To run this sample** -1. If you already have a topic set up and subscribed to in Amazon SNS that you want to use for this sample, skip ahead to step 4\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon SNS, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. \(Using an AWS root account is not recommended\.\) This statement enables viewing, creating, subscribing, and testing the sending of notifications to topics in Amazon SNS\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. +1. If you already have a topic set up and subscribed to in Amazon SNS that you want to use for this sample, skip ahead to step 4\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon SNS, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\. This statement enables viewing, creating, subscribing, and testing the sending of notifications to topics in Amazon SNS\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. ``` { @@ -37,30 +37,34 @@ To run this sample: The IAM entity that modifies this policy must have permission in IAM to modify policies\. For more information, see [Editing Customer Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with Inline Policies \(Console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. -1. Create or identify a topic in Amazon SNS\. AWS CodeBuild will use CloudWatch Events to send build notifications to this topic through Amazon SNS\. To create a topic: +1. Create or identify a topic in Amazon SNS\. AWS CodeBuild uses CloudWatch Events to send build notifications to this topic through Amazon SNS\. - 1. Open the Amazon SNS console, at [https://console\.aws\.amazon\.com/sns/home](https://console.aws.amazon.com/sns/home)\. + To create a topic: + + 1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns](https://console.aws.amazon.com/sns)\. 1. Choose **Create topic**\. - 1. In the **Create new topic** dialog box, for **Topic name**, type a name for the topic, for example **CodeBuildDemoTopic**\. \(If you choose a different name, substitute it throughout this sample\.\) + 1. In **Create new topic**, for **Topic name**, enter a name for the topic \(for example, **CodeBuildDemoTopic**\)\. \(If you choose a different name, substitute it throughout this sample\.\) 1. Choose **Create topic**\. - 1. On the **Topic details: CodeBuildDemoTopic** page, copy the **Topic ARN** value, as shown in the following screen shot\. You will 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\. To subscribe a recipient to a topic: +1. Subscribe one or more recipients to the topic to receive email notifications\. + + To subscribe a recipient to a topic: 1. With the Amazon SNS console open from the previous step, in the navigation pane, choose **Subscriptions**, and then choose **Create subscription**\. - 1. In the **Create subscription** dialog box, for **Topic ARN**, paste the topic ARN you copied from the previous step\. + 1. In **Create subscription**, for **Topic ARN**, paste the topic ARN you copied from the previous step\. 1. For **Protocol**, choose **Email**\. - 1. For **Endpoint**, type the recipient's full email address\. Compare your results to the following screen shot\. + 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**\. @@ -69,7 +73,7 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a For more information, see [Subscribe to a Topic](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html) in the *Amazon SNS Developer Guide*\. -1. If you are using an IAM user instead of an AWS root account or an administrator IAM user to work with CloudWatch Events, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. \(Using an AWS root account is not recommended\.\) This statement enables working with CloudWatch Events\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. +1. If you are using an IAM user instead of an AWS root account or an administrator IAM user to work with CloudWatch Events, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\. This statement is used to allow the user to work with CloudWatch Events\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. ``` { @@ -97,11 +101,11 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a 1. In the navigation pane, under **Events**, choose **Rules**, and then choose **Create rule**\. -1. On the **Step 1: Create rule page**, the following should already be chosen: **Event Pattern** and **Build event pattern to match events by service**\. +1. On the **Step 1: Create rule page**, **Event Pattern** and **Build event pattern to match events by service** should already be selected\. -1. For **Service Name**, choose **CodeBuild**\. For **Event Type**, **All Events** should already be chosen\. +1. For **Service Name**, choose **CodeBuild**\. For **Event Type**, **All Events** should already be selected\. -1. **Event Pattern Preview** should show the following code\. +1. The following code should be displayed in **Event Pattern Preview**: ``` { @@ -111,12 +115,12 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a } ``` - Compare your results so far to the following screen shot: + 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. Replace the code in **Event Pattern Preview** with one of the following two rule patterns by choosing **Edit**\. +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 whenever a build starts or completes, for the specified build projects in AWS CodeBuild\. + This first rule pattern triggers an event when a build starts or completes for the specified build projects in AWS CodeBuild\. ``` { @@ -142,13 +146,13 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a ``` In the preceding rule, make the following code changes as needed\. - + To trigger an event whenever a build starts or completes, either leave all of the values as shown in the `build-status` array, or remove the `build-status` array altogether\. + + To trigger an event when a build starts or completes, either leave all of the values as shown in the `build-status` array, or remove the `build-status` array altogether\. + To trigger an event only when a build completes, remove `IN_PROGRESS` from the `build-status` array\. + To trigger an event only when a build starts, remove all of the values except `IN_PROGRESS` from the `build-status` array\. + To trigger events for all build projects, remove the `project-name` array altogether\. + To trigger events only for individual build projects, specify the name of each build project in the `project-name` array\. - This second rule pattern triggers an event whenever a build moves from one build phase to another, for the specified build projects in AWS CodeBuild\. + This second rule pattern triggers an event whenever a build moves from one build phase to another for the specified build projects in AWS CodeBuild\. ``` { @@ -187,14 +191,14 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a ``` In the preceding rule, make the following code changes as needed\. - + To trigger an event for every build phase change \(which may send up to 9 notifications for each build\), either leave all of the values as shown in the `completed-phase` array, or remove the `completed-phase` array altogether\. + + To trigger an event for every build phase change \(which might send up to nine notifications for each build\), either leave all of the values as shown in the `completed-phase` array, or remove the `completed-phase` array altogether\. + To trigger events only for individual build phase changes, remove the name of each build phase in the `completed-phase` array that you do not want to trigger an event for\. + To trigger an event for every build phase status change, either leave all of the values as shown in the `completed-phase-status` array, or remove the `completed-phase-status` array altogether\. + 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\. **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 may produce unexpected results or stop working altogether\. +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\. When you have finished replacing the code, choose **Save**\. @@ -206,64 +210,64 @@ If you want to trigger events for both build state changes and build phase chang 1. Expand **Configure input**, and then choose **Input Transformer**\. -1. In the **Input Path** box, type one of the following input paths\. +1. In the **Input Path** box, enter one of the following input paths\. - For a rule with a `detail-type` value of `CodeBuild Build State Change`, type the following\. + For a rule with a `detail-type` value of `CodeBuild Build State Change`, enter the following\. ``` {"build-id":"$.detail.build-id","project-name":"$.detail.project-name","build-status":"$.detail.build-status"} ``` - For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, type the following\. + For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, enter the following\. ``` {"build-id":"$.detail.build-id","project-name":"$.detail.project-name","completed-phase":"$.detail.completed-phase","completed-phase-status":"$.detail.completed-phase-status"} ``` -**Note** -To get other types of information, see the [Build Notifications Input Format Reference](#sample-build-notifications-ref)\. -1. In the **Input Template** box, type one of the following input templates\. + To get other types of information, see the [Build notifications input format reference](#sample-build-notifications-ref)\. + +1. In the **Input Template** box, enter one of the following input templates\. - For a rule with a `detail-type` value of `CodeBuild Build State Change`, type the following\. + For a rule with a `detail-type` value of `CodeBuild Build State Change`, enter the following\. ``` "Build '' for build project '' has reached the build status of ''." ``` - For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, type the following\. + For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, enter the following\. ``` "Build '' for build project '' has completed the build phase of '' with a status of ''." ``` - Compare your results so far to the following screen shot, which shows a rule with a `detail-type` value of `CodeBuild Build State Change`: + 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, type a **Name** and an optional **Description**\. Leave the **Enabled** box checked for **State**\. +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, for example 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 AWS 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\. -To change a rule's behavior, in the CloudWatch console, choose the rule you want to change, and then choose **Actions**, **Edit**\. Make changes to the rule, and then choose **Configure details**, followed by choosing **Update rule**\. +To change a rule's behavior, in the CloudWatch console, choose the rule you want to change, choose **Actions**, and then choose **Edit**\. Make changes to the rule, choose **Configure details**, and then choose **Update rule**\. -To stop using a rule to send build notifications, in the CloudWatch console, choose the rule you want to stop using, and then choose **Actions**, **Disable**\. +To stop using a rule to send build notifications, in the CloudWatch console, choose the rule you want to stop using, choose **Actions**, and then choose **Disable**\. -To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, and then choose **Actions**, **Delete**\. +To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, choose **Actions**, and then choose **Delete**\. -### Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. +### Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. -## Build Notifications Input Format Reference +## Build notifications input format reference CloudWatch delivers notifications in JSON format\. diff --git a/doc_source/sample-buildspec-artifact-naming.md b/doc_source/sample-buildspec-artifact-naming.md index 701cc41..dc06d4e 100644 --- a/doc_source/sample-buildspec-artifact-naming.md +++ b/doc_source/sample-buildspec-artifact-naming.md @@ -1,14 +1,14 @@ -# Using Semantic Versioning to Name Build Artifacts Sample +# Use semantic versioning to name build artifacts sample This sample contains example buildspec files that demonstrate how to specify an artifact name that is created at build time\. A name specified in a buildspec file can incorporate Shell commands and environment variables to make it unique\. A name you specify in a buildspec file overrides a name you enter in the console when you create your project\. - If you build mulitple times, using an artifact name specified in the buildspec file can ensure your output artifact file names are unique\. For example, you can use a date and time stamp that is inserted into an artifact name at build time\. + If you build mulitple times, using an artifact name specified in the buildspec file can ensure your output artifact file names are unique\. For example, you can use a date and timestamp that is inserted into an artifact name at build time\. If you want to override the artifact name you entered in the console with a name in the buildspec file, do the following: 1. Set your build project to override the artifact name with a name in the buildspec file\. - + If you use the console to create your build project, select **Enable semantic versioning**\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. - + If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON\-formatted file passed to `create-project`\. For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. + + If you use the console to create your build project, select **Enable semantic versioning**\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console)\. + + If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON\-formatted file passed to `create-project`\. For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. + If you use the AWS CodeBuild API, set the `overrideArtifactName` flag on the `ProjectArtifacts` object when a project is created or updated or a build is started\. 1. Specify a name in the buildspec file\. Use the following sample buildspec files as a guide\. @@ -27,7 +27,7 @@ artifacts: name: myname-$(date +%Y-%m-%d) ``` - This Linux example shows you how to specify an artifact name that uses a CodeBuild environment variable\. For more information, see [Environment Variables in Build Environments](build-env-ref-env-vars.md)\. + This Linux example shows you how to specify 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 @@ -60,7 +60,7 @@ artifacts: name: $Env:TEST_ENV_VARIABLE-$(Get-Date -UFormat "%Y%m%d-%H%M%S") ``` - This Windows example shows you how to specify an artifact name that uses a variable declared in the buildspec file and a CodeBuild environment variable\. For more information, see [Environment Variables in Build Environments](build-env-ref-env-vars.md)\. + This Windows example shows you how to specify an artifact name that uses a variable declared in the buildspec file and a CodeBuild environment variable\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. ``` version: 0.2 @@ -79,4 +79,4 @@ artifacts: name: $Env:TEST_ENV_VARIABLE-$Env:AWS_REGION ``` - For more information, see [Build Specification Reference for CodeBuild](build-spec-ref.md)\. \ No newline at end of file + For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. \ No newline at end of file diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index c0e61d1..892c66b 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -1,13 +1,13 @@ -# CodeDeploy Sample for CodeBuild +# CodeDeploy sample for CodeBuild -This sample instructs AWS CodeBuild to use Maven to produce as build output a single JAR file named `my-app-1.0-SNAPSHOT.jar`\. This sample then uses CodeDeploy to deploy the JAR file to an Amazon Linux instance\. \(Alternatively, you can use AWS CodePipeline to automate the use of CodeDeploy to deploy the JAR file to an Amazon Linux instance\.\) This sample is based on the [Maven in 5 Minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html) topic on the Apache Maven website\. +This sample instructs AWS CodeBuild to use Maven to produce as build output a single JAR file named `my-app-1.0-SNAPSHOT.jar`\. This sample then uses CodeDeploy to deploy the JAR file to an Amazon Linux instance\. You can also use AWS CodePipeline to automate the use of CodeDeploy to deploy the JAR file to an Amazon Linux instance\. This sample is based on the [Maven in 5 Minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html) topic on the Apache Maven website\. **Important** -Running this sample may 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)\. +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)\. -## Running the Sample +## Running the sample -To run this sample: +**To run this sample** 1. Download and install Maven\. For more information, see [Downloading Apache Maven](https://maven.apache.org/download.cgi) and [Installing Apache Maven](https://maven.apache.org/install.html) on the Apache Maven website\. @@ -17,7 +17,7 @@ To run this sample: mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false ``` - If successful, this directory structure and files will be created\. + If successful, this directory structure and files is created\. ``` (root directory name) @@ -95,7 +95,7 @@ To run this sample: ` -- 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 Amazon S3 input bucket or a GitHub or Bitbucket repository\. +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\. **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: @@ -120,7 +120,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP ` -- AppTest.java ``` -1. Create a build project by following the steps in [Create a Build Project](create-project.md)\. +1. Create a build project by following the steps in [Create a build project](create-project.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\.\) @@ -147,26 +147,26 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP } ``` -1. If you plan to deploy the build output artifact with CodeDeploy, then follow the steps in [Run a Build](run-build.md)\. Otherwise, skip this step\. \(This is because if you plan to deploy the build output artifact with CodePipeline, then CodePipeline will use CodeBuild to run the build automatically\.\) +1. If you plan to deploy the build output artifact with CodeDeploy, follow the steps in [Run a build](run-build.md)\. Otherwise, skip this step\. \(This is because if you plan to deploy the build output artifact with CodePipeline, CodePipeline uses CodeBuild to run the build automatically\.\) 1. Complete the setup steps for using CodeDeploy, including: - + Grant the IAM user access to CodeDeploy and the AWS services and actions CodeDeploy depends on\. For more information, see [Provision an IAM User](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-setup.html#getting-started-user) in the *CodeDeploy User Guide*\. - + Create or identify a service role to enable CodeDeploy to identify the instances where it will deploy the build output artifact\. For more information, see [Creating a Service Role for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) in the *CodeDeploy User Guide*\. - + Create or identify an IAM instance profile to enable your instances to access the Amazon S3 input bucket or GitHub repository that contains the build output artifact\. For more information, see [Creating an IAM Instance Profile for Your Amazon EC2 Instances](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-iam-instance-profile.html) in the *CodeDeploy User Guide*\. + + Grant the IAM user access to CodeDeploy and the AWS services and actions CodeDeploy depends on\. For more information, see [Provision an IAM User](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-setup.html#getting-started-user) in the *AWS CodeDeploy User Guide*\. + + Create or identify a service role to enable CodeDeploy to identify the instances where it deploys the build output artifact\. For more information, see [Creating a Service Role for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) in the *AWS CodeDeploy User Guide*\. + + Create or identify an IAM instance profile to enable your instances to access the S3 input bucket or GitHub repository that contains the build output artifact\. For more information, see [Creating an IAM Instance Profile for Your Amazon EC2 Instances](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-iam-instance-profile.html) in the *AWS CodeDeploy User Guide*\. -1. Create or identify an Amazon Linux instance compatible with CodeDeploy where the build output artifact will be deployed\. For more information, see [Working with Instances for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-instances.html) in the *CodeDeploy User Guide*\. +1. Create or identify an Amazon Linux instance compatible with CodeDeploy where the build output artifact is deployed\. For more information, see [Working with Instances for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-instances.html) in the *AWS CodeDeploy User Guide*\. -1. Create or identify a CodeDeploy application and deployment group\. For more information, see [Creating an Application with CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-application.html) in the *CodeDeploy User Guide*\. +1. Create or identify a CodeDeploy application and deployment group\. For more information, see [Creating an Application with CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-application.html) in the *AWS CodeDeploy User Guide*\. 1. Deploy the build output artifact to the instance\. - 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 *CodeDeploy User Guide*\. + 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 CodeBuild](how-to-create-pipeline.md)\. + To deploy with CodePipeline, see [Use AWS CodePipeline with AWS 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`\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file +## Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index f0b3851..593d647 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -1,8 +1,8 @@ -# Create a Static Website with Build Output Hosted in an Amazon S3 Bucket +# Create a static website with build output hosted in an S3 bucket - You can disable the encryption of artifacts in a build\. You might want to do this so that you can publish artifacts to a location that is configured to host a website\. \(You cannot publish encrypted artifacts\.\) This sample shows how you can use webhooks to trigger a build and publish its artifacts to an Amazon S3 bucket that is configured to be a website\. + You can disable the encryption of artifacts in a build\. You might want to do this so that you can publish artifacts to a location that is configured to host a website\. \(You cannot publish encrypted artifacts\.\) This sample shows how you can use webhooks to trigger a build and publish its artifacts to an S3 bucket that is configured to be a website\. -1. Follow the instructions in [Setting Up a Static Website](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html) to configure an Amazon S3 bucket to function like a website\. +1. Follow the instructions in [Setting Up a Static Website](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html) to configure an S3 bucket to function like a website\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -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/) + + 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*\. 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,18 +32,18 @@ When you use the console to create or update a build project, you can create a C + 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)\. + For more information, see the [Buildspec reference](build-spec-ref.md)\. -1. In **Artifacts**, for ** Type**, choose **Amazon S3** to store the build output in an Amazon S3 bucket\. +1. In **Artifacts**, for ** Type**, choose **Amazon S3** to store the build output in an S3 bucket\. -1. For **Bucket name**, choose the name of the Amazon S3 bucket you configured to function as a website in step 1\. +1. For **Bucket name**, choose the name of the S3 bucket you configured to function as a website in step 1\. -1. If you chose **Insert build commands** in **Buildspec**, then in the `files` section in `artifacts` of your commands, enter the locations of the files from the build that you want to put into the output bucket\. If you have more than one location, use a comma to separate each location \(for example, "appspec\.yml, target/my\-app\.jar"\)\. For more information, see [Artifacts reference-key in the buildspec file](build-spec-ref.md#artifacts-build-spec)\. +1. If you chose **Insert build commands** in **Environment**, then for **Output files**, enter the locations of the files from the build that you want to put into the output bucket\. If you have more than one location, use a comma to separate each location \(for example, **appspec\.yml, target/my\-app\.jar**\)\. For more information, see [Artifacts reference-key in the buildspec file](build-spec-ref.md#artifacts-build-spec)\. 1. Select **Disable artifacts encryption**\. -1. Expand **Additional configuration** and set options as appropriate\. +1. Expand **Additional configuration** and choose options as appropriate\. 1. Choose **Create build project**\. On the build project page, in **Build history**, choose **Start build** to run the build\. -1. \(Optional\) Follow the instructions in [Example: Speed Up Your Website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-cloudfront-walkthrough.html)\. \ No newline at end of file +1. \(Optional\) Follow the instructions in [Example: Speed Up Your Website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-cloudfront-walkthrough.html) in the *Amazon S3 Developer Guide*\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 8baf3d0..f2557d6 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -1,28 +1,28 @@ -# Docker in Custom Image Sample for CodeBuild +# Docker in custom image sample for CodeBuild This sample builds and runs a Docker image by using AWS CodeBuild and a custom Docker build image \(`docker:dind` in Docker Hub\)\. -To learn how to build a Docker image by using a build image provided by CodeBuild with Docker support instead, see our [Docker Sample](sample-docker.md)\. +To learn how to build a Docker image by using a build image provided by CodeBuild with Docker support instead, see our [Docker sample](sample-docker.md)\. **Important** -Running this sample may 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)\. +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, 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)\. **Topics** -+ [Running the Sample](#sample-docker-custom-image-running) -+ [Directory Structure](#sample-docker-custom-image-dir) ++ [Running the sample](#sample-docker-custom-image-running) ++ [Directory structure](#sample-docker-custom-image-dir) + [Files](#sample-docker-custom-image-files) -+ [Related Resources](#w58aac11c41c34c17) ++ [Related resources](#acb-more-info) -## Running the Sample +## Running the sample -To run this sample: +**To run this sample** -1. Create the files as described in the Directory Structure and Files sections of this topic, and then upload them to an Amazon S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. +1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. **Important** Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. -If you are using an Amazon 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)`\. +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 view related 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 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\.\) @@ -49,9 +49,9 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co **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\. -1. To see the build results, look in the build's log for the string `Hello, World!`\. For more information, see [View Build Details](view-build-details.md)\. +1. To see the build results, look in the build's log for the string `Hello, World!`\. For more information, see [View build details](view-build-details.md)\. -## Directory Structure +## Directory structure This sample assumes this directory structure\. @@ -63,7 +63,7 @@ This sample assumes this directory structure\. ## Files -The base image of the operating system used in this sample is Ubuntu\. The sample uses these files\. For more information about the OverlayFS storage driver referenced in the buildspec file, see [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)\. +The base image of the operating system used in this sample is Ubuntu\. The sample uses these files\. For more information about the OverlayFS storage driver referenced in the buildspec file, see [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/) on the Docker website\. `buildspec.yml` \(in `(root directory name)`\) @@ -99,7 +99,7 @@ FROM maven:3.3.9-jdk-8 RUN echo "Hello World" ``` -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file +## Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 181555c..7c8f2ea 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -1,28 +1,28 @@ -# Docker Sample for CodeBuild +# Docker sample for CodeBuild -This sample produces as build output a Docker image and then pushes the Docker image to an Amazon Elastic Container Registry \(Amazon ECR\) image repository\. You can adapt this sample to push the Docker image to Docker Hub\. For more information, see [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub)\. +This sample produces as build output a Docker image and then pushes the Docker image to an Amazon Elastic Container Registry \(Amazon ECR\) image repository\. You can adapt this sample to push the Docker image to Docker Hub\. For more information, see [Adapting the sample to push the image to Docker Hub](#sample-docker-docker-hub)\. -To learn how to build a Docker image by using a custom Docker build image instead \(`docker:dind` in Docker Hub\), see our [Docker in Custom Image Sample](sample-docker-custom-image.md)\. +To learn how to build a Docker image by using a custom Docker build image \(`docker:dind` in Docker Hub\), see our [Docker in custom image sample](sample-docker-custom-image.md)\. This sample was tested referencing `golang:1.12`\. This sample uses the new multi\-stage Docker builds feature, which produces a Docker image as build output\. It then pushes the Docker image to an Amazon ECR image repository\. Multi\-stage Docker image builds help to reduce the size of the final Docker image\. For more information, see [Use multi\-stage builds with Docker](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)\. **Important** -Running this sample may result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry Pricing](http://aws.amazon.com/ecr/pricing)\. +Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry Pricing](http://aws.amazon.com/ecr/pricing)\. **Topics** -+ [Running the Sample](#sample-docker-running) -+ [Directory Structure](#sample-docker-dir) ++ [Running the sample](#sample-docker-running) ++ [Directory structure](#sample-docker-dir) + [Files](#sample-docker-files) -+ [Adapting the Sample to Push the Image to Docker Hub](#sample-docker-docker-hub) -+ [Related Resources](#w58aac11c41c19c23) ++ [Adapting the sample to push the image to Docker Hub](#sample-docker-docker-hub) ++ [Related resources](#acb-more-info) -## Running the Sample +## Running the sample -To run this sample: +**To run this sample** -1. If you already have an image repository in Amazon ECR you want to use, skip to step 3\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon ECR, add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. \(Using an AWS root account is not recommended\.\) This statement enables creating Amazon ECR repositories for storing Docker images\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. For more information, see [Working with Inline Policies Using the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. +1. If you already have an image repository in Amazon ECR you want to use, skip to step 3\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon ECR, add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\.This statement allows the creation of Amazon ECR repositories for storing Docker images\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. For more information, see [Working with Inline Policies Using the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. ``` { @@ -44,9 +44,9 @@ To run this sample: **Note** The IAM entity that modifies this policy must have permission in IAM to modify policies\. -1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS Region where you will be creating your build environment and running your build\. For more information, see [Creating a Repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you will specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. +1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS Region where you create your build environment and run your build\. For more information, see [Creating a Repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. -1. Add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the policy you attached to your AWS CodeBuild service role\. This statement enables CodeBuild to upload Docker images to Amazon ECR repositories\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. +1. Add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the policy you attached to your AWS CodeBuild service role\. This statement allows CodeBuild to upload Docker images to Amazon ECR repositories\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. ``` { @@ -73,12 +73,12 @@ The IAM entity that modifies this policy must have permission in IAM to modify p **Note** The IAM entity that modifies this policy must have permission in IAM to modify policies\. -1. Create the files as described in the Directory Structure and Files sections of this topic, and then upload them to an Amazon S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. +1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. **Important** Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. -If you are using an Amazon 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)`\. +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 AWS 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: @@ -145,7 +145,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 1. Choose the repository name\. The image should be listed in the **Image tag** column\. -## Directory Structure +## Directory structure This sample assumes this directory structure\. @@ -162,15 +162,12 @@ This sample uses these files\. `buildspec.yml` \(in `(root directory name)`\) **Note** -If you are using Docker prior to version 17\.06, remove the `--no-include-email` option\. +If you are using a version of Docker earlier than 17\.06, remove the `--no-include-email` option\. ``` version: 0.2 phases: - install: - runtime-versions: - docker: 18 pre_build: commands: - echo Logging in to Amazon ECR... @@ -206,13 +203,13 @@ COPY --from=build /bin/HelloWorld /bin/HelloWorld ENTRYPOINT ["/bin/HelloWorld"] ``` -## Adapting the Sample to Push the Image to Docker Hub +## Adapting the sample to push the image to Docker Hub -To push the Docker image to Docker Hub instead of Amazon ECR, modify this sample's code\. +To push the Docker image to Docker Hub instead of Amazon ECR, edit this sample's code\. +**Note** +If you are using a version of Docker earlier than 17\.06, remove the `--no-include-email` option\. 1. Replace these Amazon ECR\-specific lines of code in the `buildspec.yml` file: -**Note** -If you are using Docker prior to version 17\.06, remove the `--no-include-email` option\. ``` ... @@ -234,7 +231,7 @@ If you are using Docker prior to version 17\.06, remove the `--no-include-email` ... ``` - With these Docker Hub\-specific lines of code\. + With these Docker Hub\-specific lines of code: ``` ... @@ -256,10 +253,10 @@ If you are using Docker prior to version 17\.06, remove the `--no-include-email` ... ``` -1. Upload the modified code to an Amazon S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. +1. Upload the edited code to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. **Important** Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. -If you are using an Amazon 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)`\. +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. Replace these lines of code from the JSON\-formatted input to the `create-project` command: @@ -286,7 +283,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co ... ``` - With these lines of code\. + With these lines of code: ``` ... @@ -303,11 +300,11 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co ... ``` -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 AWS 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\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file +## Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index b85d6c1..0986ed8 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -1,24 +1,24 @@ -# Amazon ECR Sample for CodeBuild +# Amazon ECR sample for CodeBuild This sample uses a Docker image in an Amazon Elastic Container Registry \(Amazon ECR\) image repository to build a sample Go project\. **Important** -Running this sample may result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry Pricing](http://aws.amazon.com/ecr/pricing)\. +Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry Pricing](http://aws.amazon.com/ecr/pricing)\. -## Running the Sample +## Running the sample -To run this sample: +**To run this sample** -1. To create and push the Docker image to your image repository in Amazon ECR, complete the steps in the Running the Sample section of the [Docker Sample](sample-docker.md)\. +1. To create and push the Docker image to your image repository in Amazon ECR, complete the steps in the "Running the sample" section of the [Docker sample](sample-docker.md)\. 1. Create a Go project: - 1. Create the files as described in the [Go Project Structure](#ecr-sample-go-project-file-structure) and [Go Project Files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an Amazon S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. + 1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. **Important** Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. -If you are using an Amazon 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)`\. +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 view related 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 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\.\) @@ -45,37 +45,37 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co } ``` - 1. To get the build output artifact, open your Amazon S3 output bucket\. + 1. To get the build output artifact, open your S3 output bucket\. 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file\. In the extracted contents, get the `hello` file\. 1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment\. - + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your ProjectEnvironment\. - + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your ProjectEnvironment to `SERVICE_ROLE`\. + + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`\. + + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`\. 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. 1. In the list of repository names, choose the name of the repository you created or selected\. - 1. From the navigation pane choose **Permissions**, choose **Edit**, and then choose **Add statement**\. + 1. From the navigation pane, choose **Permissions**, choose **Edit**, and then choose **Add statement**\. 1. For **Statement name**, enter an identifier \(for example, **CodeBuildAccess**\)\. 1. For **Effect**, leave **Allow** selected\. This indicates that you want to allow access to another AWS account\. 1. For **Principal**, do one of the following: - + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal** enter `codebuild.amazonaws.com`\. - + If your project uses a cross\-account Amazon ECR image, for **AWS account IDs** enter IDs of the AWS accounts that you want to give access\. + + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild\.amazonaws\.com**\. + + If your project uses a cross\-account Amazon ECR image, for **AWS account IDs**, enter IDs of the AWS accounts that you want to give access\. 1. Skip the **All IAM entities** list\. - 1. For **Action**, select the pull\-only actions **ecr:GetDownloadUrlForLayer**, **ecr:BatchGetImage**, and **ecr:BatchCheckLayerAvailability**\. + 1. For **Action**, select the pull\-only actions: **ecr:GetDownloadUrlForLayer**, **ecr:BatchGetImage**, and **ecr:BatchCheckLayerAvailability**\. 1. Choose **Save**\. - This policy is displayed in **Permissions**\. The principal is what you entered for **Principal** in step 3f of this procedure: - + If your project uses CodeBuild credentials to pull an Amazon ECR image, under **Service principals** is `"codebuild.amazonaws.com"`\. - + If your project uses a cross\-account Amazon ECR image, under **AWS Account IDs** is the ID of the AWS account that you want to give access\. + This policy is displayed in **Permissions**\. The principal is what you entered for **Principal** in step 3 of this procedure: + + If your project uses CodeBuild credentials to pull an Amazon ECR image, `"codebuild.amazonaws.com"` appears under **Service principals**\. + + If your project uses a cross\-account Amazon ECR image, the ID of the AWS account that you want to give access appears under **AWS Account IDs**\. The following sample policy uses a cross\-account Amazon ECR image\. @@ -99,7 +99,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co } ``` -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 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\.\) @@ -126,11 +126,11 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co } ``` -1. To get the build output artifact, open your Amazon S3 output bucket\. +1. To get the build output artifact, open your S3 output bucket\. 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file\. In the extracted contents, get the `hello` file\. -## Go Project Structure +## Go project structure This sample assumes this directory structure\. @@ -140,7 +140,7 @@ This sample assumes this directory structure\. `-- hello.go ``` -## Go Project Files +## Go project files This sample uses these files\. @@ -182,7 +182,7 @@ func main() { } ``` -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file +## Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 7208ccc..084301c 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -1,12 +1,12 @@ -# Amazon Elastic File System Sample for CodeBuild +# Amazon Elastic File System sample for AWS CodeBuild - You might want to create your AWS CodeBuild builds on Amazon EFS\. Amazon EFS is a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What Is Amazon Elastic File System](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html)\. + You might want to create your AWS CodeBuild builds on Amazon Elastic File System, a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What Is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) in the *Amazon Elastic File System User Guide*\. - This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to a file system created in Amazon EFS\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repository\. + This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repository\. Data in transit for your file system is encrypted\. To encrypt data in transit using a different image, see [Encrypting Data in Transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)\. -## Amazon Elastic File System and AWS CodeBuild Sample High\-Level Steps +## High\-level steps This sample covers the three high\-level steps required to use Amazon EFS with AWS CodeBuild: @@ -23,11 +23,11 @@ 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 a VPC using AWS CloudFormation Create your VPC with an AWS CloudFormation template\. -1. Follow the instructions in [AWS CloudFormation VPC Template](cloudformation-vpc-template.md) to use AWS CloudFormation to create a VPC\. +1. Follow the instructions in [AWS CloudFormation VPC template](cloudformation-vpc-template.md) to use AWS CloudFormation to create a VPC\. **Note** The VPC created by this AWS CloudFormation template has two private subnets and two public subnets\. You must only use private subnets when you use AWS CodeBuild to mount the file system you created in Amazon EFS\. If you use one of the public subnets, the build fails\. @@ -35,11 +35,11 @@ Data in transit for your file system is encrypted\. To encrypt data in transit u 1. Choose the VPC you created with AWS CloudFormation\. -1. On the **Description** tab, make a note of the name and ID of your VPC\. You need the name and ID when you create your AWS CodeBuild project later in this sample\. +1. On the **Description** tab, make a note of the name of your VPC and its ID\. Both are required when you create your AWS CodeBuild project later in this sample\. -## Create a File System with Your VPC +## Create an Amazon Elastic File System file system with your VPC - Create a simple file system for this sample using the VPC you created earlier\. + Create a simple Amazon EFS file system for this sample using the VPC you created earlier\. 1. Sign in to the AWS Management Console and open the Amazon EFS console at [ https://console\.aws\.amazon\.com/efs/](https://console.aws.amazon.com/efs/)\. @@ -59,9 +59,9 @@ Data in transit for your file system is encrypted\. To encrypt data in transit u 1. Choose **Create File System**\. -## Create a CodeBuild Project to Use with Amazon EFS +## Create a CodeBuild project to use with Amazon EFS - Create a 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\. + 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\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -123,7 +123,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 1. Choose **Start build**\. -## CodeBuild and Amazon EFS Sample Summary +## 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\. diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index aec26af..c81864a 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -1,13 +1,13 @@ -# AWS Elastic Beanstalk Sample for AWS CodeBuild +# 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 Elastic Beanstalk environment\. +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\. **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)\. -## Create the Source Code +## Create the source code -In this section, you use Maven to produce the source code\. Later on, you use AWS CodeBuild to build a WAR file based on this source code\. +In this section, you use Maven to produce the source code\. Later, you use CodeBuild to build a WAR file based on this source code\. 1. Download and install Maven\. For information, see [Downloading Apache Maven](https://maven.apache.org/download.cgi) and [Installing Apache Maven](https://maven.apache.org/install.html) on the Apache Maven website\. @@ -41,17 +41,17 @@ In this section, you use Maven to produce the source code\. Later on, you use AW ``` After you run Maven, continue with one of the following scenarios: -+ [Scenario A: Run AWS CodeBuild Manually and Deploy to Elastic Beanstalk Manually](#sample-elastic-beanstalk-manual) -+ [Scenario B: Use CodePipeline to Run AWS CodeBuild and Deploy to Elastic Beanstalk](#sample-elastic-beanstalk-codepipeline) -+ [Scenario C: Use the Elastic Beanstalk CLI to Run AWS CodeBuild and Deploy to an Elastic Beanstalk Environment](#sample-elastic-beanstalk-eb-cli) ++ [Scenario A: Run CodeBuild manually and deploy to Elastic Beanstalk manually](#sample-elastic-beanstalk-manual) ++ [Scenario B: Use CodePipeline to run CodeBuild and deploy to Elastic Beanstalk](#sample-elastic-beanstalk-codepipeline) ++ [Scenario C: Use the Elastic Beanstalk CLI to run AWS CodeBuild and deploy to an Elastic Beanstalk environment](#sample-elastic-beanstalk-eb-cli) -## Scenario A: Run AWS CodeBuild Manually and Deploy to Elastic Beanstalk Manually +## Scenario A: Run CodeBuild manually and deploy to Elastic Beanstalk manually -In this scenario, you create and upload the source code\. You then use the AWS CodeBuild and Elastic Beanstalk consoles to build the source code, create an Elastic Beanstalk application and environment, and deploy the build output to the environment\. +In this scenario, you create and upload the source code\. You then use the AWS CodeBuild and AWS Elastic Beanstalk consoles to build the source code, create an Elastic Beanstalk application and environment, and deploy the build output to the environment\. -### Step A1: Add Files to the Source Code +### Step a1: Add files to the source code -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 Amazon S3 input bucket or an AWS CodeCommit or GitHub repository \. +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\. @@ -90,22 +90,22 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi `-- pom.xml ``` -1. Upload the contents of the `my-web-app` directory to an Amazon 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 Amazon 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)\. + 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*\. -### Step A2: Create the Build Project and Run the Build +### Step a2: Create the build project and run the build In this step, you use the AWS CodeBuild console to create a build project and then run a build\. -1. Create or identify an Amazon S3 output bucket to store the build output\. If you're storing the source code in an Amazon S3 input bucket, the output bucket must be in the same AWS region as the input bucket\. +1. Create or choose an S3 output bucket to store the build output\. 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. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - Use the AWS region selector to choose a region that supports CodeBuild and matches the region where your Amazon S3 output bucket is stored\. + Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. This must be the same Region where your S3 output bucket is stored\. -1. Create a build project and then run a build\. For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project and then run a build\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -113,33 +113,33 @@ In this step, you use the AWS CodeBuild console to create a build project and th + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + For **Artifacts**: + For **Type**, choose **Amazon S3**\. - + For **Bucket name**, enter the name of an Amazon S3 bucket\. + + For **Bucket name**, enter the name of an S3 bucket\. + For **Name**, enter a build output file name that's easy for you to remember\. Include the `.zip` extension\. + For **Artifacts packaging**, choose **Zip**\. -### Step A3: Create the Application and Environment and Deploy +### Step a3: Create the application and environment and deploy -In this step, you use the Elastic Beanstalk console to create an application and environment\. As part of creating the environment, you deploy the build output from the previous step to the environment\. +In this step, you use the AWS Elastic Beanstalk console to create an application and environment\. As part of creating the environment, you deploy the build output from the previous step to the environment\. -1. Open the Elastic Beanstalk console at [https://console\.aws\.amazon\.com/elasticbeanstalk](https://console.aws.amazon.com/elasticbeanstalk)\. +1. Open the AWS Elastic Beanstalk console at [https://console\.aws\.amazon\.com/elasticbeanstalk](https://console.aws.amazon.com/elasticbeanstalk)\. - Use the AWS region selector to choose the region where your Amazon S3 output bucket is stored\. + Use the AWS Region selector to choose the AWS Region where your S3 output bucket is stored\. -1. Create an Elastic Beanstalk application\. For more information, see [Managing and Configuring AWS Elastic Beanstalk Applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html)\. +1. Create an Elastic Beanstalk application\. For more information, see [Managing and Configuring AWS Elastic Beanstalk Applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. -1. Create an Elastic Beanstalk environment for this application\. For more information, see [The Create New Environment Wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html)\. Leave all settings at their default values, except for these settings\. +1. Create an Elastic Beanstalk environment for this application\. For more information, see [The Create New Environment Wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Leave all settings at their default values, except for these settings\. + For **Platform**, choose **Tomcat**\. + For **Application code**, choose **Upload your code**, and then choose **Upload**\. For **Source code origin**, choose **Public S3 URL**, and then enter the full URL to the build output ZIP file in the output bucket\. Choose **Upload**\. 1. After Elastic Beanstalk deploys the build output to the environment, you can see the results in a web browser\. Go to the environment URL for the instance \(for example, `http://my-environment-name.random-string.region-ID.elasticbeanstalk.com`\)\. The web browser should display the text `Hello World!`\. -## Scenario B: Use CodePipeline to Run AWS CodeBuild and Deploy to Elastic Beanstalk +## Scenario B: Use CodePipeline to run CodeBuild and deploy to Elastic Beanstalk -In this scenario, you complete the steps to prepare and upload the source code\. You create a build project with CodeBuild and an AWS Elastic Beanstalk application and environment with the AWS Elastic Beanstalk console\. You then use the AWS CodePipeline console to create a pipeline\. After you create the pipeline, CodePipeline builds the source code and deploys the build output to the environment\. +In this scenario, you complete the steps to prepare and upload the source code\. You create a build project with CodeBuild and an Elastic Beanstalk application and environment with the AWS Elastic Beanstalk console\. You then use the AWS CodePipeline console to create a pipeline\. After you create the pipeline, CodePipeline builds the source code and deploys the build output to the environment\. -### Step B1: Add a Build Spec File to the Source Code +### Step b1: Add a buildspec file to 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 Amazon S3 input bucket or a CodeCommit or GitHub repository\. +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\. @@ -179,18 +179,18 @@ In this step, you create and add a buildspec file to the code you created in [Cr `-- pom.xml ``` -1. Upload this contents of the `my-web-app` directory to an Amazon 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 Amazon 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)\. + 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*\. -### Step B2: Create a build project +### Step b2: Create a build project In this step, you create an AWS CodeBuild build project to use with your pipeline\. 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.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -198,31 +198,31 @@ In this step, you create an AWS CodeBuild build project to use with your pipelin + For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. + For **Artifacts**: + For **Type**, choose **Amazon S3**\. - + For **Bucket name**, enter the name of an Amazon S3 bucket\. + + For **Bucket name**, enter the name of an S3 bucket\. + For **Name**, enter a build output file name that's easy for you to remember\. Include the `.zip` extension\. + For **Artifacts packaging**, choose **Zip**\. -### Step B3: Create an AWS Elastic Beanstalk application and environment +### Step b3: Create an Elastic Beanstalk application and environment -In this step, you create an AWS Elastic Beanstalk application and environment to use with CodePipeline\. +In this step, you create an Elastic Beanstalk application and environment to use with CodePipeline\. 1. Open the Elastic Beanstalk console at [https://console\.aws\.amazon\.com/elasticbeanstalk/](https://console.aws.amazon.com/elasticbeanstalk/)\. -1. Use the Elastic Beanstalk console to create an application\. For more information, see [Managing and Configuring AWS Elastic Beanstalk Applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html)\. +1. Use the AWS Elastic Beanstalk console to create an application\. For more information, see [Managing and Configuring AWS Elastic Beanstalk Applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. -1. Use the Elastic Beanstalk console to create an environment\. For more information, see [The Create New Environment Wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html)\. Except for **Platform**, leave all settings at their default values\. For **Platform**, choose **Tomcat**\. +1. Use the AWS Elastic Beanstalk console to create an environment\. For more information, see [The Create New Environment Wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Except for **Platform**, leave all settings at their default values\. For **Platform**, choose **Tomcat**\. -### Step B4: Create the Pipeline and Deploy +### Step b4: Create the pipeline and deploy -In this step, you use the CodePipeline console to create a pipeline\. After you create and run the pipeline, CodePipeline uses AWS CodeBuild to build the source code\. CodePipeline then uses Elastic Beanstalk to deploy the build output to the environment\. +In this step, you use the AWS CodePipeline console to create a pipeline\. After you create and run the pipeline, CodePipeline uses CodeBuild to build the source code\. CodePipeline then uses Elastic Beanstalk to deploy the build output to the environment\. -1. Create or identify a service role that CodePipeline, CodeBuild, and Elastic Beanstalk can use to do their work on your behalf\. For more information, see [Prerequisites](how-to-create-pipeline.md#how-to-create-pipeline-prerequisites)\. +1. Create or identify a service role that CodePipeline, CodeBuild, and Elastic Beanstalk can use to access resources on your behalf\. For more information, see [Prerequisites](how-to-create-pipeline.md#how-to-create-pipeline-prerequisites)\. 1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. - Use the AWS region selector to choose a region that supports CodeBuild and, if you're storing the source code in an Amazon S3 input bucket, choose the region where your input bucket is stored\. + 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.md#how-to-create-pipeline-console)\. 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\. @@ -230,17 +230,17 @@ In this step, you use the CodePipeline console to create a pipeline\. After you 1. After the pipeline has run successfully, you can see the results in a web browser\. Go to the environment URL for the instance \(for example, `http://my-environment-name.random-string.region-ID.elasticbeanstalk.com`\)\. The web browser should display the text `Hello World!`\. -Now, whenever you make changes to the source code and upload those changes to the original Amazon S3 input bucket or to the CodeCommit, GitHub, or Bitbucket repository, CodePipeline detects the change and runs the pipeline again\. This causes CodeBuild to rebuild the code and then causes Elastic Beanstalk to deploy the rebuilt output to the environment\. +Now, whenever you make changes to the source code and upload those changes to the original S3 input bucket or to the CodeCommit, GitHub, or Bitbucket repository, CodePipeline detects the change and runs the pipeline again\. This causes CodeBuild to rebuild the code and then causes Elastic Beanstalk to deploy the rebuilt output to the environment\. -## Scenario C: Use the Elastic Beanstalk CLI to Run AWS CodeBuild and Deploy to an Elastic Beanstalk Environment +## Scenario C: Use the Elastic Beanstalk CLI to run AWS CodeBuild and deploy to an Elastic Beanstalk environment In this scenario, you complete the steps to prepare and upload the source code\. You then run the Elastic Beanstalk CLI to create an Elastic Beanstalk application and environment, use CodeBuild to build the source code, and then deploy the build output to the environment\. For more information, see [Using the EB CLI with CodeBuild](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli-codebuild.html) in the *AWS Elastic Beanstalk Developer Guide*\. -### Step C1: Add Files to the Source Code +### Step c1: Add files to the source code -In this step, you add an Elastic Beanstalk configuration file and a buildspec file to the code you created in [Create the Source Code](#sample-elastic-beanstalk-prepare-source)\. You also create or identify a service role for the buildspec file\. +In this step, you add an Elastic Beanstalk configuration file and a buildspec file to the code you created in [Create the source code](#sample-elastic-beanstalk-prepare-source)\. You also create or identify a service role for the buildspec file\. -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 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\. @@ -286,11 +286,11 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi `-- pom.xml ``` -### Step C2: Install and Run the EB CLI +### 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 your computer's or instance's 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)/my-web-app` directory\. Run the eb init command to configure the EB CLI\. ``` eb init @@ -316,11 +316,11 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi 1. After you run the eb create command, the EB CLI does the following: - 1. Creates a ZIP file from the source code and then uploads the ZIP file to an Amazon S3 bucket in your account\. + 1. Creates a ZIP file from the source code and then uploads the ZIP file to an S3 bucket in your account\. 1. Creates an Elastic Beanstalk application and application version\. - 1. Creates a AWS CodeBuild project\. + 1. Creates a CodeBuild project\. 1. Runs a build based on the new project\. @@ -334,7 +334,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file +## Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 149849b..f175564 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -1,4 +1,4 @@ -# GitHub Enterprise Sample for CodeBuild +# GitHub Enterprise sample for CodeBuild AWS CodeBuild supports GitHub Enterprise as a source repository\. This sample shows how to set up your CodeBuild projects when your GitHub Enterprise repository has a certificate installed\. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise repository\. @@ -38,11 +38,11 @@ Save the certificate as a \.pem file\. **Important** Save the certificate as a \.pem file\. -1. Upload your certificate file to an Amazon S3 bucket\. For information about how to create an Amazon S3 bucket, see [How Do I Create an Amazon S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) For information about how to upload objects to an Amazon S3 bucket, see [How Do I Upload Files and Folders to a Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html) +1. Upload your certificate file to an S3 bucket\. For information about how to create an S3 bucket, see [How Do I Create an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) For information about how to upload objects to an S3 bucket, see [How Do I Upload Files and Folders to a Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html) **Note** This bucket must be in the same AWS region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, the bucket must be in the US East \(Ohio\) Region\. -## Create a Build Project with GitHub Enterprise as the Source Repository and Enable Webhooks \(Console\) +## Create a build project with GitHub Enterprise as the source repository and enable webhooks \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -55,9 +55,9 @@ This bucket must be in the same AWS region as your builds\. For example, if you **Note** You only need to enter and save the personal access token once\. All future AWS CodeBuild projects use this token\. + In **Repository URL**, enter the path to your repository, including the name of the repository\. - + Expand **Additional configuration\.** + + Expand **Additional configuration**\. + Select **Rebuild every time a code change is pushed to this repository** to rebuild every time a code change is pushed to this repository\. - + Select **Enable insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. + + Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise project repository\. **Note** We recommend that you use **Enable insecure SSL** for testing only\. It should not be used in a production environment\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) @@ -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/) + + 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*\. 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\. @@ -82,20 +82,20 @@ When you use the console to create or update a build project, you can create a C + 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 CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. + For more information, see [Use AWS CodeBuild with Amazon Virtual Private Cloud](vpc-support.md)\. 1. For **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)\. + 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 build output artifacts, choose **No artifacts**\. - + To store the build output in an Amazon S3 bucket, choose **Amazon S3**, and then do the following: + + 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)\. + + 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. For **Cache type**, choose one of the following: + If you do not want to use a cache, choose **No cache**\. @@ -108,11 +108,11 @@ Do not append a trailing slash \(/\) to the end of the path prefix\. **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 CodeBuild](build-caching.md)\. + 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. Choose **Create build project**\. On the build project page, choose **Start build**\. -1. If you enabled webhooks in **Source**, then a **Create webhook** dialog box is displayed with values for **Payload URL** and **Secret**\. +1. If you enabled webhooks in **Source**, a **Create webhook** dialog box is displayed with values for **Payload URL** and **Secret**\. **Important** The **Create webhook** dialog box appears only once\. Copy the payload URL and secret key\. You need them when you add a webhook in GitHub Enterprise\. If you need to generate a payload URL and secret key again, you must first delete the webhook from your GitHub Enterprise repository\. In your CodeBuild project, clear the **Webhook** check box and then choose **Save**\. You can then create or update a CodeBuild project with the **Webhook** check box selected\. The **Create webhook** dialog box appears again\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 0cdc021..1216bd8 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -1,11 +1,11 @@ -# GitHub Pull Request and Webhook Filter Sample for CodeBuild +# GitHub pull request and webhook filter sample for CodeBuild -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 enable CodeBuild to rebuild the source code every time a code change is pushed to the repository\. +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)\. + 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)\. -## Create a Build Project with GitHub as the Source Repository and Enable Webhooks \(Console\) +## Create a build project with GitHub as the source repository and enable webhooks \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -24,7 +24,7 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 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. 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**\. +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. In **Environment**: @@ -32,7 +32,7 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 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/) + + 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*\. 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\. @@ -44,20 +44,20 @@ When you use the console to create or update a build project, you can create a C + 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)\. + 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 build output artifacts, choose **No artifacts**\. - + To store the build output in an Amazon S3 bucket, choose **Amazon S3**, and then do the following: + + 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)\. + + 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\. 1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. -## Verification Checks +## Verification checks 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -71,16 +71,13 @@ When you use the console to create or update a build project, you can create a C 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 AWS Region has been authorized\. +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 +## 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\. -**Note** -Filter groups work the same way in GitHub and GitHub Enterprise\. - 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) @@ -90,17 +87,18 @@ Filter groups work the same way in GitHub and GitHub Enterprise\. + `ACTOR_ACCOUNT_ID` \(`ACTOR_ID` in the console\): A webhook event triggers a build when a GitHub or GitHub Enterprise 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 and GitHub Enterprise push events only\. + + `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 push events\. It cannot be used with GitHub Enterprise 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 push events\. It cannot be used with GitHub Enterprise 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\)](#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\) +### Filter GitHub webhook events \(console\) To use the AWS Management Console to filter webhook events: @@ -114,7 +112,7 @@ Filter groups work the same way in GitHub and GitHub Enterprise\. 1. Choose **Add filter group** to add another filter group\. - For more information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. + For more information, see [Create a build project \(console\)](create-project.md#create-project-console) 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: @@ -134,14 +132,18 @@ In this example, a webhook filter group triggers a build only when files with na ![\[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 user with account ID that matches the regular expression `actor-account-id`\. +In this example, a webhook filter group triggers a build only when a change is made by a specified GitHub or GitHub Enterprise 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/) -### Filter GitHub Webhook Events \(SDK\) +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*\. @@ -209,7 +211,7 @@ To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` fi ] ``` - 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\. +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": [ @@ -246,11 +248,29 @@ You can create a filter that triggers a build only when a change is made by a sp ] ``` -### Filter GitHub Webhook Events \(AWS CloudFormation\) +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 a 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 that does not have account ID `12345`\. + 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: @@ -285,4 +305,8 @@ CodeBuildProject: - 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/sample-lambda.md b/doc_source/sample-lambda.md index ad6c073..5c780bb 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -1,12 +1,12 @@ -# AWS Lambda Sample for CodeBuild +# AWS Lambda sample for CodeBuild -To define a standard model for serverless applications that use resources such as Lambda, AWS created the AWS Serverless Application Model \(AWS SAM\)\. For more information, see the [AWS Serverless Application Model](https://github.com/awslabs/serverless-application-model) repository on GitHub\. +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 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 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*\. -## Related Resources -+ For more information about getting started with AWS CodeBuild, see [Getting Started with CodeBuild in the Console](getting-started.md)\. -+ For more information about troubleshooting problems with CodeBuild, see [Troubleshooting CodeBuild](troubleshooting.md)\. -+ For more information about limits in CodeBuild, see [Limits for CodeBuild](limits.md)\. \ No newline at end of file +## Related resources ++ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. ++ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. ++ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ 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 ff62a49..b01d1b9 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -1,18 +1,18 @@ -# Multiple Input Sources and Output Artifacts Sample +# Multiple input sources and output artifacts sample You can create an AWS CodeBuild build project with more than one input source and more than one set of output artifacts\. This sample shows you how to set up a build project that: + Uses multiple sources and repositories of varying types\. -+ Publishes build artifacts to multiple Amazon S3 buckets in a single build\. ++ Publishes build artifacts to multiple S3 buckets in a single build\. In this sample, you create a build project and use it to run a build\. The sample uses the build project's buildspec file to show you how to incorporate more than one source and create more than one set of artifacts\. -1. Upload your sources to one or more Amazon S3 buckets, CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repositories\. +1. Upload your sources to one or more S3 buckets, CodeCommit, GitHub, GitHub Enterprise, 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. Create a build project\. For more information, see [Create a Build Project in CodeBuild](create-project.md) +1. Create a build project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md)\. -1. Follow the instructions in [Run AWS CodeBuild Directly](how-to-run.md) to create your build project, run the build, and get information about the build\. +1. Follow the instructions in [Run AWS CodeBuild directly](how-to-run.md) to create your build project, run the build, and get information about the build\. 1. If you use the AWS CLI to create the build project, the JSON\-formatted input to the `create-project` command might look similar to the following: @@ -57,7 +57,7 @@ You can create an AWS CodeBuild build project with more than one input source an } ``` - Your primary source is defined under the `source` attribute\. All other sources are called secondary sources and appear under `secondarySources`\. All secondary sources are installed in their own directory\. This directory is stored in the built\-in environment variable `CODEBUILD_SRC_DIR_sourceIdentifer`\. For more information, see [Environment Variables in Build Environments](build-env-ref-env-vars.md)\. + Your primary source is defined under the `source` attribute\. All other sources are called secondary sources and appear under `secondarySources`\. All secondary sources are installed in their own directory\. This directory is stored in the built\-in environment variable `CODEBUILD_SRC_DIR_sourceIdentifer`\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. The `secondaryArtifacts` attribute contains a list of artifact definitions\. These artifacts use the `secondary-artifacts` block of the buildspec file that is nested inside the `artifacts` block\. @@ -114,9 +114,9 @@ artifacts: } ``` -## Project Without a Source Sample +## Project without a source sample - You can configure a AWS CodeBuild project by choosing the **NO\_SOURCE** source type when you configure your source\. When your source type is **NO\_SOURCE**, you cannot specify a buildspec file because your project does not have a source\. Instead, you must specify a YAML\-formatted buildspec string in the `buildspec` attribute of the JSON\-formatted input to the `create-project` CLI command\. It might look like this: + You can configure a CodeBuild project by choosing the **NO\_SOURCE** source type when you configure your source\. When your source type is **NO\_SOURCE**, you cannot specify a buildspec file because your project does not have a source\. Instead, you must specify a YAML\-formatted buildspec string in the `buildspec` attribute of the JSON\-formatted input to the `create-project` CLI command\. It might look like this: ``` { @@ -135,6 +135,6 @@ artifacts: } ``` -For more information, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. +For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. -To learn how to to create a pipeline that uses multiple source inputs to CodeBuild to create multiple output artifacts, see [ 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-multi-input-output.md b/doc_source/sample-pipeline-multi-input-output.md index 37b0841..a940f6b 100644 --- a/doc_source/sample-pipeline-multi-input-output.md +++ b/doc_source/sample-pipeline-multi-input-output.md @@ -1,8 +1,8 @@ -# CodePipeline Integration with CodeBuild and Multiple Input Sources and Output Artifacts Sample +# AWS CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample -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)\. +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)\. + 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*\. ``` { @@ -102,8 +102,8 @@ An AWS CodeBuild project can take more than one input source\. It can also creat In this JSON file: + 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)\. ++ 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)\. + ``` @@ -128,4 +128,4 @@ An AWS CodeBuild project can take more than one input source\. It can also creat - source2_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)\. \ No newline at end of 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-private-registry.md b/doc_source/sample-private-registry.md index 3330116..5b292b3 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -1,17 +1,17 @@ -# Private Registry with AWS Secrets Manager Sample for CodeBuild +# Private registry with AWS Secrets Manager sample for CodeBuild This sample shows you how to use a Docker image that is stored in a private registry as your AWS CodeBuild runtime environment\. The credentials for the private registry are stored in AWS Secrets Manager\. Any private registry works with CodeBuild\. This sample uses Docker Hub\. -## Private Registry Sample Requirements +## Private registry sample requirements To use a private registry with AWS CodeBuild, you must have the following: -+ An Secrets Manager secret that stores your Docker Hub credentials\. The credentials are used to access your private repository\. ++ A Secrets Manager secret that stores your Docker Hub credentials\. The credentials are used to access your private repository\. + A private repository or account\. + A CodeBuild service role IAM policy that grants access to your Secrets Manager secret\. Follow these steps to create these resources and then create a CodeBuild build project using the Docker images stored in your private registry\. -## Create a CodeBuild Project with a Private Registry +## Create a CodeBuild project with a private registry 1. For information about how to create a free private repository, see [Repositories on Docker Hub](https://docs.docker.com/docker-hub/repos/)\. You can also run the following commands in a terminal to pull an image, get its ID, and push it to a new repository\. @@ -40,12 +40,12 @@ 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)\. +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*\. 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/) -1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. +1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project.md#create-project-console)\. **Note** If your private registry is in your VPC, it must have public internet access\. CodeBuild cannot pull an image from a private IP address in a VPC\. @@ -57,4 +57,4 @@ 1. In **Other location**, enter the image location and the ARN or name of your Secrets Manager credentials\. **Note** - If your credentials do not exist in your current region, then you must use the ARN\. You cannot use the credential name if they exist in a different region\. \ No newline at end of file + If your credentials do not exist in your current Region, then you must use the ARN\. You cannot use the credential name if the credentials exist in a different Region\. \ No newline at end of file diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 43ebcc4..ef18016 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -1,11 +1,11 @@ -# Runtime Versions in Buildspec File Sample for CodeBuild +# 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, then your build must run in privileged mode\. For more information, see [Run a Build in CodeBuild](run-build.md) and [Create a Build Project in 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 +## 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: @@ -61,7 +61,7 @@ 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\. @@ -102,14 +102,14 @@ `-- pom.xml ``` -1. Upload the contents of the `my-web-app` directory to an Amazon 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 Amazon 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`\. +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`\. 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.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -118,7 +118,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co 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: @@ -167,7 +167,7 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co [Container] Date Time Running command for tool_path in "$JAVA_11_HOME"/bin/* "$JRE_11_HOME"/bin/*; ``` -## Specify a Runtime Dependency +## 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\. @@ -175,11 +175,11 @@ The build project in this example uses source code in the GitHub [AWS Samples](h 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.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Source provider**, choose **GitHub**\. + For **Repository**, choose **Public repository**\. - + For **Repository URL**, type **https://github\.com/aws\-samples/aws\-mobile\-android\-notes\-tutorial**\. + + For **Repository URL**, enter **https://github\.com/aws\-samples/aws\-mobile\-android\-notes\-tutorial**\. + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. + For **Runtime\(s\)**, choose **Standard**\. @@ -211,7 +211,7 @@ The build project in this example uses source code in the GitHub [AWS Samples](h 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: @@ -224,7 +224,7 @@ The build project in this example uses source code in the GitHub [AWS Samples](h Installing Java version 8 ... ``` -## Specify Two Runtimes +## 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\. @@ -322,13 +322,13 @@ The build project in this example uses source code in the GitHub [AWS Samples](h |-- buildspec.yml ``` -1. Upload the contents of the `my-source` directory to an Amazon S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. +1. Upload the contents of the `my-source` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. **Important** - If you are using an Amazon 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 `my-source` to the ZIP file, just the directories and files in `my-source`\. + 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 `my-source` to the ZIP file, just the directories and files in `my-source`\. 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.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index 680ccf5..e79fc76 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -1,6 +1,6 @@ -# Source Version Sample with CodeBuild +# Source version sample with AWS CodeBuild - This sample demonstrates how to specify a version of your source using a format other than a commit ID \(also known as a commit SHA\)\. You can specify the version of your source the following ways: + This sample demonstrates how to specify a version of your source using a format other than a commit ID \(also known as a commit SHA\)\. You can specify the version of your source in the following ways: + For an Amazon S3 source provider, use the version ID of the object that represents the build input ZIP file\. + For CodeCommit, Bitbucket, GitHub, and GitHub Enterprise, use one of the following: + Pull request as a pull request reference \(for example, `refs/pull/1/head`\)\. @@ -15,20 +15,18 @@ **Note** You can specify the version of a pull request source only if your repository is GitHub or GitHub Enterprise\. - 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 only the version\. This is because when you add a reference, CodeBuild does not need to download the entire repository to find the commit\. + 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\. \. **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 with a lower Git clone depth\. - - \. +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\. **To specify a GitHub repository version with a commit ID** 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 information, see [Create a Build Project \(Console\)](create-project.md#create-project-console) and [Run a Build \(Console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings: +1. Create a build project\. For information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings: + In **Source**: + For **Source provider**, choose **GitHub**\. If you are not connected to GitHub, follow the instructions to connect\. + For **Repository**, choose **Public repository**\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 63e6979..d331c4f 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -1,25 +1,25 @@ -# Create a Test Report in CodeBuild Using the AWS CLI Sample +# Create a test report in CodeBuild using the AWS CLI sample | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - Tests that you specify in your buildspec file are run during your build\. This sample shows you how to use the AWS CLI to incorporate tests into builds in CodeBuild\. \. You can use JUnit to create unit tests, or you can use another tool to create configuration tests\. You can then evaluate the test results to fix issues or optimize your application\. + Tests that you specify in your buildspec file are run during your build\. This sample shows you how to use the AWS CLI to incorporate tests into builds in CodeBuild\. You can use JUnit to create unit tests, or you can use another tool to create configuration tests\. You can then evaluate the test results to fix issues or optimize your application\. You can use the CodeBuild API or the AWS CodeBuild console to access the test results\. This sample shows you how to configure your report so its test results are exported to an S3 bucket\. **Topics** + [Prerequisites](#sample-test-report-cli-prerequisites) -+ [Create a Report Group](#sample-test-report-cli-create-report) -+ [Configure a Project with a Report Group](#sample-test-report-cli-create-project-with-report) -+ [Run and View Results of a Report](#sample-test-report-cli-run-and-view-report-results) ++ [Create a report group](#sample-test-report-cli-create-report) ++ [Configure a project with a report group](#sample-test-report-cli-create-project-with-report) ++ [Run and view results of a report](#sample-test-report-cli-run-and-view-report-results) ## Prerequisites + 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 format of your test cases can be JUnit XML, Cucumber JSON, Visual Studio TRX, or TestNG XML\. Create your test cases with any test framework that can create test files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and 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*\. -+ Make a note of the ARN of the IAM role you use\. You need the ARN when you create your build project\. -+ If your role does not have the following permissions, add them\. ++ Create an IAM role and make a note of its ARN\. You need the ARN when you create your build project\. ++ If your role does not have the following permissions, add them\. ``` { @@ -36,9 +36,9 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re } ``` - For more information, see [Permissions for Test Reporting Operations](test-permissions.md#test-permissions-related-to-reporting)\. + For more information, see [Permissions for test reporting operations](test-permissions.md#test-permissions-related-to-reporting)\. -## Create a Report Group +## Create a report group 1. Create a file named `CreateReportGroupInput.json`\. @@ -68,7 +68,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re --region your-region ``` - The output looks like the following\. Make a note of the report group ARN\. You use it when you create a project that uses this report group\. + 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\. ``` { @@ -91,7 +91,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re } ``` -## Configure a Project with a Report Group +## 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\. @@ -118,7 +118,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re 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\. @@ -154,7 +154,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re --region your-region ``` -## Run and View Results of a Report +## 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\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index aaab7e8..35808ae 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -1,20 +1,20 @@ -# Microsoft Windows Samples for CodeBuild +# Microsoft Windows samples for CodeBuild -These samples use an AWS CodeBuild build environment running Microsoft Windows Server 2016, the Microsoft \.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 2016, the \.NET Framework, and the \.NET Core SDK to build executables file out of code written in C\#, F\#, and Visual Basic\. **Important** -Running these samples may 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)\. +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)\. -## Running the Samples +## Running the samples -To run these samples: +**To run these samples** -1. Create the files as described in the Directory Structure and Files sections of this topic, and then upload them to an Amazon S3 input bucket or a CodeCommit or GitHub repository\. +1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or a CodeCommit or GitHub repository\. **Important** Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. -If you are using an Amazon 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)`\. +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, run the build, and follow 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\.\) @@ -41,17 +41,17 @@ If you are using an Amazon S3 input bucket, be sure to create a ZIP file that co } ``` -1. To get the build output artifact, in your Amazon 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 Microsoft \.NET Framework, `CSharpHelloWorld.exe`, can be found in the `CSharpHelloWorld\bin\Debug` directory\. - + The executable file for the F\# sample using the Microsoft \.NET Framework, `FSharpHelloWorld.exe`, can be found in the `FSharpHelloWorld\bin\Debug` directory\. - + The executable file for the Visual Basic sample using the Microsoft \.NET Framework, `VBHelloWorld.exe`, can be found in the `VBHelloWorld\bin\Debug` directory\. +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\netcoreapp1.0` directory\. -## Directory Structure +## Directory structure These samples assume the following directory structures\. -### C\# and the Microsoft \.NET Framework +### C\# and the \.NET Framework ``` (root directory name) @@ -65,7 +65,7 @@ These samples assume the following directory structures\. `-- AssemblyInfo.cs ``` -### F\# and the Microsoft \.NET Framework +### F\# and the \.NET Framework ``` (root directory name) @@ -78,7 +78,7 @@ These samples assume the following directory structures\. `-- Program.fs ``` -### Visual Basic and the Microsoft \.NET Framework +### Visual Basic and the \.NET Framework ``` (root directory name) @@ -109,9 +109,9 @@ These samples assume the following directory structures\. ## Files -These samples use the following files: +These samples use the following files\. -### C\# and the Microsoft \.NET Framework +### C\# and the \.NET Framework `buildspec.yml` \(in `(root directory name)`\): @@ -299,7 +299,7 @@ using System.Runtime.InteropServices; [assembly: AssemblyFileVersion("1.0.0.0")] ``` -### F\# and the Microsoft \.NET Framework +### F\# and the \.NET Framework `buildspec.yml` \(in `(root directory name)`\): @@ -499,7 +499,7 @@ let main argv = 0 // return an integer exit code ``` -### Visual Basic and the Microsoft \.NET Framework +### Visual Basic and the \.NET Framework `buildspec.yml` \(in `(root directory name)`\): diff --git a/doc_source/samples.md b/doc_source/samples.md index 39adb2d..95bf6a0 100644 --- a/doc_source/samples.md +++ b/doc_source/samples.md @@ -1,4 +1,4 @@ -# CodeBuild Samples +# CodeBuild samples These use case\-based samples can be used to experiment with AWS CodeBuild: @@ -7,23 +7,23 @@ | Name | Description | | --- | --- | -| [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\. | -| [Private Registry with AWS Secrets Manager Sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment\. The private registry credentials are stored in Secrets Manager\. | -| [Create a Test Report in CodeBuild Using the AWS CLI Sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | -| [Docker Sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | -| [Amazon EFS Sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | -| [GitHub Enterprise Sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [GitHub Pull Request and Webhook Filter Sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [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\. | -| [Use AWS Config with AWS CodeBuild Sample](how-to-integrate-config.md) | Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. | -| [ Host Build Output in an Amazon S3 Bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an Amazon S3 bucket using unencrypted build artifacts\. | -| [ Access Token Sample ](sample-access-tokens.md) | Shows how to use access tokens in CodeBuild to connect to GitHub and Bitbucket\. | -| [ Multiple Input Sources and Output Artifacts Sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | -| [ 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\. | -| [Build Badges Sample](sample-build-badges.md) | Shows how to set up CodeBuild with build badges\. | -| [Using Semantic Versioning to Name Build Artifacts Sample](sample-buildspec-artifact-naming.md) | Shows how to use semantic versioning to create an artifact name at build time\. | -| [Build Notifications Sample](sample-build-notifications.md) | Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. | -| [Docker in Custom Image Sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | -| [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 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\. | -| [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\. | \ No newline at end of file +| [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\. | +| [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\. | +| [Amazon EFS sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | +| [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\. | +| [Build badges sample](sample-build-badges.md) | Shows how to set up CodeBuild with build badges\. | +| [Build notifications sample](sample-build-notifications.md) | Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. | +| [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) | Shows how to use AWS CodePipeline to create a build with multiple input sources and multiple output artifacts\. | +| [ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. | +| [Create a test report in CodeBuild using the AWS CLI sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | +| [Docker in custom image sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | +| [Docker sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | +| [GitHub Enterprise sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | +| [GitHub pull request and webhook filter sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | +| [ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | +| [Private registry with AWS Secrets Manager sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment\. The private registry credentials are stored in Secrets Manager\. | +| [AWS Config sample](how-to-integrate-config.md) | Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. | +| [ Access token sample ](sample-access-tokens.md) | Shows how to use access tokens in CodeBuild to connect to GitHub and Bitbucket\. | +| [Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) | Shows how to use semantic versioning to create an artifact name at build time\. | \ No newline at end of file diff --git a/doc_source/sdk-ref.md b/doc_source/sdk-ref.md index 07bbdeb..fcbadee 100644 --- a/doc_source/sdk-ref.md +++ b/doc_source/sdk-ref.md @@ -1,10 +1,10 @@ -# AWS SDKs and Tools Reference for CodeBuild +# AWS SDKs and tools reference for AWS CodeBuild -To use one the AWS SDKs or tools to automate CodeBuild, see the following resources\. +To use one the AWS SDKs or tools to automate AWS CodeBuild, see the following resources\. -If you want to use the AWS CLI to run CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +If you want to use the AWS CLI to run CodeBuild, see the [Command line reference](cmd-ref.md)\. -## Supported AWS SDKs and Tools for CodeBuild +## Supported AWS SDKs and tools for AWS CodeBuild The following AWS SDKs and tools support CodeBuild: + The [AWS SDK for C\+\+](https://aws.amazon.com/sdk-for-cpp)\. For more information, see the [Aws::CodeBuild](http://sdk.amazonaws.com/cpp/api/LATEST/namespace_aws_1_1_code_build.html) namespace section of the *AWS SDK for C\+\+ API Reference*\. diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 52f27c5..db68b35 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -1,10 +1,10 @@ -# Data Encryption +# 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 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.md#encryptionkey-console) and [Set the Encryption Key Using the CLI](create-project.md#encryptionkey-cli)\. 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 TSL 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/)\. ++ **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 KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file diff --git a/doc_source/security-incident-response.md b/doc_source/security-incident-response.md index 71870e7..70cc362 100644 --- a/doc_source/security-incident-response.md +++ b/doc_source/security-incident-response.md @@ -1,7 +1,7 @@ -# Logging and Monitoring in AWS CodeBuild +# Logging and monitoring in AWS CodeBuild - Monitoring is an important part of maintaining the reliability, availability, and performance of AWS CodeBuild and your AWS solutions\. You should collect monitoring data from all of the parts of your AWS solution so that you can more easily debug a multi\-point failure, if one occurs\. AWS provides the following tools for monitoring your CodeBuild resources and builds and for responding to potential incidents: + Monitoring is an important part of maintaining the reliability, availability, and performance of AWS CodeBuild and your AWS solutions\. You should collect monitoring data from all of the parts of your AWS solution so that you can more easily debug a multi\-point failure, if one occurs\. AWS provides the following tools for monitoring your CodeBuild resources and builds and for responding to potential incidents\. **Topics** -+ [Logging CodeBuild API Calls with AWS CloudTrail](cloudtrail.md) ++ [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md) + [Monitoring AWS CodeBuild](monitoring-builds.md) \ No newline at end of file diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index 4fd6776..225c9be 100644 --- a/doc_source/security-key-management.md +++ b/doc_source/security-key-management.md @@ -1,7 +1,7 @@ -# Key Management +# 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 CodeBuild](create-project.md), [Run a Build in 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 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)\. - 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` 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)\. - 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 77fe65e..79e0a6e 100644 --- a/doc_source/security-traffic-privacy.md +++ b/doc_source/security-traffic-privacy.md @@ -1,3 +1,3 @@ -# Traffic Privacy +# 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 809f4c7..8edf32c 100644 --- a/doc_source/security.md +++ b/doc_source/security.md @@ -7,9 +7,9 @@ Security and compliance is a shared responsibility between AWS and you\. This sh To learn how to secure your CodeBuild resources, see the following topics\. **Topics** -+ [Data Protection in AWS CodeBuild](data-protection.md) -+ [Identity and Access Management in CodeBuild](auth-and-access-control.md) -+ [Logging and Monitoring in AWS CodeBuild](security-incident-response.md) -+ [Compliance Validation for AWS CodeBuild](codebuild-compliance-validation.md) ++ [Data protection in AWS CodeBuild](data-protection.md) ++ [Identity and access management in AWS CodeBuild](auth-and-access-control.md) ++ [Logging and monitoring in AWS CodeBuild](security-incident-response.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) \ No newline at end of file diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index b6d6ace..d9820ea 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -1,16 +1,16 @@ -# Advanced Setup +# Advanced setup -If you follow the steps in [Getting Started in the Console](getting-started.md) to access AWS CodeBuild for the first time, most likely you will not need to reference the information in this topic\. However, as you continue using CodeBuild, you will 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 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\. 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) -+ [Install and Configure the AWS CLI](#setting-up-cli) ++ [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) ++ [Install and configure the AWS CLI](#setting-up-cli) -## Add CodeBuild Access Permissions to an IAM Group or IAM User +## Add CodeBuild access permissions to an IAM group or IAM user To access AWS CodeBuild with an IAM group or IAM user, you must add access permissions\. This section describes how to do this with the IAM console or the AWS CLI\. @@ -45,8 +45,8 @@ For information about AWS root accounts and administrator IAM users, see [The Ac 1. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip ahead to step 4 in this procedure\. To add a default set of CodeBuild access permissions to an IAM group or IAM user, choose **Policy Type**, **AWS Managed**, and then do the following: - + To add full access permissions to CodeBuild, select the box named **AWSCodeBuildAdminAccess**\. Then choose **Policy Actions**, **Attach**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policies named **AmazonS3ReadOnlyAccess** and **IAMFullAccess**\. - + To add access permissions to CodeBuild for everything except build project administration, select the box named **AWSCodeBuildDeveloperAccess**\. Then choose **Policy Actions**, **Attach**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policy named **AmazonS3ReadOnlyAccess**\. + + To add full access permissions to CodeBuild, select the box named **AWSCodeBuildAdminAccess**, choose **Policy Actions**, and then choose **Attach**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policies named **AmazonS3ReadOnlyAccess** and **IAMFullAccess**\. + + To add access permissions to CodeBuild for everything except build project administration, select the box named **AWSCodeBuildDeveloperAccess**, choose **Policy Actions**, and then choose **Attach**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policy named **AmazonS3ReadOnlyAccess**\. + To add read\-only access permissions to CodeBuild, select the boxes named **AWSCodeBuildReadOnlyAccess**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policy named **AmazonS3ReadOnlyAccess**\. You have now added a default set of CodeBuild access permissions to an IAM group or IAM user\. Skip the rest of the steps in this procedure\. @@ -55,9 +55,9 @@ For information about AWS root accounts and administrator IAM users, see [The Ac 1. On the **Create Policy** page, next to **Create Your Own Policy**, choose **Select**\. -1. On the **Review Policy** page, for **Policy Name**, type a name for the policy \(for example, **CodeBuildAccessPolicy**\)\. If you use a different name, substitute it throughout this procedure\. +1. On the **Review Policy** page, for **Policy Name**, enter a name for the policy \(for example, **CodeBuildAccessPolicy**\)\. If you use a different name, be sure to use it throughout this procedure\. -1. For **Policy Document**, type the following, and then choose **Create Policy**\. +1. For **Policy Document**, enter the following, and then choose **Create Policy**\. ``` { @@ -105,13 +105,13 @@ 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)\. 1. In the navigation pane, choose **Groups** or **Users**\. 1. In the list of groups or users, choose the name of the IAM group or IAM user to which you want to add CodeBuild access permissions\. -1. For a group, on the group settings page, on the **Permissions** tab, expand **Managed Policies**, and choose **Attach Policy**\. +1. For a group, on the group settings page, on the **Permissions** tab, expand **Managed Policies**, and then choose **Attach Policy**\. For a user, on the user settings page, on the **Permissions** tab, choose **Add permissions**\. @@ -123,7 +123,7 @@ This policy allows access to all CodeBuild actions and to a potentially large nu 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, as described in the previous procedure\. 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. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip ahead to step 3 in this procedure\. +1. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip to step 3 in this procedure\. To add a default set of CodeBuild access permissions to an IAM group or IAM user, do the following: @@ -149,7 +149,7 @@ This policy allows access to all CodeBuild actions and to a potentially large nu You have now added a default set of CodeBuild access permissions to an IAM group or IAM user\. Skip the rest of the steps in this procedure\. -1. In an empty directory on the local workstation or instance where the AWS CLI is installed, create a file named `put-group-policy.json` or `put-user-policy.json`\. If you use a different file name, substitute it throughout this procedure\. +1. In an empty directory on the local workstation or instance where the AWS CLI is installed, create a file named `put-group-policy.json` or `put-user-policy.json`\. If you use a different file name, be sure to use it throughout this procedure\. ``` { @@ -197,9 +197,9 @@ 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\. -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, substitute them here\. +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\. For an IAM group: @@ -215,18 +215,18 @@ This policy allows access to all CodeBuild actions and to a potentially large nu In the preceding commands, replace *group\-name* or *user\-name* with the name of the target IAM group or IAM user\. -## Create a CodeBuild Service Role +## Create a CodeBuild service role 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.md#create-project-console) -+ [Create a Pipeline That Uses CodeBuild \(CodePipeline Console\)](how-to-create-pipeline.md#how-to-create-pipeline-console) -+ [Add an 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 build project \(console\)](create-project.md#create-project-console) ++ [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) 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)\. +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)\. **To create a CodeBuild service role \(console\)** @@ -260,7 +260,7 @@ The service role described on this page contains a policy that grants the minimu 1. On the **Create Policy** page, choose **JSON**\. -1. For the JSON Policy, type the following, and then choose **Review Policy**: +1. For the JSON policy, enter the following, and then choose **Review Policy**: ``` { @@ -347,25 +347,25 @@ The service role described on this page contains a policy that grants the minimu **Note** This policy contains statements that allow access to a potentially large number of AWS resources\. To restrict AWS CodeBuild to access specific AWS resources, change the value of the `Resource` array\. For more information, see the security documentation for the AWS service\. -1. On the **Review Policy** page, for **Policy Name**, type a name for the policy \(for example, **CodeBuildServiceRolePolicy**\), and then choose **Create policy**\. +1. On the **Review Policy** page, for **Policy Name**, enter a name for the policy \(for example, **CodeBuildServiceRolePolicy**\), and then choose **Create policy**\. **Note** -If you use a different name, substitute it throughout this procedure\. +If you use a different name, be sure to use it throughout this procedure\. 1. In the navigation pane, choose **Roles**\. 1. Choose **Create role**\. -1. On the **Create role** page, with **AWS Service** already selected, choose **CodeBuild**, as the service that will use this role, and then choose **Next:Permissions**\. +1. On the **Create role** page, with **AWS Service** already selected, choose **CodeBuild**, and then choose **Next:Permissions**\. 1. On the **Attach permissions policies** page, select **CodeBuildServiceRolePolicy**, and then choose **Next: Review**\. -1. On the **Create role and review** page, for **Role name**, type a name for the role \(for example, **CodeBuildServiceRole**\), and then choose **Create role**\. +1. On the **Create role and review** page, for **Role name**, enter a name for the role \(for example, **CodeBuildServiceRole**\), and then choose **Create role**\. **To create a CodeBuild service role \(AWS CLI\)** 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, as described in the previous procedure\. 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. In an empty directory on the local workstation or instance where the AWS CLI is installed, create two files named `create-role.json` and `put-role-policy.json`\. If you choose different file names, substitute them throughout this procedure\. +1. In an empty directory on the local workstation or instance where the AWS CLI is installed, create two files named `create-role.json` and `put-role-policy.json`\. If you choose different file names, be sure to use them throughout this procedure\. `create-role.json`: @@ -450,7 +450,7 @@ If you use a different name, substitute it throughout this procedure\. **Note** This policy contains statements that allow access to a potentially large number of AWS resources\. To restrict AWS CodeBuild to access specific AWS resources, change the value of the `Resource` array\. For more information, see the security documentation for the AWS service\. -1. Switch to the directory where you saved the preceding files, and then run the following two commands, one at a time, in this order\. You can use different values for `CodeBuildServiceRole` and `CodeBuildServiceRolePolicy`, but be sure to substitute them here\. +1. Switch to the directory where you saved the preceding files, and then run the following two commands, one at a time, in this order\. You can use different values for `CodeBuildServiceRole` and `CodeBuildServiceRolePolicy`, but be sure to use them here\. ``` aws iam create-role --role-name CodeBuildServiceRole --assume-role-policy-document file://create-role.json @@ -460,7 +460,7 @@ 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 an AWS KMS CMK 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\. @@ -541,7 +541,7 @@ Your AWS root account\. This is not recommended\. For more information, see [The 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*\. -## Install and Configure the AWS CLI +## Install and configure the AWS CLI To access AWS CodeBuild, you can use the AWS CLI with—or instead of—the CodeBuild console, the CodePipeline console, or the AWS SDKs\. To install and configure the AWS CLI, 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*\. diff --git a/doc_source/stop-build.md b/doc_source/stop-build.md index 15966d8..7af0f19 100644 --- a/doc_source/stop-build.md +++ b/doc_source/stop-build.md @@ -1,13 +1,13 @@ -# Stop a Build in CodeBuild +# Stop a build in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to stop a build in AWS CodeBuild\. **Topics** -+ [Stop a Build \(Console\)](#stop-build-console) -+ [Stop a Build \(AWS CLI\)](#stop-build-cli) -+ [Stop a Build \(AWS SDKs\)](#stop-build-sdks) ++ [Stop a build \(console\)](#stop-build-console) ++ [Stop a build \(AWS CLI\)](#stop-build-cli) ++ [Stop a build \(AWS SDKs\)](#stop-build-sdks) -## Stop a Build \(Console\) +## Stop 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)\. @@ -20,7 +20,7 @@ You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to stop a build in AW 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 build \(for example, if the build process is already complete\), the **Stop** button is disabled or might not appear\. -## Stop a Build \(AWS CLI\) +## Stop a build \(AWS CLI\) + Run the stop\-build command: ``` @@ -29,13 +29,13 @@ If AWS CodeBuild cannot successfully stop a build \(for example, if the build pr In the preceding command, replace the following placeholder: + *id*: Required string\. The ID of the build to stop\. 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 Build IDs for a Build Project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) + + [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-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) If AWS CodeBuild successfully stops the build, the `buildStatus` value in the `build` object in the output is `STOPPED`\. If CodeBuild cannot successfully stop the build \(for example, if the build is already complete\), the `buildStatus` value in the `build` object in the output is the final build status \(for example, `SUCCEEDED`\)\. -## Stop a Build \(AWS SDKs\) +## Stop 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 +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 032a112..afb448d 100644 --- a/doc_source/test-permissions.md +++ b/doc_source/test-permissions.md @@ -1,4 +1,4 @@ -# Working with Test Report Permissions +# Working with test report permissions | | @@ -8,11 +8,11 @@ This topic describes important information about permissions related to test reporting\. **Topics** -+ [Create a Role for Test Reports](#test-permissions-required) -+ [Permissions for Test Reporting Operations](#test-permissions-related-to-reporting) -+ [Test Reporting Permissions Examples](#test-permissions-examples) ++ [Create a role for test reports](#test-permissions-required) ++ [Permissions for test reporting operations](#test-permissions-related-to-reporting) ++ [Test reporting permissions examples](#test-permissions-examples) -## Create a Role for Test Reports +## Create a role for test reports | | @@ -80,7 +80,7 @@ } ``` -## Permissions for Test Reporting Operations +## Permissions for test reporting operations | | @@ -99,9 +99,9 @@ + `ListReportsForReportGroup` + `UpdateReportGroup` -For more information, see [CodeBuild Permissions Reference](auth-and-access-control-permissions-reference.md)\. +For more information, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. -## Test Reporting Permissions Examples +## Test reporting permissions examples | | @@ -109,13 +109,13 @@ For more information, see [CodeBuild Permissions Reference](auth-and-access-cont | The test reporting feature is in preview release for CodeBuild and is subject to change\. | For information about sample policies related to test reporting, see the following: -+ [Allow a User to Get Information About Report Groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-report-group) -+ [Allow a User to Get Information About Reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-reports) -+ [Allow a User to Create a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-report-group) -+ [Allow a User to Delete a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report-group) -+ [Allow a User to Delete a Report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report) -+ [Allow a User to Get a List of Test Cases for a Report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-test-cases-for-report) -+ [Allow a User to Get a List of Report Groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-report-groups) -+ [Allow a User to Get a List of Reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports) -+ [Allow a User to Get a List of Reports for a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports-for-report-group) -+ [Allow a User to Change a Report Group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-change-report-group) \ No newline at end of file ++ [Allow a user to change a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-change-report-group) ++ [Allow a user to create a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-report-group) ++ [Allow a user to delete a report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report) ++ [Allow a user to delete a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report-group) ++ [Allow a user to get information about report groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-report-group) ++ [Allow a user to get information about reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-reports) ++ [Allow a user to get a list of report groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-report-groups) ++ [Allow a user to get a list of reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports) ++ [Allow a user to get a list of reports for a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports-for-report-group) ++ [Allow a user to get a list of test cases for a report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-test-cases-for-report) \ No newline at end of file diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md index f3722c8..2574943 100644 --- a/doc_source/test-report-group-create-buildspec.md +++ b/doc_source/test-report-group-create-buildspec.md @@ -1,11 +1,11 @@ -# Create a Report Group \(Buildspec\) +# Create a report group \(buildspec\) | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | -A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Update a Report Group](report-group-export-settings.md)\. +A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Update a report group](report-group-export-settings.md)\. **To create a report group using a buildspec file** @@ -21,8 +21,8 @@ A report group created using the buildspec does not export raw test result files base-directory: 'surefire/target/surefire-reports' ``` - For more information, see [Specify Test Files](report-group-test-cases.md) and [Reports Syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. + For more information, see [Specify test files](report-group-test-cases.md) and [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. -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. 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)\. \ No newline at end of file diff --git a/doc_source/test-report-group-create-cfn.md b/doc_source/test-report-group-create-cfn.md index 89658e9..bd79f8c 100644 --- a/doc_source/test-report-group-create-cfn.md +++ b/doc_source/test-report-group-create-cfn.md @@ -1,13 +1,13 @@ -# Create a Report Group \(AWS CloudFormation\) +# Create a report group \(AWS CloudFormation\) | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | - **To create a test report using the AWS CloudFormation template** + **To create a test report** - You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. + You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. The following AWS CloudFormation YAML template creates a report group that does not export raw test result files\. diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index 4a04459..b36b6a4 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -1,11 +1,11 @@ -# Create a Report Group \(CLI\) +# Create a report group \(CLI\) | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | -**To create a test report using the AWS CLI** +**To create a test report** + Create a file named `CreateReportGroup.json`\. 1. Depending on your requirements, copy one of the following JSON code snippets into `CreateReportGroup.json`: @@ -27,7 +27,7 @@ } ``` - 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 `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)\. + Use the following JSON to specify that your test report does not export raw test files: ``` diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index f0e9fc2..a1d2b33 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -1,11 +1,11 @@ -# Create a Report Group \(Console\) +# Create a report group \(console\) | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | -**To create a test report using the AWS CodeBuild console** +**To create a test report** 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -30,6 +30,6 @@ + **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\.\) - 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)\. 1. Choose **Create report group**\. \ No newline at end of file diff --git a/doc_source/test-report-group-naming.md b/doc_source/test-report-group-naming.md index b214cd6..aa5ad0c 100644 --- a/doc_source/test-report-group-naming.md +++ b/doc_source/test-report-group-naming.md @@ -1,4 +1,4 @@ -# Report Group Naming +# Report group naming | | diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md index 134cb7d..ab4c53e 100644 --- a/doc_source/test-report-group.md +++ b/doc_source/test-report-group.md @@ -1,4 +1,4 @@ -# Working with Report Groups +# Working with report groups | | @@ -12,9 +12,9 @@ A *report group* contains test reports and specifies shared settings\. You use t Report groups can be used in more than one build project\. All test reports created with one report group share the same configuration, such as its export option and permissions, even if the test reports are created using different build projects\. Test reports created with one report group in multiple build projects can contain the results from running different sets of test cases \(one set of test cases for each build project\)\. This is because you can specify different test case files for the report group in each project's buildspec file\. You can also change the test case files for a report group in a build project by editing its buildspec file\. Subsequent build runs create new test reports that contain the results of the test case files in the updated buildspec\. **Topics** -+ [Create a Report Group](report-group-create.md) -+ [Update a Report Group](report-group-export-settings.md) -+ [Specify Test Files](report-group-test-cases.md) -+ [Specify Test Commands](report-group-test-case-commands.md) -+ [Report Group Naming](test-report-group-naming.md) -+ [Working with Shared Report Groups](report-groups-sharing.md) \ No newline at end of file ++ [Create a report group](report-group-create.md) ++ [Update a report group](report-group-export-settings.md) ++ [Specify test files](report-group-test-cases.md) ++ [Specify test commands](report-group-test-case-commands.md) ++ [Report group naming](test-report-group-naming.md) ++ [Working with shared report groups](report-groups-sharing.md) \ No newline at end of file diff --git a/doc_source/test-report.md b/doc_source/test-report.md index 8252ea8..a3e6f4c 100644 --- a/doc_source/test-report.md +++ b/doc_source/test-report.md @@ -1,4 +1,4 @@ -# Working with Reports +# Working with reports | | @@ -7,14 +7,14 @@ A report contains the results of test cases that are specified for one report group\. A test report is created during the run of a build project\. You specify a report group, test case files, and commands to run the test cases in its buildspec file\. Each time the test cases run, a new test report is created in the report group\. - A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Update a Report Group](report-group-export-settings.md)\. + A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Update a report group](report-group-export-settings.md)\. The status of a test report can be one of the following: + `GENERATING`: The run of the test cases is still in progress\. + `DELETING`: The test report is being deleted\. When a test report is deleted, its test cases are also deleted\. Raw test result data files exported to an S3 bucket are not deleted\. + `INCOMPLETE`: The test report was not completed\. This status might be returned for one of the following reasons: + A problem with the configuration of the report group that specifies this report's test cases\. For example, the path to the test cases under the report group in the buildspec file might be incorrect\. - + The IAM user that ran the build does not have permissions to run tests\. For more information, see [Working with Test Report Permissions](test-permissions.md)\. + + The IAM user that ran the build does not have permissions to run tests\. For more information, see [Working with test report permissions](test-permissions.md)\. + The build was not completed because of an error that is not related to the tests\. + `SUCCEEDED`: All test cases were successful\. + `FAILED`: Some of the test cases were not successful\. diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index 31cb7c7..93a0c0d 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -1,11 +1,11 @@ -# Working with Test Reporting in CodeBuild +# Working with test reporting in AWS CodeBuild | | | --- | | The test reporting feature is in preview release for CodeBuild and is subject to change\. | -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 test file format can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. +You can create reports in AWS 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 test file format can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. @@ -14,8 +14,8 @@ You can use a test report to help troubleshoot a problem during a build run\. If A report expires 30 days after it was created\. You cannot view an expired test report\. If you want to keep test reports for more than 30 days, you can export your test results' raw data files to an S3 bucket\. Exported test files do not expire\. Information about the S3 bucket is specified when you create the report group\. **Topics** -+ [Create a Test Report](report-create.md) -+ [Working with Report Groups](test-report-group.md) -+ [Working with Reports](test-report.md) -+ [Working with Test Report Permissions](test-permissions.md) -+ [View Test Reports](test-view-reports.md) \ No newline at end of file ++ [Create a test report](report-create.md) ++ [Working with report groups](test-report-group.md) ++ [Working with reports](test-report.md) ++ [Working with test report permissions](test-permissions.md) ++ [View test reports](test-view-reports.md) \ No newline at end of file diff --git a/doc_source/test-view-reports.md b/doc_source/test-view-reports.md index 492fee3..5f394ce 100644 --- a/doc_source/test-view-reports.md +++ b/doc_source/test-view-reports.md @@ -1,4 +1,4 @@ -# View Test Reports +# View test reports | | @@ -10,11 +10,11 @@ You can see view test reports that are not expired\. Test reports expire 30 days after they are created\. You cannot view an expired report in CodeBuild\. **Topics** -+ [View Test Reports for a Build](#test-view-project-reports) -+ [View Test Reports for a Report Group](#test-view-report-group-reports) -+ [View Test Reports in Your AWS Account](#test-view-account-reports) ++ [View test reports for a build](#test-view-project-reports) ++ [View test reports for a report group](#test-view-report-group-reports) ++ [View test reports in your AWS account](#test-view-account-reports) -## View Test Reports for a Build +## View test reports for a build | | @@ -37,7 +37,7 @@ 1. In the build page, choose **Reports**, and then choose a test report to see its details\. -## View Test Reports for a Report Group +## View test reports for a report group | | @@ -54,7 +54,7 @@ 1. Choose a test report to see its details\. -## View Test Reports in Your AWS Account +## View test reports in your AWS account | | diff --git a/doc_source/trigger-create.md b/doc_source/trigger-create.md index 2c09fef..0eefff9 100644 --- a/doc_source/trigger-create.md +++ b/doc_source/trigger-create.md @@ -1,4 +1,4 @@ -# Create CodeBuild Triggers +# 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\. @@ -20,16 +20,16 @@ By default, the 100 most recent build projects are displayed\. To view more buil 1. From the **Frequency** drop\-down list, choose the frequency for your trigger\. If you want to create a frequency using a cron expression, choose **Custom**\. -1. Specify the parameters for the frequency of your trigger\. You can type the first few characters of your selections in the text box to filter drop\-down menu items\. +1. Specify the parameters for the frequency of your trigger\. You can enter the first few characters of your selections in the text box to filter drop\-down menu items\. **Note** Start hours and minutes are zero\-based\. The start minute is a number between zero and 59\. The start hour is a number between zero and 23\. For example, a daily trigger that starts every day at 12:15 P\.M\. has a start hour of 12 and a start minute of 15\. A daily trigger that starts every day at midnight has a start hour of zero and a start minute of zero\. A daily trigger that starts every day at 11:59 P\.M\. has a start hour of 23 and a start minute of 59\. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/trigger-create.html) -1. Select **Enable this trigger** to enable the trigger\. +1. Select **Enable this trigger**\. 1. \(Optional\) Expand **Advanced section**\. In **Source version**, type a version of your source\. - + For Amazon S3, type the version ID that corresponds to the version of the input artifact you want to build\. If **Source version** is left blank, the latest version is used\. + + For Amazon S3, enter the version ID that corresponds to the version of the input artifact you want to build\. If **Source version** is left blank, the latest version is used\. + For AWS CodeCommit, type a commit ID\. If **Source version** is left blank, the default branch's HEAD commit ID is used\. + For GitHub or GitHub Enterprise, type a commit ID, a pull request ID, a branch name, or a tag name that corresponds to 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\. + For Bitbucket, type a commit ID, a branch name, or a tag name that corresponds to 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\. diff --git a/doc_source/triggers-edit.md b/doc_source/triggers-edit.md index ab92730..ba32512 100644 --- a/doc_source/triggers-edit.md +++ b/doc_source/triggers-edit.md @@ -1,8 +1,8 @@ -# Edit CodeBuild Triggers +# 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 CodeBuild Triggers](trigger-create.md)\. + 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: +**To edit a trigger** 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -16,13 +16,13 @@ By default, the 100 most recent build projects are displayed\. To view more buil 1. From the **Frequency** drop\-down list, choose the frequency for your trigger\. If you want to create a frequency using a cron expression, choose **Custom**\. -1. Specify the parameters for the frequency of your trigger\. You can type the first few characters of your selections in the text box to filter drop\-down menu items\. +1. Specify the parameters for the frequency of your trigger\. You can enter the first few characters of your selections in the text box to filter drop\-down menu items\. **Note** Start hours and minutes are zero\-based\. The start minute is a number between zero and 59\. The start hour is a number between zero and 23\. For example, a daily trigger that starts every day at 12:15 P\.M\. has a start hour of 12 and a start minute of 15\. A daily trigger that starts every day at midnight has a start hour of zero and a start minute of zero\. A daily trigger that starts every day at 11:59 P\.M\. has a start hour of 23 and a start minute of 59\. **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/triggers-edit.html) -1. Select **Enable this trigger** to enable the trigger\. +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 diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 7e9a941..e234a64 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -1,160 +1,42 @@ -# Troubleshooting CodeBuild +# Troubleshooting AWS CodeBuild -Use the information in this topic to help you identify, diagnose, and address issues\. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see [Logging and Monitoring](security-incident-response.md)\. +Use the information in this topic to help you identify, diagnose, and address issues\. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see [Logging and monitoring](security-incident-response.md)\. **Topics** -+ [Error: "CodeBuild is not authorized to perform: sts:AssumeRole" when creating or updating a build project](#troubleshooting-assume-role) ++ [Apache Maven builds reference artifacts from the wrong repository](#troubleshooting-maven-repos) ++ [Build commands run as root by default](#troubleshooting-root-build-commands) ++ [Builds might fail when file names have non\-U\.S\. English characters](#troubleshooting-utf-8) ++ [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) ++ [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) -+ [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: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build](#troubleshooting-input-bucket-different-region) -+ [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) -+ [Error: "Unable to Locate Credentials"](#troubleshooting-versions) -+ [Earlier Commands in Buildspec Files Are Not Recognized by Later Commands](#troubleshooting-build-spec-commands) -+ [Apache Maven Builds Reference Artifacts from the Wrong Repository](#troubleshooting-maven-repos) -+ [Build Commands Run as root by Default](#troubleshooting-root-build-commands) -+ [The Bourne Shell \(sh\) Must Exist in Build Images](#troubleshooting-sh-build-images) + [Error: "CodeBuild is experiencing an issue" when running a build](#troubleshooting-large-env-vars) -+ [Error: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image](#troubleshooting-unable-to-pull-image) -+ [Builds Might Fail When File Names Have Non\-U\.S\. English Characters](#troubleshooting-utf-8) -+ [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) -+ ["Access denied" error message when attempting to download cache](#troubleshooting-dependency-caching) -+ [Error: "Unable to download cache: RequestError: send request failed caused by: x509: failed to load system roots and no roots provided"](#troubleshooting-cache-image) -+ [Error: "Unable to download certificate from S3\. AccessDenied"](#troubleshooting-certificate-in-S3) -+ [Error: "Git Clone Failed: unable to access `'your-repository-URL'`: SSL certificate problem: self signed certificate"](#troubleshooting-self-signed-certificate) ++ [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) ++ [Error: "Git clone failed: Unable to access `'your-repository-URL'`: SSL certificate problem: Self signed certificate"](#troubleshooting-self-signed-certificate) ++ [Error: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build](#troubleshooting-input-bucket-different-region) + [Error: "The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation\."](#enhanced-zero-click-role-creation) -+ [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) -+ [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) -+ [RequestError timeout error when running CodeBuild in a proxy server](#code-request-timeout-error) ++ [Error: "This build image requires selecting at least one runtime version\."](#troubleshooting-build-must-specify-runtime) + [Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails](#queued-insufficient-subnet-error) ++ [Error: "Unable to download cache: RequestError: Send request failed caused by: x509: Failed to load system roots and no roots provided"](#troubleshooting-cache-image) ++ [Error: "Unable to download certificate from S3\. AccessDenied"](#troubleshooting-certificate-in-S3) ++ [Error: "Unable to locate credentials"](#troubleshooting-versions) ++ [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: "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 following error: "Code:InvalidInputException, Message:CodeBuild is not authorized to perform: sts:AssumeRole on arn:aws:iam::*account\-ID*:role/*service\-role\-name*"\. - - **Possible causes:** -+ The AWS Security Token Service \(AWS STS\) has been deactivated for the AWS region where you are attempting to create or update the build project\. -+ The AWS CodeBuild service role associated with the build project does not exist or does not have sufficient permissions to trust CodeBuild\. - - **Recommended solutions:** -+ Make sure AWS STS is activated for the AWS region where you are attempting to create or update the build project\. For more information, see [Activating and Deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) in the *IAM User Guide*\. -+ Make sure the target CodeBuild service role exists in your AWS account\. If you are not using the console, make sure you did not misspell the Amazon Resource Name \(ARN\) of the service role when you created or updated the build project\. -+ Make sure the target CodeBuild service role has sufficient permissions to trust CodeBuild\. For more information, see the trust relationship policy statement in [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. - -## Error: "Cannot connect to the Docker daemon" when running a build - -**Issue: **Your build fails and you receive an error similar to `Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running?` in the build log\. - -**Possible cause: **You are not running your build in privileged mode\. - -**Recommended solution: ** Run your build in privileged mode: - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In the navigation pane, choose **Build projects**, and then choose your build project\. - -1. From **Edit**, choose **Environment**\. - -1. Choose **Override images**, and then choose **Environment**\. - -1. Specify your environment image, operating system, runtime, and image\. These should match your settings for the build that failed\. - -1. Select **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\. - -1. Choose **Update environment**\. - -1. Choose **Start build** to retry your build\. - -## Warning: "Skipping install of runtimes\. Runtime version selection is not supported by this build image" when running a build - -**Issue:** When you run a build, the build log contains the warning, "Skipping install of runtimes\. Runtime version selection is not supported by this build image\." - -**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\. - -## Error: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build - -**Issue:** When you run a build, the `DOWNLOAD_SOURCE` build phase fails with the error "The bucket you are attempting to access must be addressed using the specified endpoint\. Please send all future requests to this endpoint\." - -**Possible cause:** Your pre\-built source code is stored in an Amazon S3 bucket, and that bucket is in a different AWS region than the AWS CodeBuild build project\. - -**Recommended solution:** Update the build project's settings to point to a bucket that contains your pre\-built source code, and that bucket is in the same region as the build project\. - -## Error: "error calling GetBucketAcl: either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl" - -**Issue:** When you run a build, you receive an error about a change in ownership of an Amazon 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 Amazon S3 bucket and ensure that only you can access it\. After adding these permissions, the owner of the Amazon S3 bucket changed\. - -**Recommended solution:** Verify you are an owner of the Amazon S3 bucket, and then add permissions to your IAM role again\. For more information, see [Secure Access to Amazon S3 Buckets](auth-and-access-control-iam-access-control-identity-based.md#secure-s3-buckets)\. - -## Error: "Failed to upload artifacts: Invalid arn" when running a build - -**Issue:** When you run a build, the `UPLOAD_ARTIFACTS` build phase fails with the error "Failed to upload artifacts: Invalid arn"\. - -**Possible cause:** Your Amazon S3 output bucket \(the bucket where AWS CodeBuild stores its output from the build\) is in a different AWS region than the CodeBuild build project\. - -**Recommended solution:** Update the build project's settings to point to an output bucket that is in the same region as the build project\. - -## Error: "Unable to Locate Credentials" - -**Issue:** When you try to run the AWS CLI, use an AWS SDK, or call another similar component as part of a build, you get build errors that are directly related to the AWS CLI, AWS SDK, or component\. For example, you may get a build error such as "unable to locate credentials\." - - **Possible causes:** -+ The version of the AWS CLI, AWS SDK, or component in the build environment is incompatible with AWS CodeBuild\. -+ You are running a Docker container within a build environment that uses Docker, and that Docker container does not have access to the necessary AWS credentials by default\. - - **Recommended solutions:** -+ Make sure your build environment has the following version or higher of the AWS CLI, AWS SDK, or component\. - + AWS CLI: 1\.10\.47 - + AWS SDK for C\+\+: 0\.2\.19 - + AWS SDK for Go: 1\.2\.5 - + AWS SDK for Java: 1\.11\.16 - + AWS SDK for JavaScript: 2\.4\.7 - + AWS SDK for PHP: 3\.18\.28 - + AWS SDK for Python \(Boto3\): 1\.4\.0 - + AWS SDK for Ruby: 2\.3\.22 - + Botocore: 1\.4\.37 - + CoreCLR: 3\.2\.6\-beta - + Node\.js: 2\.4\.7 -+ If you need to run a Docker container in a build environment and that container requires AWS credentials, you must pass through the credentials from the build environment to the container\. In your buildspec file, include a Docker `run` command such as the following, which in this example uses the `aws s3 ls` command to list your available Amazon S3 buckets\. The `-e` option passes through the necessary environment variables for your container to access AWS credentials\. - - ``` - docker run -e AWS_DEFAULT_REGION -e AWS_CONTAINER_CREDENTIALS_RELATIVE_URI your-image-tag aws s3 ls - ``` -+ If you are building a Docker image and the build requires AWS credentials \(for example, to download a file from Amazon S3\), you must pass through the credentials from the build environment to the Docker build process as follows\. - - 1. In your source code's Dockerfile for the Docker image, specify the following `ARG` instructions\. - - ``` - ARG AWS_DEFAULT_REGION - ARG AWS_CONTAINER_CREDENTIALS_RELATIVE_URI - ``` - - 1. In your buildspec file, include a Docker `build` command such as the following\. The `--build-arg` options will set the necessary environment variables for your Docker build process to access the AWS credentials\. - - ``` - docker build --build-arg AWS_DEFAULT_REGION=$AWS_DEFAULT_REGION --build-arg AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI -t your-image-tag . - ``` - -## Earlier Commands in Buildspec Files Are Not Recognized by Later Commands - -**Issue:** The results of one or more commands in your buildspec file are not recognized by later commands in the same buildspec file\. For example, a command might set a local environment variable, but a command run later might fail to get the value of that local environment variable\. - -**Possible cause:** In buildspec file version 0\.1, AWS CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. By default, then, you cannot run a single command that relies on the state of any previous commands\. - -**Recommended solutions:** We recommend you use build spec version 0\.2, which solves this issue\. If you must use buildspec version 0\.1 for some reason, we recommend using the shell command chaining operator \(for example, `&&` in Linux\) to combine multiple commands into a single command\. Or include a shell script in your source code that contains multiple commands, and then call that shell script from a single command in the buildspec file\. For more information, see [Shells and Commands in Build Environments](build-env-ref-cmd.md) and [Environment Variables in Build Environments](build-env-ref-env-vars.md)\. - -## Apache Maven Builds Reference Artifacts from the Wrong Repository +## Apache Maven builds reference artifacts from the wrong repository -**Issue:** When you use Maven with an AWS CodeBuild provided Java build environment, Maven pulls build and plugin dependencies from the secure central Maven repository at [https://repo1\.maven\.org/maven2](https://repo1.maven.org/maven2)\. This happens even if your build project's `pom.xml` file explicitly declares other locations to use instead\. +**Issue:** When you use Maven with an AWS CodeBuild\-provided Java build environment, Maven pulls build and plugin dependencies from the secure central Maven repository at [https://repo1\.maven\.org/maven2](https://repo1.maven.org/maven2)\. This happens even if your build project's `pom.xml` file explicitly declares other locations to use instead\. -**Possible cause:** CodeBuild provided Java build environments include a file named `settings.xml` that is preinstalled in the build environment's `/root/.m2` directory\. This `settings.xml` file contains the following declarations, which instruct Maven to always pull build and plugin dependencies from the secure central Maven repository at [https://repo1\.maven\.org/maven2](https://repo1.maven.org/maven2)\. +**Possible cause:** CodeBuild\-provided Java build environments include a file named `settings.xml` that is preinstalled in the build environment's `/root/.m2` directory\. This `settings.xml` file contains the following declarations, which instruct Maven to always pull build and plugin dependencies from the secure central Maven repository at [https://repo1\.maven\.org/maven2](https://repo1.maven.org/maven2)\. ``` @@ -204,53 +86,21 @@ By default, Docker containers do not allow access to any devices\. Privileged mo - cp ./settings.xml /root/.m2/settings.xml ``` -## Build Commands Run as root by Default +## Build commands run as root by default **Issue:** AWS CodeBuild runs your build commands as the root user\. This happens even if your related build image's Dockerfile sets the `USER` instruction to a different user\. -**Cause:** CodeBuild runs all build commands as the root user by default\. +**Cause:** By default, CodeBuild runs all build commands as the root user\. **Recommended solution:** None\. -## The Bourne Shell \(sh\) Must Exist in Build Images - -**Issue:** You are using a build image that is not provided by AWS CodeBuild, and your builds fail with the message "build container found dead before completing the build\." - -**Possible cause:**The Bourne shell \(`sh`\) is not included in your build image\. CodeBuild needs `sh` to run build commands and scripts\. - -**Recommended solution:** If `sh` in not present in your build image, be sure to include it before you start any more builds that use your image\. \(CodeBuild already includes `sh` in its build images\.\) - -## Error: "CodeBuild is experiencing an issue" when running a build - -**Issue:** When you try to run a build project, you receive the following error during the build's `PROVISIONING` phase: "CodeBuild is experiencing an issue\." - -**Possible cause:** Your build is using environment variables that are too large for AWS CodeBuild\. CodeBuild can raise errors once 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)\. +## Builds might fail when file names have non\-U\.S\. English characters -## Error: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image +**Issue:** When you run a build that uses files with file names that contain non\-U\.S\. English characters \(for example, Chinese characters\), the build fails\. -**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 cause:** Build environments provided by AWS CodeBuild have their default locale set to `POSIX`\. `POSIX` localization settings are less compatible with CodeBuild and file names that contain non\-U\.S\. English characters and can cause related builds to fail\. - **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 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)\. - - **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 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\. - -## Builds Might Fail When File Names Have Non\-U\.S\. English Characters - -**Issue:** When you run a build that uses files with file names containing non\-US English characters \(for example, Chinese characters\), the build fails\. - -**Possible cause:** : Build environments provided by AWS CodeBuild have their default locale set to `POSIX`\. `POSIX` localization settings are less compatible with CodeBuild and file names that contain non\-US English characters and can cause related builds to fail\. - -**Recommended solution:** Add the following commands to the `pre_build` section of your buildspec file\. These commands make the build environment use US English UTF\-8 for its localization settings, which is more compatible with CodeBuild and file names that contain non\-US English characters\. +**Recommended solution:** Add the following commands to the `pre_build` section of your buildspec file\. These commands make the build environment use U\.S\. English UTF\-8 for its localization settings, which is more compatible with CodeBuild and file names that contain non\-U\.S\. English characters\. For build environments based on Ubuntu: @@ -270,9 +120,9 @@ pre_build: - export LC_ALL="en_US.utf8" ``` -## Builds Might Fail When Getting Parameters from Amazon EC2 Parameter Store +## Builds might fail when getting parameters from Amazon EC2 Parameter Store -**Issue:** When a build tries to get the value of one or more parameters stored in Amazon EC2 Parameter Store, the build fails in the `DOWNLOAD_SOURCE` phase with the following error: "Parameter does not exist\." +**Issue:** When a build tries to get the value of one or more parameters stored in Amazon EC2 Parameter Store, the build fails in the `DOWNLOAD_SOURCE` phase with the error `Parameter does not exist`\. **Possible cause:** The service role the build project relies on does not have permission to call the `ssm:GetParameters` action or the build project uses a service role that is generated by AWS CodeBuild and allows calling the `ssm:GetParameters` action, but the parameters have names that do not start with `/CodeBuild/`\. @@ -306,70 +156,185 @@ pre_build: } ``` -## Cannot Access Branch Filter in the CodeBuild Console +## Cannot access branch filter in the CodeBuild console **Issue:** The branch filter option is not available in the console when you create or update an AWS CodeBuild project\. - **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 CodeBuild 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)\. + +## Cannot view build success or failure + +**Issue:** You cannot see the success or failure of a retried 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)\. + +## Cannot view build success or failure + +**Issue:** You cannot see the success or failure of a retried 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) in the *AWS CodeBuild API Reference*\. + +## Cannot find and 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 2016 platform\. + +**Possible cause:** You are using an AWS Region that does not support this image\. -**Recommended solution:** To migrate a branch filter created prior to the introduction of webhook filters, create a webhook filter groups 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 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\) + +## Earlier commands in buildspec files are not recognized by later commands + +**Issue:** The results of one or more commands in your buildspec file are not recognized by later commands in the same buildspec file\. For example, a command might set a local environment variable, but a command run later might fail to get the value of that local environment variable\. + +**Possible cause:** In buildspec file version 0\.1, AWS CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. By default, then, you cannot run a single command that relies on the state of any previous commands\. + +**Recommended solutions:** We recommend that you use build spec version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend that you use the shell command chaining operator \(for example, `&&` in Linux\) to combine multiple commands into a single command\. Or include a shell script in your source code that contains multiple commands, and then call that shell script from a single command in the buildspec file\. For more information, see [Shells and commands in build environments](build-env-ref-cmd.md) and [Environment variables in build environments](build-env-ref-env-vars.md)\. -## "Access denied" error message when attempting to download cache +## Error: "Access denied" when attempting to download cache -**Issue:** When attempting to download the cache on a build project that has cache enabled, you receive the following generic error: "Access denied"\. +**Issue:** When attempting to download the cache on a build project that has cache enabled, you receive an `Access denied` error\. **Possible causes:** + You have just configured caching as part of your build project\. -+ The cache has recently been invalidated via the `InvalidateProjectCache` API\. -+ The service role being used by CodeBuild does not have `s3:GetObject` and `s3:PutObject` permissions to the Amazon S3 bucket that is holding the cache\. ++ The cache has recently been invalidated through the `InvalidateProjectCache` API\. ++ The service role being used by CodeBuild does not have `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. -**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the Amazon S3 bucket that is holding the cache\. For more information, see [Specifying S3 permissions\.](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html) +**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. For more information, see [Specifying S3 Permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html) in the *Amazon S3 Developer Guide*\. -## Error: "Unable to download cache: RequestError: send request failed caused by: x509: failed to load system roots and no roots provided" +## Error: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image -**Issue:** When you try to run a build project, the build fails with the error: "RequestError: send request failed caused by: x509: failed to load system roots and no roots provided\." +**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 cause:** You configured caching as part of your build project and are using an older Docker image that includes an expired root certificate\. + **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)\. - **Recommended solution:** Update the Docker image that is being used in your AWS CodeBuild the project\. For more information, see [Docker Images Provided by CodeBuild](build-env-ref-available.md)\. + **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\. -## Error: "Unable to download certificate from S3\. AccessDenied" +## 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" -**Issue:** When you try to run a build project, the build fails with the error "Unable to download certificate from S3\. AccessDenied"\. + **Issue:** When you try to use a Microsoft Windows or Linux container in AWS CodeBuild, this error occurs during the PROVISIONING phase\. **Possible causes:** -+ You have chosen the wrong S3 bucket for your certificate\. -+ You have entered the wrong object key for your certificate\. ++ The container OS version is not supported by CodeBuild\. ++ `HTTP_PROXY`, `HTTPS_PROXY`, or both are specified in the container\. **Recommended solutions:** -+ Edit your project\. For **Bucket of certificate**, choose the S3 bucket where your TSL certificate is stored\. -+ Edit your project\. For **Object key of certificate**, type the name of your S3 object key\. ++ For Microsoft Windows, use a Windows container with a container OS that is version microsoft/windowsservercore:10\.0\.x \(for example, microsoft/windowsservercore:10\.0\.14393\.2125\)\. ++ For Linux, clear the `HTTP_PROXY` and `HTTPS_PROXY` settings in your Docker image, or specify the VPC configuration in your build project\. + +## Error: "Cannot connect to the Docker daemon" when running a build + +**Issue:** Your build fails and you receive an error similar to `Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running?` in the build log\. -## Error: "Git Clone Failed: unable to access `'your-repository-URL'`: SSL certificate problem: self signed certificate" +**Possible cause:** You are not running your build in privileged mode\. -**Issue:** When you try to run a build project, the build fails with the error "Git Clone Failed: unable to access `'your-repository-URL'`: SSL certificate problem: self signed certificate\." +**Recommended solution:** Follow these steps to run your build in privileged mode: + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In the navigation pane, choose **Build projects**, and then choose your build project\. + +1. From **Edit**, choose **Environment**\. + +1. Choose **Override images**, and then choose **Environment**\. + +1. Specify your environment image, operating system, runtime, and image\. These settings should match the settings for the build that failed\. + +1. Select **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\. + +1. Choose **Update environment**\. + +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`\. + + **Possible causes:** ++ The AWS Security Token Service \(AWS STS\) has been deactivated for the AWS region where you are attempting to create or update the build project\. ++ The AWS CodeBuild service role associated with the build project does not exist or does not have sufficient permissions to trust CodeBuild\. + + **Recommended solutions:** ++ Make sure AWS STS is activated for the AWS region where you are attempting to create or update the build project\. For more information, see [Activating and Deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) in the *IAM User Guide*\. ++ Make sure the target CodeBuild service role exists in your AWS account\. If you are not using the console, make sure you did not misspell the Amazon Resource Name \(ARN\) of the service role when you created or updated the build project\. ++ Make sure the target CodeBuild service role has sufficient permissions to trust CodeBuild\. For more information, see the trust relationship policy statement in [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. + +## Error: "Error calling GetBucketAcl: Either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl" + +**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\. + +**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)\. + +## Error: "Failed to upload artifacts: Invalid arn" when running a build + +**Issue:** When you run a build, the `UPLOAD_ARTIFACTS` build phase fails with the error `Failed to upload artifacts: Invalid arn`\. + +**Possible cause:** Your S3 output bucket \(the bucket where AWS CodeBuild stores its output from the build\) is in an AWS Region different from the CodeBuild build project\. + +**Recommended solution:** Update the build project's settings to point to an output bucket that is in the same AWS Region as the build project\. + +## Error: "Git clone failed: Unable to access `'your-repository-URL'`: SSL certificate problem: Self signed certificate" + +**Issue:** When you try to run a build project, the build fails with this error\. **Possible cause:** Your source repository has a self\-signed certificate, but you have not chosen to install the certificate from your S3 bucket as part of your build project\. **Recommended solutions:** -+ Edit your project\. For **Certificate**, choose **Install certificate from S3**\. For **Bucket of certificate**, choose the S3 bucket where your TSL certificate is stored\. For **Object key of certificate**, type the name of your S3 object key\. ++ Edit your project\. For **Certificate**, choose **Install certificate from S3**\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. For **Object key of certificate**, enter the name of your S3 object key\. + Edit your project\. Select **Insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. **Note** We recommend that you use **Insecure SSL** for testing only\. It should not be used in a production environment\. +## Error: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build + +**Issue:** When you run a build, the `DOWNLOAD_SOURCE` build phase fails with the error `The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint`\. + +**Possible cause:** Your pre\-built source code is stored in an S3 bucket, and that bucket is in an AWS Region different from the AWS CodeBuild build project\. + +**Recommended solution:** Update the build project's settings to point to a bucket that contains your pre\-built source code\. Make sure that bucket is in the same AWS Region as the build project\. + ## Error: "The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation\." -**Issue:** When you try to update a project in the console, the update failed with the error: "The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation\." +**Issue:** When you try to update a project in the console, the update failed with this error: **Possible causes:** + You have updated the policies attached to the target AWS CodeBuild service role\. + You have selected an earlier version of a policy attached to the target CodeBuild service role\. **Recommended solutions:** -+ Edit your CodeBuild project and clear the **Allow CodeBuild to modify this service role so it can be used with this build project** check box\. Verify the CodeBuild service role you are using has sufficient permissions\. If you edit your CodeBuild project again, you must clear this check box again\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. -+ Edit your CodeBuild project to use a new service role: ++ Edit your CodeBuild project and clear the **Allow CodeBuild to modify this service role so it can be used with this build project** check box\. Verify the CodeBuild service role you are using has sufficient permissions\. If you edit your CodeBuild project again, you must clear this check box again\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. ++ Follow these steps to edit your CodeBuild project to use a new service role: - 1. Open the IAM console and create a new service role\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role) + 1. Open the IAM console and create a new service role\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -381,37 +346,107 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u 1. Choose **Update environment**\. -## 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" +## 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`\. - **Issue:** When you try to use a Microsoft Windows or Linux container in AWS CodeBuild an error occurs during the PROVISIONING phase\. +**Possible cause:** Your build uses 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 not specified in the buildspec file\. + +**Recommended solution:** If you use the `aws/codebuild/standard:2.0` CodeBuild managed image, you must specify a runtime version in the `runtime-versions` section of the buildspec file\. For example, you might use the following buildspec file for a project that uses PHP: + +``` +version: 0.2 + +phases: + install: + runtime-versions: + php: 7.3 + build: + commands: + - php --version +artifacts: + files: + - README.md +``` + +**Note** + 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`\." + + For more information, see [Specify runtime versions in the buildspec file](build-spec-ref.md#runtime-versions-buildspec-file)\. + +## Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails + +**Issue:** A build in a build queue fails with an error similar to `QUEUED: INSUFFICIENT_SUBNET`\. + +**Possible causes:** The IPv4 CIDR block specified for your VPC uses a reserved IP address\. The first four IP addresses and the last IP address in each subnet CIDR block are not available for you to use and cannot be assigned to an instance\. For example, in a subnet with CIDR block `10.0.0.0/24`, the following five IP addresses are reserved: ++ `10.0.0.0:` Network address\. ++ `10.0.0.1`: Reserved by AWS for the VPC router\. ++ `10.0.0.2`: Reserved by AWS\. The IP address of the DNS server is always the base of the VPC network range plus two; however, we also reserve the base of each subnet range plus two\. For VPCs with multiple CIDR blocks, the IP address of the DNS server is located in the primary CIDR\. For more information, see [Amazon DNS Server](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS) in the *Amazon VPC User Guide*\. ++ `10.0.0.3`: Reserved by AWS for future use\. ++ `10.0.0.255`: Network broadcast address\. We do not support broadcast in a VPC\. This address is reserved\. + +**Recommended solutions:** Check if your VPC uses a reserved IP address\. Replace any reserved IP address with one that is not reserved\. For more information, see [VPC and Subnet Sizing](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#VPC_Sizing) in the *Amazon VPC User Guide*\. + +## Error: "Unable to download cache: RequestError: Send request failed caused by: x509: Failed to load system roots and no roots provided" + +**Issue:** When you try to run a build project, the build fails with this error\. + + **Possible cause:** You configured caching as part of your build project and are using an older Docker image that includes an expired root certificate\. + + **Recommended solution:** Update the Docker image that is being used in your AWS CodeBuild the project\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. + +## Error: "Unable to download certificate from S3\. AccessDenied" + +**Issue:** When you try to run a build project, the build fails with this error\. **Possible causes:** -+ The Container OS version is not supported by CodeBuild\. -+ `HTTP_PROXY`, `HTTPS_PROXY`, or both are specified in the container\. ++ You have chosen the wrong S3 bucket for your certificate\. ++ You have entered the wrong object key for your certificate\. **Recommended solutions:** -+ For Microsoft Windows, use a Windows container with a Container OS that is version microsoft/windowsservercore:10\.0\.x\. For example, microsoft/windowsservercore:10\.0\.14393\.2125\. -+ For Linux, clear the `HTTP_PROXY` and `HTTPS_PROXY` settings in your Docker image, or specify the VPC configuration in you build project\. ++ Edit your project\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. ++ Edit your project\. For **Object key of certificate**, enter the name of your S3 object key\. -## Cannot view build success or failure +## Error: "Unable to locate credentials" -**Issue:** You cannot see the success or failure of a retried build\. +**Issue:** When you try to run the AWS CLI, use an AWS SDK, or call another similar component as part of a build, you get build errors that are directly related to the AWS CLI, AWS SDK, or component\. For example, you might get a build error such as `Unable to locate credentials`\. -**Possible cause:** The option to report your build's status is not enabled\. + **Possible causes:** ++ The version of the AWS CLI, AWS SDK, or component in the build environment is incompatible with AWS CodeBuild\. ++ You are running a Docker container within a build environment that uses Docker, and the container does not have access to the AWS credentials by default\. -**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:** ++ Make sure your build environment has the following version or higher of the AWS CLI, AWS SDK, or component\. + + AWS CLI: 1\.10\.47 + + AWS SDK for C\+\+: 0\.2\.19 + + AWS SDK for Go: 1\.2\.5 + + AWS SDK for Java: 1\.11\.16 + + AWS SDK for JavaScript: 2\.4\.7 + + AWS SDK for PHP: 3\.18\.28 + + AWS SDK for Python \(Boto3\): 1\.4\.0 + + AWS SDK for Ruby: 2\.3\.22 + + Botocore: 1\.4\.37 + + CoreCLR: 3\.2\.6\-beta + + Node\.js: 2\.4\.7 ++ If you need to run a Docker container in a build environment and the container requires AWS credentials, you must pass through the credentials from the build environment to the container\. In your buildspec file, include a Docker `run` command such as the following\. This example uses the `aws s3 ls` command to list your available S3 buckets\. The `-e` option passes through the environment variables required for your container to access AWS credentials\. -## Cannot find and select the base image of the Windows Server Core 2016 platform + ``` + docker run -e AWS_DEFAULT_REGION -e AWS_CONTAINER_CREDENTIALS_RELATIVE_URI your-image-tag aws s3 ls + ``` ++ If you are building a Docker image and the build requires AWS credentials \(for example, to download a file from Amazon S3\), you must pass through the credentials from the build environment to the Docker build process as follows\. -**Issue:** You cannot find or select the base image of the Windows Server Core 2016 platform\. + 1. In your source code's Dockerfile for the Docker image, specify the following `ARG` instructions\. -**Possible cause:** You are using a region that does not support this image\. + ``` + ARG AWS_DEFAULT_REGION + ARG AWS_CONTAINER_CREDENTIALS_RELATIVE_URI + ``` -**Recommended solutions:** Use one of the regions that supports the base image of the Windows Server Core 2016 platform: -+ US East \(N\. Virginia\) -+ US East \(Ohio\) -+ US East \(Ohio\) -+ US West \(N\. California\) + 1. In your buildspec file, include a Docker `build` command such as the following\. The `--build-arg` options sets the environment variables required for your Docker build process to access the AWS credentials\. + + ``` + docker build --build-arg AWS_DEFAULT_REGION=$AWS_DEFAULT_REGION --build-arg AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI -t your-image-tag . + ``` ## RequestError timeout error when running CodeBuild in a proxy server @@ -425,15 +460,15 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u + Your buildspec file does not have proxy settings specified using a `proxy` element\. **Recommended solutions:** -+ Make sure `ssl-bump` is configured properly\. If you use Squid for your proxy server, see [ Configure Squid as an Explicit Proxy Server](use-proxy-server.md#use-proxy-server-explicit-squid-configure)\. -+ Use private endpoints for Amazon S3 and CloudWatch Logs by doing the following: ++ Make sure `ssl-bump` is configured properly\. If you use Squid for your proxy server, see [ Configure Squid as an explicit proxy server](use-proxy-server.md#use-proxy-server-explicit-squid-configure)\. ++ Follow these steps to use private endpoints for Amazon S3 and CloudWatch Logs: - 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)\. + 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)\. + 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. 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)\. -+ 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)\. + 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)\. ``` version: 0.2 @@ -445,15 +480,18 @@ We recommend that you use **Insecure SSL** for testing only\. It should not be u commands: ``` -## Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails +## The bourne shell \(sh\) must exist in build images -**Issue:** A build in a build queue fails with an error similar to `QUEUED: INSUFFICIENT_SUBNET`\. +**Issue:** You are using a build image that is not provided by AWS CodeBuild, and your builds fail with the message `Build container found dead before completing the build`\. -**Possible causes:** The IPv4 CIDR block specified for your VPC uses a reserved IP address\. The first four IP addresses and the last IP address in each subnet CIDR block are not available for you to use and cannot be assigned to an instance\. For example, in a subnet with CIDR block `10.0.0.0/24`, the following five IP addresses are reserved: -+ `10.0.0.0:` Network address\. -+ `10.0.0.1`: Reserved by AWS for the VPC router\. -+ `10.0.0.2`: Reserved by AWS\. The IP address of the DNS server is always the base of the VPC network range plus two; however, we also reserve the base of each subnet range plus two\. For VPCs with multiple CIDR blocks, the IP address of the DNS server is located in the primary CIDR\. For more information, see [Amazon DNS Server](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS)\. -+ `10.0.0.3`: Reserved by AWS for future use\. -+ `10.0.0.255`: Network broadcast address\. We do not support broadcast in a VPC, therefore we reserve this address\. +**Possible cause:** The Bourne shell \(`sh`\) is not included in your build image\. CodeBuild needs `sh` to run build commands and scripts\. + +**Recommended solution:** If `sh` in not present in your build image, be sure to include it before you start any more builds that use your image\. \(CodeBuild already includes `sh` in its build images\.\) + +## Warning: "Skipping install of runtimes\. runtime version selection is not supported by this build image" when running a build + +**Issue:** When you run a build, the build log contains this warning\. + +**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 solutions:** Check if your VPC uses a reserved IP address\. Replace any reserved IP address with an IP address that is not reserved\. For more information, see [VPC and Subnet Sizing](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#VPC_Sizing)\. \ 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\. \ 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 4b30f86..2d19b29 100644 --- a/doc_source/update-report-group-cli.md +++ b/doc_source/update-report-group-cli.md @@ -1,4 +1,4 @@ -# Update a Report Group \(CLI\) +# Update a report group \(CLI\) **To update a report group** diff --git a/doc_source/update-report-group-console.md b/doc_source/update-report-group-console.md index c2a6d97..f89c282 100644 --- a/doc_source/update-report-group-console.md +++ b/doc_source/update-report-group-console.md @@ -1,4 +1,4 @@ -# Update a Report Group \(Console\) +# Update a report group \(console\) **To update a report group** diff --git a/doc_source/use-case-based-samples.md b/doc_source/use-case-based-samples.md index d0ee0d1..2bf1f55 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -1,4 +1,4 @@ -# CodeBuild Use Case\-Based Samples +# CodeBuild use case\-based samples You can use these use case\-based samples to experiment with AWS CodeBuild: @@ -7,25 +7,25 @@ You can use these use case\-based samples to experiment with AWS CodeBuild: | Name | Description | | --- | --- | -| [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\. | -| [Private Registry with AWS Secrets Manager Sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment when building with CodeBuild The private registry credentials are stored in AWS Secrets Manager\. | -| [Create a Test Report Using the AWS CLI Sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | -| [ Runtime Versions in Buildspec File Sample ](sample-runtime-versions.md) | Shows how to specify runtimes and their versions in the buildspec file\. This is a requirement when using the Ubuntu standard image version 2\.0\. | -| [Source Version Sample](sample-source-version.md) | Shows how to use a specific version of your source in a CodeBuild build project\. | -| [Docker Sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | -| [Amazon EFS Sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | -| [GitHub Enterprise Sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [GitHub Pull Request and Webhook Filter Sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [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\. | -| [Use AWS Config with AWS CodeBuild Sample](how-to-integrate-config.md) | Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. | -| [ Host Build Output in an Amazon S3 Bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an Amazon S3 bucket using unencrypted build artifacts\. | -| [ Access Token Sample ](sample-access-tokens.md) | Shows how to use access tokens in CodeBuild to connect to GitHub and Bitbucket\. | -| [ Multiple Input Sources and Output Artifacts Sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | -| [ 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\. | -| [Build Badges Sample](sample-build-badges.md) | Shows how to set up CodeBuild with build badges\. | -| [Using Semantic Versioning to Name Build Artifacts Sample](sample-buildspec-artifact-naming.md) | Shows how to use semantic versioning to create an artifact name at build time\. | -| [Build Notifications Sample](sample-build-notifications.md) | Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. | -| [Docker in Custom Image Sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | -| [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 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\. | -| [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\. | \ No newline at end of file +| [ 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\. | +| [Amazon EFS sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | +| [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) | 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) | Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. | +| [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\. | +| [Build badges sample](sample-build-badges.md) | Shows how to set up CodeBuild with build badges\. | +| [Build notifications sample](sample-build-notifications.md) | Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. | +| [Create a test report using the AWS CLI sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | +| [Docker in custom image sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | +| [Docker sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | +| [GitHub Enterprise sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | +| [GitHub pull request and webhook filter sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | +| [ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. | +| [ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | +| [Private registry with AWS Secrets Manager sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment when building with CodeBuild The private registry credentials are stored in AWS Secrets Manager\. | +| [ Runtime versions in buildspec file sample ](sample-runtime-versions.md) | Shows how to specify runtimes and their versions in the buildspec file\. This is a requirement when using the Ubuntu standard image version 2\.0\. | +| [Source version sample](sample-source-version.md) | Shows how to use a specific version of your source in a CodeBuild build project\. | +| [Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) | Shows how to use semantic versioning to create an artifact name at build time\. | \ No newline at end of file diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index b3eb2b9..757c6b3 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -1,10 +1,12 @@ -# Test and Debug Locally with the CodeBuild Agent +# Test and debug 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\. -## Test and Debug on a Local Machine with the CodeBuild Agent +## Test and debug on a local machine with the CodeBuild agent - You can use the AWS CodeBuild agent to test and debug builds on a local machine\. To use the agent: + You can use the AWS CodeBuild agent to test and debug builds on a local machine\. + +**To use the agent** 1. Download the [codebuild\.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) script\. @@ -20,44 +22,42 @@ docker inspect amazon/aws-codebuild-local ``` -## Receive Notifications for New CodeBuild Agent Versions +## Receive notifications for new CodeBuild agent versions - Amazon SNS can notify you when new versions of the AWS CodeBuild Agent are released\. Use the following procedure to subscribe to these notifications\. + 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 subscribe to the CodeBuild Agent notifications:** +**To subscribe to the 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 region to **US East \(N\. Virginia\)**\. You must select this region because the Amazon SNS notifications that you are subscribing to are created in this region\. +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 the **Create subscription** dialog box: +1. In **Create subscription**: - 1. For **Topic ARN**, use the following Amazon Resource Name \(ARN\): + For **Topic ARN**, use the following Amazon Resource Name \(ARN\): - ``` - arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates - ``` + ``` + arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates + ``` - 1. For **Protocol** choose **Email** or **SMS**\. + For **Protocol**, choose **Email** or **SMS**\. - 1. For **Endpoint** choose where to receive the notifications: - + If you choose **Email**, type an email address\. - + If you choose **SMS**, type a phone number, including area code\. + For **Endpoint**, choose where \(email or SMS\) to receive the notifications\. Enter an email or address or phone number, including area code\. - 1. Choose **Create subscription**\. + Choose **Create subscription**\. -1. If you choose **Email**, you'll receive an email asking you to confirm your subscription\. Follow the directions in the email to complete your 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\. - When a new version of the CodeBuild agent is released, subscribers receive notifications\. If you no longer want to receive these notifications, use the following procedure to unsubscribe\. + If you no longer want to receive these notifications, follow the steps in this procedure to unsubscribe\. - ** To unsubscribe from CodeBuild agent notifications:** +**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. In the navigation pane, choose **Subscriptions**\. -1. Select the subscription and then 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 95fe9ad..9c73d84 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -1,40 +1,40 @@ -# Use CodeBuild with a Proxy Server +# Use AWS CodeBuild with a proxy server - You can use AWS CodeBuild with a proxy server to regulate HTTP and HTTPS traffic to and from the internet\. To run CodeBuild with a proxy server, you install a proxy server in a public subnet and CodeBuild in a private subnet in an Amazon Virtual Private Cloud \(Amazon VPC\)\. + You can use AWS CodeBuild with a proxy server to regulate HTTP and HTTPS traffic to and from the internet\. To run CodeBuild with a proxy server, you install a proxy server in a public subnet and CodeBuild in a private subnet in a VPC\. There are two primary use cases for running CodeBuild in a proxy server: -+ It eliminates the use of a NAT gateway or NAT instance in your Amazon VPC\. ++ It eliminates the use of a NAT gateway or NAT instance in your VPC\. + 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 CodeBuild ](change-project.md) and [Create a Build Project in 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** -+ [Components Required to Run CodeBuild in a Proxy Server](#use-proxy-server-transparent-components) -+ [Run CodeBuild in an Explicit Proxy Server](#run-codebuild-in-explicit-proxy-server) -+ [Run CodeBuild in a Transparent Proxy Server](#run-codebuild-in-transparent-proxy-server) -+ [Run a Package Manager and Other Tools in a Proxy Server](#use-proxy-server-tools) ++ [Components required to run CodeBuild in a proxy server](#use-proxy-server-transparent-components) ++ [Run CodeBuild in an explicit proxy server](#run-codebuild-in-explicit-proxy-server) ++ [Run CodeBuild in a transparent proxy server](#run-codebuild-in-transparent-proxy-server) ++ [Run a package manager and other tools in a proxy server](#use-proxy-server-tools) -## Components Required to Run CodeBuild in a Proxy Server +## Components required to run CodeBuild in a proxy server You need these components to run AWS CodeBuild in a transparent or explicit proxy server: -+ An Amazon VPC\. -+ One public subnet in your Amazon VPC for the proxy server\. -+ One private subnet in your Amazon VPC for CodeBuild\. ++ A VPC\. ++ One public subnet in your VPC for the proxy server\. ++ One private subnet in your VPC for CodeBuild\. + An internet gateway that allows communcation between the VPC and the internet\. The following diagram shows how the components interact\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-proxy-transparent.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) -### Set Up a VPC, Subnets, and a Network Gateway +### Set up a VPC, subnets, and a network gateway The following steps are required to run AWS CodeBuild in a transparent or explicit proxy server\. -1. Create a VPC\. For information, see [Creating a VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC)\. +1. Create a VPC\. For information, see [Creating a VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC) in the *Amazon VPC User Guide*\. -1. Create two subnets in your VPC\. One is a public subnet named Public Subnet in which your proxy server runs\. The other is a private subnet named Private Subnet in which CodeBuild runs\. +1. Create two subnets in your VPC\. One is a public subnet named `Public Subnet` in which your proxy server runs\. The other is a private subnet named `Private Subnet` in which CodeBuild runs\. For information, see [Creating a Subnet in Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet)\. @@ -44,7 +44,7 @@ There are two primary use cases for running CodeBuild in a proxy server: 1. Add a rule to the default security group of your VPC that allows ingress SSH traffic \(TCP 22\) from your VPC \(0\.0\.0\.0/0\)\. -1. Follow the instructions in [Launching an Instance Using the Launch Instance Wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) to launch an Amazon Linux Amazon EC2 instance\. When you run the wizard, choose the following options: +1. Follow the instructions in [Launching an Instance Using the Launch Instance Wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) in the *Amazon EC2 User Guide* to launch an Amazon Linux instance\. When you run the wizard, choose the following options: + In **Choose an Instance Type**, choose an Amazon Linux Amazon Machine Image \(AMI\)\. + In **Subnet**, choose the public subnet you created earlier in this topic\. If you used the suggested name, it is **Public Subnet**\. + In **Auto\-assign Public IP**, choose **Enable**\. @@ -53,11 +53,11 @@ There are two primary use cases for running CodeBuild in a proxy server: Choose the default settings for all other options\. -1. After your Amazon EC2 instance is running, disable source/destination checks\. For information, see [Disabling Source/Destination Checks](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck)\. +1. After your EC2 instance is running, disable source/destination checks\. For information, see [Disabling Source/Destination Checks](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) in the *Amazon VPC User Guide*\. -1. Create a route table in your VPC\. Add a rule to the route table that routes traffic destined for the internet to your proxy server\. Associate this route table with your private subnet\. This is required so that outbound requests from instances in your private subnet, where CodeBuild runs, is always routed through the proxy server\. +1. Create a route table in your VPC\. Add a rule to the route table that routes traffic destined for the internet to your proxy server\. Associate this route table with your private subnet\. This is required so that outbound requests from instances in your private subnet, where CodeBuild runs, are always routed through the proxy server\. -### Install and Configure a Proxy Server +### Install and configure a proxy server There are many proxy servers from which to choose\. An open\-source proxy server, Squid, is used here to demonstrate how AWS CodeBuild runs in a proxy server\. You can apply the same concepts to other proxy servers\. @@ -68,11 +68,11 @@ sudo yum update -y sudo yum install -y squid ``` - After you install Squid, you edit its `squid.conf` file\. Instructions for editing this file are included later in this topic\. + After you install Squid, edit its `squid.conf` file using the instructions later in this topic\. -### Configure Squid for HTTPS Traffic +### Configure Squid for HTTPS traffic - For HTTPS, the HTTP traffic is encapsulated in a Transport Layer Security \(TLS\) connection\. Squid uses a feature called [SslPeekAndSplice](https://wiki.squid-cache.org/Features/SslPeekAndSplice) to retrieve the Server Name Indication \(SNI\) from the TSL initiation that contains the requested internet host\. This is required so Squid does not need to unencrypt HTTPS traffic\. To enable SslPeekAndSplice, Squid requires a certificate\. Create this certificate using OpenSSL: + For HTTPS, the HTTP traffic is encapsulated in a Transport Layer Security \(TLS\) connection\. Squid uses a feature called [SslPeekAndSplice](https://wiki.squid-cache.org/Features/SslPeekAndSplice) to retrieve the Server Name Indication \(SNI\) from the TLS initiation that contains the requested internet host\. This is required so Squid does not need to unencrypt HTTPS traffic\. To enable SslPeekAndSplice, Squid requires a certificate\. Create this certificate using OpenSSL: ``` sudo mkdir /etc/squid/ssl @@ -86,16 +86,16 @@ sudo cat squid.key squid.crt | sudo tee squid.pem **Note** For HTTP, Squid does not require configuration\. From all HTTP/1\.1 request messages, it can retrieve the host header field, which specifies the internet host that is being requested\. -## Run CodeBuild in an Explicit Proxy Server +## Run CodeBuild in an explicit proxy server **Topics** -+ [Configure Squid as an Explicit Proxy Server](#use-proxy-server-explicit-squid-configure) -+ [Create a CodeBuild Project](#use-proxy-server-explicit-create-acb-project) -+ [Explicit Proxy Server Sample `Squid.conf` File](#use-proxy-server-explicit-sample-squid-conf) ++ [Configure Squid as an explicit proxy server](#use-proxy-server-explicit-squid-configure) ++ [Create a CodeBuild project](#use-proxy-server-explicit-create-acb-project) ++ [Explicit proxy server sample `squid.conf` file](#use-proxy-server-explicit-sample-squid-conf) - To run AWS CodeBuild with in an explicit proxy server, you must configure the proxy server to allow or deny traffic to and from external sites, and then configure the `HTTP_PROXY` and `HTTPS_PROXY` environment variables\. + To run AWS CodeBuild in an explicit proxy server, you must configure the proxy server to allow or deny traffic to and from external sites, and then configure the `HTTP_PROXY` and `HTTPS_PROXY` environment variables\. -### Configure Squid as an Explicit Proxy Server +### Configure Squid as an explicit proxy server To configure the Squid proxy server to be explicit, you must make the following modifications to its `/etc/squid/squid.conf` file: + Remove the following default access control list \(ACL\) rules\. @@ -108,9 +108,9 @@ sudo cat squid.key squid.crt | sudo tee squid.pem acl localnet src fe80::/10 ``` - Add the following in place of the default ACL rules you removed\. The first line allows requests from your Amazon VPC\. The next two lines grant your proxy server access to destination URLs that might be used by AWS CodeBuild\. Modify the regular expression in the last line to specify Amazon S3 buckets or a CodeCommit repository in an AWS Region\. For example: - + If your source is Amazon S3, use the command acl download\_src dstdom\_regex \.\*s3\\\.us\-west\-1\\\.amazonaws\\\.comto grant access to Amazon S3 buckets in the `us-west-1` Region\. - + If your source is AWS CodeCommit, use `git-codecommit..amazonaws.com` to whitelist an AWS Region\. + Add the following in place of the default ACL rules you removed\. The first line allows requests from your VPC\. The next two lines grant your proxy server access to destination URLs that might be used by AWS CodeBuild\. Edit the regular expression in the last line to specify S3 buckets or a CodeCommit repository in an AWS Region\. For example: + + If your source is Amazon S3, use the command acl download\_src dstdom\_regex \.\*s3\\\.us\-west\-1\\\.amazonaws\\\.comto grant access to S3 buckets in the `us-west-1` Region\. + + If your source is AWS CodeCommit, use `git-codecommit..amazonaws.com` to add an AWS Region to an allow list\. ``` acl localnet src 10.1.0.0/16 #Only allow requests from within the VPC @@ -149,7 +149,7 @@ sudo cat squid.key squid.crt | sudo tee squid.pem sudo service squid restart ``` - 1. Add `proxy` to your buildspec file\. For more information, see [Buildspec Syntax](build-spec-ref.md#build-spec-ref-syntax)\. + 1. Add `proxy` to your buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. ``` version: 0.2 @@ -165,11 +165,11 @@ sudo cat squid.key squid.crt | sudo tee squid.pem **Note** If you receive a RequestError timeout error, see [ RequestError timeout error when running CodeBuild in a proxy server](troubleshooting.md#code-request-timeout-error)\. -For more information, see [Explicit Proxy Server Sample `Squid.conf` File](#use-proxy-server-explicit-sample-squid-conf) later in this topic\. +For more information, see [Explicit proxy server sample `squid.conf` file](#use-proxy-server-explicit-sample-squid-conf) later in this topic\. -### Create a CodeBuild Project +### 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 Amazon 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 CodeBuild](create-project.md) and [Change a Build Project's Settings in 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: @@ -177,9 +177,9 @@ For more information, see [Explicit Proxy Server Sample `Squid.conf` File](#use- sudo tail -f /var/log/squid/access.log ``` -### Explicit Proxy Server Sample `Squid.conf` File +### Explicit proxy server sample `squid.conf` file - The following is an example of how a `squid.conf` file that is configured for an explicit proxy server might look\. + The following is an example of a `squid.conf` file that is configured for an explicit proxy server\. ``` acl localnet src 10.0.0.0/16 #Only allow requests from within the VPC @@ -252,13 +252,13 @@ sudo tail -f /var/log/squid/access.log refresh_pattern . 0 20% 4320 ``` -## Run CodeBuild in a Transparent Proxy Server +## Run CodeBuild in a transparent proxy server To run AWS CodeBuild in a transparent proxy server, you must configure the proxy server with access to the websites and domains it interacts with\. -### Configure Squid as a Transparent Proxy Server +### Configure Squid as a transparent proxy server - To configure a proxy server to be transparent, you must grant it access to the domains and websites you want it to access\. To run AWS CodeBuild with a transparent proxy server, you must grant it access to amazonaws\.com\. You must also grant access to other websites CodeBuild uses\. These vary depending on how you create your CodeBuild projects\. Example websites are those for repositories such as GitHub, Bitbucket, Yum, and Maven\. To grant Squid access to specific domains and websites, use a command similar to the following to update the `squid.conf` file\. This sample command grants access to amazonaws\.com, github\.com, and bitbucket\.com\. You can edit this sample to grant access to other websites\. + To configure a proxy server to be transparent, you must grant it access to the domains and websites you want it to access\. To run AWS CodeBuild with a transparent proxy server, you must grant it access to `amazonaws.com`\. You must also grant access to other websites CodeBuild uses\. These vary, depending on how you create your CodeBuild projects\. Example websites are those for repositories such as GitHub, Bitbucket, Yum, and Maven\. To grant Squid access to specific domains and websites, use a command similar to the following to update the `squid.conf` file\. This sample command grants access to `amazonaws.com`, `github.com`, and `bitbucket.com`\. You can edit this sample to grant access to other websites\. ``` cat | sudo tee /etc/squid/squid.conf ≪EOF @@ -287,7 +287,7 @@ http_access deny all EOF ``` - Incoming requests from instances in the private subnet must redirect to the Squid ports\. Squid listens on port 3129 for HTTP traffic \(instead of 80\) and 3130 for HTTPS traffic \(instead of 443\)\. Use the iptables command to properly route traffic: + Incoming requests from instances in the private subnet must redirect to the Squid ports\. Squid listens on port 3129 for HTTP traffic \(instead of 80\) and 3130 for HTTPS traffic \(instead of 443\)\. Use the iptables command to route traffic: ``` sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3129 @@ -296,7 +296,7 @@ sudo service iptables save sudo service squid start ``` -### Create a CodeBuild Project +### Create a CodeBuild project After you configure your proxy server, you can use it with AWS CodeBuild in a private subnet without more configuration\. Every HTTP and HTTPS request goes through the public proxy server\. Use the following command to view the Squid proxy access log: @@ -304,19 +304,19 @@ sudo service squid start sudo tail -f /var/log/squid/access.log ``` -## Run a Package Manager and Other Tools in a Proxy Server +## 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 execute a tool, such as a package manager, in a proxy server** -1. Whitelist the tool in your proxy server by adding statements to your `squid.conf` file\. +1. Add the tool to the allow list in your proxy server by adding statements to your `squid.conf` file\. 1. Add a line to your buildspec file that points to the private endpoint of your proxy server\. - The following examples demonstrate how to do this for `apt-get`, `curl`, and `maven`\. If you use a different tool, use the same concepts by whitelisting it in the `squid.conf` file and adding a command to your buildspec file to make CodeBuild aware of your proxy server's endpoint\. + The following examples demonstrate how to do this for `apt-get`, `curl`, and `maven`\. If you use a different tool, the same principles apply\. Add it to an allow list in the `squid.conf` file and add a command to your buildspec file to make CodeBuild aware of your proxy server's endpoint\. -**Run `apt-get` in a Proxy Server** +**To run `apt-get` in a proxy server** -1. Add the following statements to your `squid.conf` file to whitelist `apt-get` 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 execute in the build environment\. ``` acl allowed_sites dstdomain ppa.launchpad.net # Required for apt-get to execute in the build environment @@ -332,9 +332,9 @@ sudo tail -f /var/log/squid/access.log echo 'Acquire::http::Proxy "http://:3128"; Acquire::https::Proxy "http://:3128"; Acquire::ftp::Proxy "http://:3128";' > /etc/apt/apt.conf.d/00proxy ``` -**Run `curl` in a Proxy Server** +**To run `curl` in a proxy server** -1. Add the following to your `squid.conf` file to whitelist `curl` in your build environment\. +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 @@ -349,9 +349,9 @@ sudo tail -f /var/log/squid/access.log curl -x :3128 https://www.google.com ``` -**Run `maven` in a Proxy Server** +**To run `maven` in a proxy server** -1. Add the following to your `squid.conf` file to whitelist `maven` in your build environment\. +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 diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index 1d343fa..70642b7 100644 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ b/doc_source/use-vpc-endpoints-with-codebuild.md @@ -1,25 +1,25 @@ -# Use VPC Endpoints +# 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 enables you 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/VPC_Introduction.html#what-is-privatelink)\. + 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*\. -## Before You Create VPC Endpoints +## Before you create VPC endpoints Before you configure VPC endpoints for AWS CodeBuild, be aware of the following restrictions and limitations\. **Note** - Use an [Amazon VPC NAT Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html) if you want to use CodeBuild with AWS services that do not support Amazon VPC PrivateLink connections\. + Use a [NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html) if you want to use CodeBuild with AWS services that do not support Amazon VPC PrivateLink connections\. + VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP Option Sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. -+ VPC endpoints currently do not support cross\-region requests\. Make sure that you create your endpoint in the same region as any Amazon S3 buckets that store your build input and output\. You can use the Amazon S3 console or the [ get\-bucket\-location](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-bucket-location.html) command to find the location of your bucket\. Use a region\-specific Amazon S3 endpoint to access your bucket \(for example, `mybucket.s3-us-west-2.amazonaws.com`\)\. For more information about region\-specific endpoints for Amazon S3, see [Amazon Simple Storage Service](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in Amazon Web Services General Reference*Amazon Web Services General Reference*\. If you use the AWS CLI to make requests to Amazon S3, set your default region to the same region as your bucket, or use the `--region` parameter in your requests\. ++ VPC endpoints currently do not support cross\-Region requests\. Make sure that you create your endpoint in the same AWS Region as any S3 buckets that store your build input and output\. You can use the Amazon S3 console or the [get\-bucket\-location](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-bucket-location.html) command to find the location of your bucket\. Use a Region\-specific Amazon S3 endpoint to access your bucket \(for example, `mybucket.s3-us-west-2.amazonaws.com`\)\. For more information about Region\-specific endpoints for Amazon S3, see [Amazon Simple Storage Service](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the *Amazon Web Services General Reference*\. If you use the AWS CLI to make requests to Amazon S3, set your default Region to the same Region where your bucket was created, or use the `--region` parameter in your requests\. -## Creating VPC Endpoints for CodeBuild +## Creating VPC endpoints for CodeBuild -Use [Creating an Interface Endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. +Follow the instructions in [Creating an Interface Endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - *region* represents the region identifier for an AWS Region supported by CodeBuild, such as `us-east-2` for the US East \(Ohio\) Region\. For a list of supported regions, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the * AWS General Reference*\. The endpoint is prepopulated with the region you specified when you signed in to AWS\. If you change your region, the VPC endpoint is updated accordingly\. + *region* represents the region identifier for an AWS Region supported by CodeBuild, such as `us-east-2` for the US East \(Ohio\) Region\. For a list of supported AWS Regions, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the * AWS General Reference*\. The endpoint is prepopulated with the Region you specified when you signed in to AWS\. If you change your Region, the VPC endpoint is updated accordingly\. -## Create a VPC Endpoint Policy for CodeBuild +## Create a VPC endpoint policy for CodeBuild You can create a policy for Amazon VPC endpoints for AWS CodeBuild in which you can specify: + The principal that can perform actions\. @@ -45,4 +45,4 @@ The following example policy specifies that all principals can only start and vi } ``` - For more information, see [Controlling Access to Services with VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html)\. \ No newline at end of file + For more information, see [Controlling Access to Services with VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html) in the *Amazon VPC User Guide*\. \ No newline at end of file diff --git a/doc_source/view-build-details.md b/doc_source/view-build-details.md index 727a39d..6e9cc6b 100644 --- a/doc_source/view-build-details.md +++ b/doc_source/view-build-details.md @@ -1,14 +1,14 @@ -# View Build Details in CodeBuild +# View build details in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view details about builds managed by CodeBuild\. **Topics** -+ [View Build Details \(Console\)](#view-build-details-console) -+ [View Build Details \(AWS CLI\)](#view-build-details-cli) -+ [View Build Details \(AWS SDKs\)](#view-build-details-sdks) -+ [Build Phase Transitions](#view-build-details-phases) ++ [View build details \(console\)](#view-build-details-console) ++ [View build details \(AWS CLI\)](#view-build-details-cli) ++ [View build details \(AWS SDKs\)](#view-build-details-sdks) ++ [Build phase transitions](#view-build-details-phases) -## View Build Details \(Console\) +## View build details \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -18,9 +18,9 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view details abou **Note** By default, only the 10 most recent 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\. -## View Build Details \(AWS CLI\) +## View build details \(AWS CLI\) -For more information about using the AWS CLI with AWS CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. Run the batch\-get\-builds command: @@ -30,8 +30,8 @@ aws codebuild batch-get-builds --ids ids Replace the following placeholder: + *ids*: Required string\. One or more build IDs to view details about\. To specify more than one build ID, separate each build ID with a space\. You can specify up to 100 build IDs\. 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 Build IDs for a Build Project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) + + [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-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) For example, if you run this command: @@ -41,11 +41,11 @@ aws codebuild batch-get-builds --ids codebuild-demo-project:e9c4f4df-3f43-41d2-a If the command is successful, data similar to that described in [To view summarized build information ](getting-started-cli-monitor-build.md#getting-started-cli-monitor-build-cli) appears in the output\. -## View Build Details \(AWS SDKs\) +## View build details \(AWS SDKs\) -For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and Tools Reference](sdk-ref.md)\. +For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. -## Build Phase Transitions +## Build phase transitions Builds in AWS CodeBuild proceed in phases: diff --git a/doc_source/view-build-list.md b/doc_source/view-build-list.md index 609bd02..8006ed0 100644 --- a/doc_source/view-build-list.md +++ b/doc_source/view-build-list.md @@ -1,13 +1,13 @@ -# View a List of Build IDs in CodeBuild +# View a list of build IDs in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build IDs for builds managed by CodeBuild\. **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 Build IDs \(AWS SDKs\)](#view-build-list-sdks) ++ [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 build IDs \(AWS SDKs\)](#view-build-list-sdks) -## View a List of Build IDs \(Console\) +## View a list of build IDs \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -15,9 +15,9 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of bu **Note** By default, only the 10 most recent builds are displayed\. To view more builds, choose the gear icon, and then choose a different value for **Builds per page** or use the back and forward arrows\. -## View a List of Build IDs \(AWS CLI\) +## View a list of build IDs \(AWS CLI\) -For more information about using the AWS CLI with CodeBuild, see the [Command Line Reference](cmd-ref.md)\. +For more information about using the AWS CLI with CodeBuild, see the [Command line reference](cmd-ref.md)\. + Run the list\-builds command: ``` @@ -67,6 +67,6 @@ For more information about using the AWS CLI with CodeBuild, see the [Command Li } ``` -## View a List of Build IDs \(AWS SDKs\) +## View a list of build IDs \(AWS SDKs\) -For more information about using CodeBuild with the AWS SDKs, see the [AWS SDKs and Tools Reference](sdk-ref.md)\. \ No newline at end of file +For more 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/view-builds-for-project.md b/doc_source/view-builds-for-project.md index 060b566..759b585 100644 --- a/doc_source/view-builds-for-project.md +++ b/doc_source/view-builds-for-project.md @@ -1,13 +1,13 @@ -# View a List of Build IDs for a Build Project in CodeBuild +# View a list of build IDs for a build project in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build IDs for a build project in CodeBuild\. **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 Build IDs for a Build Project \(AWS SDKs\)](#view-builds-for-project-sdks) ++ [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 build IDs for a build project \(AWS SDKs\)](#view-builds-for-project-sdks) -## View a List of Build IDs for a Build Project \(Console\) +## View a list of build IDs for a build project \(console\) 1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. @@ -16,9 +16,9 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of bu **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\. -## View a List of Build IDs for a Build Project \(AWS CLI\) +## View a list of 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)\. +For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. Run the list\-builds\-for\-project command, as follows: @@ -27,7 +27,7 @@ aws codebuild list-builds-for-project --project-name project-name --sort-order s ``` 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)\. ++ *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\. @@ -70,6 +70,6 @@ You might see a result like the following in the output: } ``` -## View a List of Build IDs for a Build Project \(AWS SDKs\) +## 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 +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 fde5b06..fbe1f81 100644 --- a/doc_source/view-project-details.md +++ b/doc_source/view-project-details.md @@ -1,13 +1,13 @@ -# View a Build Project's Details in CodeBuild +# View a build project's details in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view the details of a build project in CodeBuild\. **Topics** -+ [View a Build Project's Details \(Console\)](#view-project-details-console) -+ [View a Build Project's Details \(AWS CLI\)](#view-project-details-cli) -+ [View a Build Project's Details \(AWS SDKs\)](#view-project-details-sdks) ++ [View a build project's details \(console\)](#view-project-details-console) ++ [View a build project's details \(AWS CLI\)](#view-project-details-cli) ++ [View a build project's details \(AWS SDKs\)](#view-project-details-sdks) -## View a Build Project's Details \(Console\) +## View a build project's details \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -19,9 +19,7 @@ By default, only the 10 most recent build projects are displayed\. To view more 1. On the **Build project: *project\-name*** page, choose **Build details**\. -## View a Build Project's Details \(AWS CLI\) - -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 CLI\) Run the batch\-get\-projects command: @@ -30,7 +28,7 @@ aws codebuild batch-get-projects --names names ``` In the preceding command, replace the following placeholder: -+ *names*: Required string used to indicate one or more build project names to view details about\. To specify more than one build project, separate each build project's name with a space\. You can specify up to 100 build project names\. 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)\. ++ *names*: Required string used to indicate one or more build project names to view details about\. To specify more than one build project, separate each build project's name with a space\. You can specify up to 100 build project names\. 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)\. For example, if you run this command: @@ -60,8 +58,10 @@ 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.md#create-project-cli)\. +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.md#create-project-cli)\. + +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\) +## View a build project's details \(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 +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-list.md b/doc_source/view-project-list.md index cdfa6ea..3e37872 100644 --- a/doc_source/view-project-list.md +++ b/doc_source/view-project-list.md @@ -1,13 +1,15 @@ -# View a List of Build Project Names in CodeBuild +# View a list of build project names in AWS CodeBuild You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build projects in CodeBuild\. **Topics** -+ [View a List of Build Project Names \(Console\)](#view-project-list-console) -+ [View a List of Build Project Names \(AWS CLI\)](#view-project-list-cli) -+ [View a List of Build Project Names \(AWS SDKs\)](#view-project-list-sdks) ++ [View a list of build project names \(console\)](#view-project-list-console) ++ [View a list of build project names \(AWS CLI\)](#view-project-list-cli) ++ [View a list of build project names \(AWS SDKs\)](#view-project-list-sdks) -## View a List of Build Project Names \(Console\) +## View a list of build project names \(console\) + +You can view a list of build projects in an AWS Region in the console\. Information includes the name, source provider, repository, latest build status, and description, if any\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -15,7 +17,7 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of bu **Note** By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. -## View a List of Build Project Names \(AWS CLI\) +## View a list of build project names \(AWS CLI\) Run the list\-projects command: @@ -70,6 +72,6 @@ A result similar to the following might appear in the output: } ``` -## View a List of Build Project Names \(AWS SDKs\) +## View a list of build project names \(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 +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/vpc-support.md b/doc_source/vpc-support.md index 8bf127d..d4ba181 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -1,87 +1,83 @@ -# Use CodeBuild with Amazon Virtual Private Cloud +# Use AWS CodeBuild with Amazon Virtual Private Cloud -Typically, resources in an VPC are not accessible by AWS CodeBuild\. To enable access, you must provide additional VPC\-specific configuration information as part of your CodeBuild project configuration\. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs\. VPC\-enabled builds are then able to access resources inside your VPC\. For more information about setting up a VPC in Amazon VPC, see the [VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. +Typically, AWS CodeBuild cannot access resources in a VPC\. To enable access, you must provide additional VPC\-specific configuration information in your CodeBuild project configuration\. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs\. VPC\-enabled builds can then access resources inside your VPC\. For more information about setting up a VPC in Amazon VPC, see the [Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. **Note** VPC connectivity from CodeBuild is not supported in Windows\. **Topics** -+ [Use Cases](#use-cases) -+ [Enabling Amazon VPC Access in Your CodeBuild Projects](#enabling-vpc-access-in-projects) -+ [Best Practices for VPCs](#best-practices-for-vpcs) -+ [Troubleshooting Your VPC Setup](#troubleshooting-vpc) -+ [Use VPC Endpoints](use-vpc-endpoints-with-codebuild.md) -+ [AWS CloudFormation VPC Template](cloudformation-vpc-template.md) -+ [Use CodeBuild with a Proxy Server](use-proxy-server.md) ++ [Use cases](#use-cases) ++ [Allowing Amazon VPC access in your CodeBuild projects](#enabling-vpc-access-in-projects) ++ [Best practices for VPCs](#best-practices-for-vpcs) ++ [Troubleshooting your VPC setup](#troubleshooting-vpc) ++ [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 Cases +## Use cases VPC connectivity from AWS CodeBuild builds makes it possible to: + Run integration tests from your build against data in an Amazon RDS database that's isolated on a private subnet\. + Query data in an Amazon ElastiCache cluster directly from tests\. + Interact with internal web services hosted on Amazon EC2, Amazon ECS, or services that use internal Elastic Load Balancing\. + Retrieve dependencies from self\-hosted, internal artifact repositories, such as PyPI for Python, Maven for Java, and npm for Node\.js\. -+ Access objects in an Amazon S3 bucket configured to allow access through an Amazon VPC endpoint only\. -+ Query external web services that require fixed IP addresses through the Elastic IP address of the NAT gateway or NAT instance associated with your subnet\(s\)\. ++ Access objects in an S3 bucket configured to allow access through an Amazon VPC endpoint only\. ++ Query external web services that require fixed IP addresses through the Elastic IP address of the NAT gateway or NAT instance associated with your subnet\. Your builds can access any resource that's hosted in your VPC\. -## Enabling Amazon VPC Access in Your CodeBuild Projects +## Allowing Amazon VPC access in your CodeBuild projects Include these settings in your VPC configuration: + For **VPC ID**, choose the VPC ID that CodeBuild uses\. -+ For **Subnets**, choose a private subnet with NAT translation that includes or has routes to the resources used CodeBuild\. ++ 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\. -**Create a build project \(console\)** +To use the console to create a build project, see [Create a build project \(console\)](create-project.md#create-project-console)\. When you create or change your CodeBuild project, in **VPC**, choose your VPC ID, subnets, and security groups\. -For information about creating a build project, see [Create a Build Project \(Console\)](create-project.md#create-project-console)\. When you create or change your CodeBuild project, in **VPC**, choose your VPC ID, subnets, and security groups\. - -**Create a build project \(AWS CLI\)** - -For information about creating a build project, see [Create a Build Project \(AWS CLI\)](create-project.md#create-project-cli)\. 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 the following policy attached: [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)\. +To use the AWS CLI to create a build project, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. 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*\. -+ *vpcId*: Required value\. The VPC ID that CodeBuild uses\. To get a list of all Amazon VPC IDs in your region, run this command: ++ *vpcId*: Required\. The VPC ID that CodeBuild uses\. Run this command to get a list of all Amazon VPC IDs in your Region: ``` aws ec2 describe-vpcs ``` -+ *subnets*: Required value\. The subnet IDs that include resources used by CodeBuild\. To obtain these IDs, run this command: ++ *subnets*: Required\. The subnet IDs that include resources used by CodeBuild\. Run this command obtain these IDs: ``` aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region us-east-1 ``` **Note** -Replace us\-east\-1 with your region\. -+ *securityGroupIds*: Required value\. The security group IDs used by CodeBuild to allow access to resources in the VPCs\. To obtain these IDs, run this command: +Replace `us-east-1` with your Region\. ++ *securityGroupIds*: Required\. The security group IDs used by CodeBuild to allow access to resources in the VPCs\. Run this command to obtain these IDs: ``` aws ec2 describe-security-groups --filters "Name=vpc-id,Values=" --region us-east-1 ``` **Note** -Replace us\-east\-1 with your region\. +Replace `us-east-1` with your Region\. -## Best Practices for VPCs +## Best practices for VPCs -Use this checklist when setting 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)\. +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*\. **Important** -You need a NAT gateway or NAT instance in order to use CodeBuild with your Amazon 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 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\. + Include multiple Availability Zones with your VPC\. -+ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security Groups Rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. ++ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security Groups Rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*\. + Set up separate subnets for your builds\. + When you set up your CodeBuild projects to access your VPC, choose private subnets only\. For more information about setting up a VPC in Amazon VPC, see the [Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. -For more information about using AWS CloudFormation to configure an Amazon VPC to use the CodeBuild VPC feature, see the [AWS CloudFormation VPC Template](cloudformation-vpc-template.md)\. +For more information about using AWS CloudFormation to configure a VPC to use the CodeBuild VPC feature, see the [AWS CloudFormation VPC template](cloudformation-vpc-template.md)\. -## Troubleshooting Your VPC Setup +## Troubleshooting your VPC setup -When troubleshooting VPC issues, use the information that appears in the error message to help you identify, diagnose, and address issues\. +Use the information that appears in the error message to help you identify, diagnose, and address issues\. -The following are some guidelines to assist you when troubleshooting a common CodeBuild VPC error: "Build does not have internet connectivity\. Please check subnet network configuration"\. +The following are some guidelines to assist you when troubleshooting a common CodeBuild VPC error: `Build does not have internet connectivity. Please check subnet network configuration`\. 1. [Make sure that your internet gateway is attached to VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. @@ -91,10 +87,10 @@ The following are some guidelines to assist you when troubleshooting a common Co 1. [Make sure that your security groups allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. -1. [Troubleshoot your NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html#nat-gateway-troubleshooting)\. +1. [Troubleshoot your NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC-nat-gateway.html#nat-gateway-troubleshooting)\. 1. [Make sure that the route table for private subnets points to the NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#route-tables-nat)\. -1. Make sure that the service role used by CodeBuild to interact with services on behalf of the IAM user has the permissions in [ this policy](https://docs.aws.amazon.com/codebuild/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html#customer-managed-policies-example-create-vpc-network-interface)\. For more information, see [Create a CodeBuild Service Role](setting-up.md#setting-up-service-role)\. +1. Make sure that the service role used by CodeBuild to interact with services on behalf of the IAM user has the permissions in [ this policy](https://docs.aws.amazon.com/codebuild/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html#customer-managed-policies-example-create-vpc-network-interface)\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. - If CodeBuild is missing permissions, you might receive an error that says, "Unexpected EC2 error: UnauthorizedOperation\." This error can occur if CodeBuild does not have the Amazon EC2 permissions required to work with an Amazon VPC\. \ No newline at end of file + If CodeBuild is missing permissions, you might receive an error that says, `Unexpected EC2 error: UnauthorizedOperation`\. This error can occur if CodeBuild does not have the Amazon EC2 permissions required to work with a VPC\. \ No newline at end of file diff --git a/doc_source/welcome.md b/doc_source/welcome.md index 9fe38b7..e903bcb 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -1,4 +1,4 @@ -# What Is AWS CodeBuild? +# 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\. @@ -10,37 +10,37 @@ CodeBuild provides these benefits: For more information, see [AWS CodeBuild](https://aws.amazon.com/codebuild/)\. **Topics** -+ [How to Run CodeBuild](#welcome-quick-look) ++ [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) ++ [How do I get started with CodeBuild?](#welcome-getting-started) ++ [AWS CodeBuild concepts](concepts.md) -## How to Run CodeBuild +## How to run CodeBuild -You can run CodeBuild by using the CodeBuild or AWS CodePipeline console\. You can also automate the running of CodeBuild by using the AWS Command Line Interface \(AWS CLI\) or the AWS SDKs\. +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)\. +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 enables you 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\. +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 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 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/)\. -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 type 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)\. +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)\. ## Pricing for CodeBuild For information, see [CodeBuild Pricing](https://aws.amazon.com/codebuild/pricing)\. -## How Do I Get Started with CodeBuild? +## How do I get started with CodeBuild? We recommend that you complete the following steps: 1. **Learn** more about CodeBuild by reading the information in [Concepts](concepts.md)\. -1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting Started in the Console](getting-started.md)\. +1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting started using the console](getting-started.md)\. -1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a Build](planning.md)\. \ No newline at end of file +1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a build](planning.md)\. \ No newline at end of file diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 470966c..7b2ca10 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -1,17 +1,17 @@ -# Working with Build Projects +# Working with build projects 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\. You can perform these tasks when working with build projects: **Topics** -+ [Create a Build Project in CodeBuild](create-project.md) ++ [Create a build project in AWS CodeBuild](create-project.md) + [Create a Notification Rule](notification-rule-create.md) -+ [View a List of Build Project Names in CodeBuild](view-project-list.md) -+ [View a Build Project's Details in CodeBuild](view-project-details.md) -+ [Build Caching in CodeBuild](build-caching.md) -+ [Create CodeBuild Triggers](trigger-create.md) -+ [Edit CodeBuild Triggers](triggers-edit.md) -+ [Change a Build Project's Settings in CodeBuild](change-project.md) -+ [Delete a Build Project in AWS CodeBuild](delete-project.md) -+ [Working with Shared Projects](project-sharing.md) \ No newline at end of file ++ [View a list of build project names in AWS CodeBuild](view-project-list.md) ++ [View a build project's details in AWS CodeBuild](view-project-details.md) ++ [Build caching in AWS CodeBuild](build-caching.md) ++ [Create AWS CodeBuild triggers](trigger-create.md) ++ [Edit AWS CodeBuild triggers](triggers-edit.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) \ No newline at end of file From b62a0a2c2d7732146309336c15974ab7f9cf9b32 Mon Sep 17 00:00:00 2001 From: Mjone77 Date: Wed, 20 May 2020 13:24:40 -0500 Subject: [PATCH 031/156] Update amazon/aws-codebuild-local signature --- doc_source/use-codebuild-agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 757c6b3..ab6ae06 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -16,7 +16,7 @@ codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] ``` - 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 `94467b3eeac4184d28a38feb27a1530691527dd49c17e30ad1b6331d791e82f5`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + 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 `bd69dbcdc9b3da66fd93de0b6d45534086367d6b48d3536d0248a01a459fb7e4`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: ``` docker inspect amazon/aws-codebuild-local @@ -60,4 +60,4 @@ docker inspect amazon/aws-codebuild-local 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**\. From cb4691e4b039ce309b5b14d10f5282a7aeb49ffc Mon Sep 17 00:00:00 2001 From: Denis Policastro Date: Thu, 21 May 2020 18:15:56 -0300 Subject: [PATCH 032/156] Update sample-build-notifications.md Remove one of the two colons from build ARN --- doc_source/sample-build-notifications.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 2b9f811..d7201ac 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -283,12 +283,12 @@ Build state change notifications use the following format: "time": "2017-09-01T16:14:28Z", "region": "us-west-2", "resources":[ - "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" + "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" ], "detail":{ "build-status": "SUCCEEDED", "project-name": "my-sample-project", - "build-id": "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", + "build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", "additional-information": { "artifact": { "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", @@ -413,12 +413,12 @@ Build phase change notifications use the following format: "time": "2017-09-01T16:14:21Z", "region": "us-west-2", "resources":[ - "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" + "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" ], "detail":{ "completed-phase": "COMPLETED", "project-name": "my-sample-project", - "build-id": "arn:aws:codebuild:us-west-2::123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", + "build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", "completed-phase-context": "[]", "additional-information": { "artifact": { @@ -532,4 +532,4 @@ Build phase change notifications use the following format: "completed-phase-end": "Sep 1, 2017 4:14:26 PM" } } -``` \ No newline at end of file +``` From 57c7b6cfd6f665939ff25ee58de2ab34277b444a Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 21 May 2020 15:53:46 -0700 Subject: [PATCH 033/156] Remove extra colon from account ID --- doc_source/build-caching.md | 5 +++-- doc_source/delete-builds.md | 4 ++-- doc_source/report-groups-sharing.md | 2 +- doc_source/sample-build-notifications.md | 14 +++++++------- doc_source/sample-test-report-cli.md | 4 ++-- doc_source/use-codebuild-agent.md | 4 ++-- 6 files changed, 17 insertions(+), 16 deletions(-) diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index b069dc8..1e31fe5 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -26,10 +26,11 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + 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 are overriden if a source item has 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)\. + + 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)\. +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)\. **Topics** + [Specify local caching \(CLI\)](#caching-local-cli) diff --git a/doc_source/delete-builds.md b/doc_source/delete-builds.md index 9924d01..8c74d51 100644 --- a/doc_source/delete-builds.md +++ b/doc_source/delete-builds.md @@ -29,12 +29,12 @@ Information similar to the following appears in the output: { "buildsNotDeleted": [ { - "id": "arn:aws:codebuild:us-west-2::123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX", + "id": "arn:aws:codebuild:us-west-2:123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX", "statusCode": "BUILD_IN_PROGRESS" } ], "buildsDeleted": [ - "arn:aws:codebuild:us-west-2::123456789012n:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" + "arn:aws:codebuild:us-west-2:123456789012n:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" ] } ``` diff --git a/doc_source/report-groups-sharing.md b/doc_source/report-groups-sharing.md index d6dc552..870d818 100644 --- a/doc_source/report-groups-sharing.md +++ b/doc_source/report-groups-sharing.md @@ -99,7 +99,7 @@ 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" ] }, diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index d7201ac..07bf56c 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -279,7 +279,7 @@ Build state change notifications use the following format: "id": "c030038d-8c4d-6141-9545-00ff7b7153EX", "detail-type": "CodeBuild Build State Change", "source": "aws.codebuild", - "account": ":123456789012", + "account": "123456789012", "time": "2017-09-01T16:14:28Z", "region": "us-west-2", "resources":[ @@ -293,7 +293,7 @@ Build state change notifications use the following format: "artifact": { "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", "sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX", - "location": "arn:aws:s3:::codebuild-:123456789012-output-bucket/my-output-artifact.zip" + "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" }, "environment": { "image": "aws/codebuild/standard:2.0", @@ -307,7 +307,7 @@ Build state change notifications use the following format: "initiator": "MyCodeBuildDemoUser", "build-start-time": "Sep 1, 2017 4:12:29 PM", "source": { - "location": "codebuild-:123456789012-input-bucket/my-input-artifact.zip", + "location": "codebuild-123456789012-input-bucket/my-input-artifact.zip", "type": "S3" }, "logs": { @@ -409,7 +409,7 @@ Build phase change notifications use the following format: "id": "43ddc2bd-af76-9ca5-2dc7-b695e15adeEX", "detail-type": "CodeBuild Build Phase Change", "source": "aws.codebuild", - "account": ":123456789012", + "account": "123456789012", "time": "2017-09-01T16:14:21Z", "region": "us-west-2", "resources":[ @@ -424,7 +424,7 @@ Build phase change notifications use the following format: "artifact": { "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", "sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX", - "location": "arn:aws:s3:::codebuild-:123456789012-output-bucket/my-output-artifact.zip" + "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" }, "environment": { "image": "aws/codebuild/standard:2.0", @@ -438,7 +438,7 @@ Build phase change notifications use the following format: "initiator": "MyCodeBuildDemoUser", "build-start-time": "Sep 1, 2017 4:12:29 PM", "source": { - "location": "codebuild-:123456789012-input-bucket/my-input-artifact.zip", + "location": "codebuild-123456789012-input-bucket/my-input-artifact.zip", "type": "S3" }, "logs": { @@ -532,4 +532,4 @@ Build phase change notifications use the following format: "completed-phase-end": "Sep 1, 2017 4:14:26 PM" } } -``` +``` \ No newline at end of file diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index d331c4f..ae1445d 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -73,7 +73,7 @@ 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", + "arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/report-name", "name": "report-name", "type": "TEST", "exportConfig": { @@ -82,7 +82,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "bucket": "s3-bucket-name", "path": "folder-path", "packaging": "NONE", - "encryptionKey": "arn:aws:kms:us-west-2::123456789012:alias/aws/s3" + "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" } }, "created": 1570837165.885, diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index ab6ae06..757c6b3 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -16,7 +16,7 @@ codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] ``` - 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 `bd69dbcdc9b3da66fd93de0b6d45534086367d6b48d3536d0248a01a459fb7e4`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + 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 `94467b3eeac4184d28a38feb27a1530691527dd49c17e30ad1b6331d791e82f5`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: ``` docker inspect amazon/aws-codebuild-local @@ -60,4 +60,4 @@ docker inspect amazon/aws-codebuild-local 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**\. +1. Select the subscription and from **Actions**, choose **Delete subscriptions**\. When you are prompted to confirm, choose **Delete**\. \ No newline at end of file From 0f9e42731d7115de921ec427e7ce8822b69dc86f Mon Sep 17 00:00:00 2001 From: krymtkts Date: Fri, 22 May 2020 14:20:39 +0900 Subject: [PATCH 034/156] Fix Go versions on sample-runtime-versions.md --- doc_source/sample-runtime-versions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index ef18016..b34bcb9 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -279,7 +279,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\.12 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 10 and Go version 1\.13 runtimes\. ``` version: 0.2 @@ -345,10 +345,10 @@ The build project in this example uses source code in the GitHub [AWS Samples](h ``` [Container] Date Time Processing environment variables - [Container] Date Time Selecting 'golang' runtime version '1.12' based on manual selections... + [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 Running command echo "Installing Go version 1.12 ..." - Installing Go version 1.12 ... + [Container] Date Time Running command echo "Installing Go version 1.13 ..." + Installing Go version 1.13 ... [Container] Date Time Running command echo "Installing Node.js version 10 ..." Installing Node.js version 10 ... From e61b46b29d7a4447d0837204ea86dd0fab221b98 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 22 May 2020 07:59:46 -0700 Subject: [PATCH 035/156] Updates for test reporting/tagging --- ...ntrol-iam-access-control-identity-based.md | 2 +- ...ntrol-iam-identity-based-access-control.md | 251 +++++++++++++++++- .../auth-and-access-control-using-tags.md | 67 +++++ doc_source/build-caching.md | 4 +- doc_source/build-spec-ref.md | 12 +- doc_source/change-project.md | 2 - doc_source/create-project.md | 2 +- doc_source/delete-builds.md | 2 +- doc_source/history.md | 6 +- doc_source/how-to-tag-project-add.md | 38 +++ doc_source/how-to-tag-project-delete.md | 33 +++ doc_source/how-to-tag-project-list.md | 38 +++ doc_source/how-to-tag-project-update.md | 28 ++ doc_source/how-to-tag-project.md | 17 ++ doc_source/how-to-tag-report-group-add.md | 38 +++ doc_source/how-to-tag-report-group-delete.md | 35 +++ doc_source/how-to-tag-report-group-list.md | 72 +++++ doc_source/how-to-tag-report-group-update.md | 28 ++ doc_source/how-to-tag-report-group.md | 17 ++ doc_source/index.md | 10 + doc_source/limits.md | 15 +- doc_source/report-create.md | 5 - doc_source/report-group-create.md | 7 +- doc_source/report-group-export-settings.md | 18 +- doc_source/report-group-test-case-commands.md | 5 - doc_source/report-group-test-cases.md | 7 +- doc_source/sample-github-pull-request.md | 4 +- doc_source/sample-runtime-versions.md | 4 +- doc_source/sample-test-report-cli.md | 5 - doc_source/test-permissions.md | 23 +- .../test-report-group-create-buildspec.md | 5 - doc_source/test-report-group-create-cfn.md | 16 +- doc_source/test-report-group-create-cli.md | 20 +- .../test-report-group-create-console.md | 11 +- doc_source/test-report-group-naming.md | 5 - doc_source/test-report-group.md | 6 +- doc_source/test-report.md | 5 - doc_source/test-reporting.md | 12 +- doc_source/test-view-reports.md | 20 -- doc_source/update-report-group-cli.md | 13 +- doc_source/use-codebuild-agent.md | 4 +- doc_source/working-with-build-projects.md | 3 +- 42 files changed, 761 insertions(+), 154 deletions(-) create mode 100644 doc_source/how-to-tag-project-add.md create mode 100644 doc_source/how-to-tag-project-delete.md create mode 100644 doc_source/how-to-tag-project-list.md create mode 100644 doc_source/how-to-tag-project-update.md create mode 100644 doc_source/how-to-tag-project.md create mode 100644 doc_source/how-to-tag-report-group-add.md create mode 100644 doc_source/how-to-tag-report-group-delete.md create mode 100644 doc_source/how-to-tag-report-group-list.md create mode 100644 doc_source/how-to-tag-report-group-update.md create mode 100644 doc_source/how-to-tag-report-group.md 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 8022441..847da99 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 @@ -89,7 +89,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 be add them yourself\. +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:GetBucketLocation` 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 1de8277..592054c 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 @@ -21,7 +21,7 @@ The following shows an example of a permissions policy that allows a user to get { "Effect": "Allow", "Action": "codebuild:BatchGetProjects", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" + "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" } ] } @@ -55,7 +55,7 @@ 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\. 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 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*\. 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\. @@ -68,6 +68,251 @@ To create and manage CodeBuild service roles, you must also attach the AWS manag You can also create your own custom IAM policies to allow permissions for CodeBuild actions and resources\. You can attach these custom policies to the IAM users or groups that require those permissions\. +**Topics** ++ [AWSCodeBuildAdminAccess](#admin-access-policy) ++ [AWSCodeBuildDeveloperAccess](#developer-access-policy) ++ [AWSCodeBuildReadOnlyAccess](#read-only-access-policy) + +### 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 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": "*" + } + ] +} +``` + +### 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 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": "*" + } + ], + "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 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": "*" + } + ], + "Version": "2012-10-17" +} +``` + ## CodeBuild Managed Policies and Notifications CodeBuild supports notifications, which can notify users of important changes to build projects\. Managed policies for CodeBuild include policy statements for notification functionality\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html)\. @@ -212,7 +457,7 @@ For more information about IAM and notifications, see [Identity and Access Manag ## Customer\-managed policy examples -In this section, you can find example user policies that grant permissions for AWS CodeBuild actions\. These policies work when you are using the CodeBuild API, AWS SDKs, or AWS CLI\. When you are using the console, you must grant additional permissions specific to the console\. For information, see [Permissions required to use the AWS CodeBuild console](#console-permissions)\. +In this section, you can find example user policies that grant permissions for AWS CodeBuild actions\. These policies work when you are using the CodeBuild API, AWS SDKs, or AWS CLI\. When you are using the console, you must grant additional, console\-specific permissions\. For information, see [Permissions required to use the AWS CodeBuild console](#console-permissions)\. You can use the following sample IAM policies to limit CodeBuild access for your IAM users and roles\. diff --git a/doc_source/auth-and-access-control-using-tags.md b/doc_source/auth-and-access-control-using-tags.md index 7714585..97e65d0 100644 --- a/doc_source/auth-and-access-control-using-tags.md +++ b/doc_source/auth-and-access-control-using-tags.md @@ -58,4 +58,71 @@ 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** +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`: + +``` +{ + "Version": "2012-10-17", + "Statement" : [ + { + "Effect" : "Deny", + "Action" : [ + "codebuild:BatchGetReportGroups," + "codebuild:CreateReportGroup", + "codebuild:DeleteReportGroup", + "codebuild:ListReportGroups", + "codebuild:ListReportsForReportGroup", + "codebuild:UpdateReportGroup" + ] + "Resource" : "*", + "Condition" : { + "StringEquals" : "aws:ResourceTag/Status": "Secret" + } + } + ] +} +``` + +**Example 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: + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "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" + ], + "Resource": "*", + "Condition": { + "StringNotEquals": { + "aws:ResourceTag/Status": "Secret", + "aws:ResourceTag/Team": "Saanvi" + } + } + } + ] +} ``` \ No newline at end of file diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 1e31fe5..fcca734 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -15,8 +15,8 @@ Docker layer cache mode is available for the Linux environment only\. If you cho ## 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 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\. This is not the best option if your builds are infrequent\. If you choose this option and your project does not use a Git repository \(GitHub, GitHub Enterprise, or Bitbucket\), the option is ignored\. + 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, 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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 3fb9db7..413bb12 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -223,13 +223,14 @@ Commands in some build phases might not be run if commands in earlier build phas + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + `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\. - + `discard-paths`: Optional mapping\. Represents whether paths to test result files uploaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TestResult.xml`\. + + `discard-paths`: Optional mapping\. Represents whether paths to test result files uploaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TesResult.xml`\. + `file-format`: Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: + `JunitXml` + `CucumberJson` + `VisualStudioTrx` + + `VisualStudioTrx` + `TestNGXml` -+ `artifacts`: Optional sequence\. Represents information about where CodeBuild can find the build output and how CodeBuild prepares it for uploading to the Amazon 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\. ++ `artifacts`: 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\. + `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`\)\. + A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. @@ -378,7 +379,7 @@ Commands in some build phases might not be run if commands in earlier build phas - directory/file2 name: secondary-artifact-name-2 ``` -+ `cache`: Optional sequence\. Represents information about where CodeBuild can prepare the files for uploading cache to an Amazon S3 cache bucket\. This sequence is not required if the cache type of the project is `No Cache`\. ++ `cache`: Optional sequence\. Represents information about where CodeBuild can prepare the files for uploading cache to an S3 cache bucket\. This sequence is not required if the cache type of the project is `No Cache`\. + `paths`: Required sequence\. Represents the locations of the cache\. 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`\)\. + A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. @@ -394,11 +395,6 @@ You can use the CodeBuild or CodePipeline consoles instead of a buildspec\.yml f ## Buildspec example - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - Here is an example of a buildspec\.yml file\. ``` diff --git a/doc_source/change-project.md b/doc_source/change-project.md index d961b16..9608ae7 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -82,8 +82,6 @@ If your build project refers to secrets stored in Secrets Manager, the build pro 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. To change information about tags for this build project, in **Additional configuration**, for **Tags**, change the values of **Name** and **Value**\. Use **Add row** to add a tag\. You can add up to 50 tags\. Choose the delete \(**X**\) icon next to a tag you no longer want to use\. - 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`\)\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index c65763e..fbcd9b2 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -519,7 +519,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + *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 that contains a `key` and `value` value of *tag\-key* and *tag\-value*\. + + 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: diff --git a/doc_source/delete-builds.md b/doc_source/delete-builds.md index 8c74d51..6666922 100644 --- a/doc_source/delete-builds.md +++ b/doc_source/delete-builds.md @@ -34,7 +34,7 @@ Information similar to the following appears in the output: } ], "buildsDeleted": [ - "arn:aws:codebuild:us-west-2:123456789012n:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" + "arn:aws:codebuild:us-west-2:123456789012:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" ] } ``` diff --git a/doc_source/history.md b/doc_source/history.md index e81a426..82bac5d 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,12 @@ 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: **May 6, 2020 ++ **Latest documentation update: **May 21, 2020 | Change | Description | Date | | --- |--- |--- | +| [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 | @@ -43,8 +45,6 @@ The following table describes the important changes to the documentation since t The following table describes important changes in each release of the *AWS CodeBuild User Guide* before June 2018\. -**** - | 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 | diff --git a/doc_source/how-to-tag-project-add.md b/doc_source/how-to-tag-project-add.md new file mode 100644 index 0000000..f739466 --- /dev/null +++ b/doc_source/how-to-tag-project-add.md @@ -0,0 +1,38 @@ +# Add a Tag to a Project + +Adding tags to a project can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a project\. Keep in mind that there are limits on the number of tags you can have on a project\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the project based on these tags\. You can use the CodeBuild console or the AWS CLI to add tags to a project\. + +**Important** +Before you add a tag to a project, make sure to review any IAM policies that might use tags to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +For more information about adding tags to a project when you create it, see [Add a Tag to a Project \(Console\)](#how-to-tag-project-add-console)\. + +**Topics** ++ [Add a Tag to a Project \(Console\)](#how-to-tag-project-add-console) ++ [Add a Tag to a Project \(AWS CLI\)](#how-to-tag-project-add-cli) + +## Add a Tag to a Project \(Console\) + +You can use the CodeBuild console to add one or more tags to a CodeBuild project\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Build projects**, choose the name of the project where you want to add tags\. + +1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. + +1. If no tags have been added to the project, choose **Add tag**\. Otherwise, choose **Edit**, and then choose **Add tag**\. + +1. In **Key**, enter a name for the tag\. You can add an optional value for the tag in **Value**\. + +1. \(Optional\) To add another tag, choose **Add tag** again\. + +1. When you have finished adding tags, choose **Submit**\. + +## Add a Tag to a Project \(AWS CLI\) + +To add a tag to a project when you create it, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. In `create-project.json`, add your tags\. + +In these steps, we assume that you have already installed a recent version of the AWS CLI or updated to the current version\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)\. + +If successful, this command returns nothing\. \ 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 new file mode 100644 index 0000000..21620e1 --- /dev/null +++ b/doc_source/how-to-tag-project-delete.md @@ -0,0 +1,33 @@ +# Remove a Tag from a Project + +You can remove one or more tags associated with a project\. Removing a tag does not delete the tag from other AWS resources that are associated with that tag\. + +**Important** +Removing tags for a project can impact access to that project\. Before you remove a tag from a project, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +## Remove a Tag from a Project \(Console\) + +You can use the CodeBuild console to remove the association between a tag and a CodeBuild project\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Build projects**, choose the name of the project where you want to remove tags\. + +1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. + +1. Choose **Edit**\. + +1. Find the tag you want to remove, and then choose **Remove tag**\. + +1. When you have finished removing tags, choose **Submit**\. + +## 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: + +``` +"tags: []" +``` + +**Note** +If you delete a CodeBuild build project, all tag associations are removed from the deleted build project\. You do not have to remove tags before you delete a build project\. \ No newline at end of file diff --git a/doc_source/how-to-tag-project-list.md b/doc_source/how-to-tag-project-list.md new file mode 100644 index 0000000..139e0d3 --- /dev/null +++ b/doc_source/how-to-tag-project-list.md @@ -0,0 +1,38 @@ +# View Tags for a Project + +Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +## View Tags for a Project \(Console\) + +You can use the CodeBuild console to view the tags associated with a CodeBuild project\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Build projects**, choose the name of the project where you want to view tags\. + +1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. + +## View Tags for a Project \(AWS CLI\) + +To view tags for a build project, run the following command\. Use the name of your project for the `--names` parameter\. + +``` +aws codebuild batch-get-projects --names your-project-name +``` + +If successful, this command returns JSON\-formatted information about your build project that includes something like the following: + +``` +{ + "tags": { + "Status": "Secret", + "Team": "JanesProject" + } +} +``` + +If the project does not have tags, the `tags` section is empty: + +``` +"tags": [] +``` \ No newline at end of file diff --git a/doc_source/how-to-tag-project-update.md b/doc_source/how-to-tag-project-update.md new file mode 100644 index 0000000..90d96b5 --- /dev/null +++ b/doc_source/how-to-tag-project-update.md @@ -0,0 +1,28 @@ +# Edit Tags for a Project + +You can change the value for a tag associated with a project\. You can also change the name of the key, which is equivalent to removing the current tag and adding a different one with the new name and the same value as the other key\. Keep in mind that there are limits on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. + +**Important** +Editing tags for a project can impact access to that project\. Before you edit the name \(key\) or value of a tag for a project, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +## Edit a Tag for a Project \(Console\) + +You can use the CodeBuild console to edit the tags associated with a CodeBuild project\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Build projects**, choose the name of the project where you want to edit tags\. + +1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. + +1. Choose **Edit**\. + +1. Do one of the following: + + To change the tag, enter a new name in **Key**\. Changing the name of the tag is the equivalent of removing a tag and adding a new tag with the new key name\. + + To change the value of a tag, enter a new value\. If you want to change the value to nothing, delete the current value and leave the field blank\. + +1. When you have finished editing tags, choose **Submit**\. + +## 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 diff --git a/doc_source/how-to-tag-project.md b/doc_source/how-to-tag-project.md new file mode 100644 index 0000000..2a9c514 --- /dev/null +++ b/doc_source/how-to-tag-project.md @@ -0,0 +1,17 @@ +# Tagging Projects in AWS CodeBuild + +A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Each AWS tag has two parts: ++ A *tag key* \(for example, `CostCenter`, `Environment`, `Project`, or `Secret`\)\. Tag keys are case sensitive\. ++ An optional field known as a *tag value* \(for example, `111122223333`, `Production`, or a team name\)\. Omitting the tag value is the same as using an empty string\. Like tag keys, tag values are case sensitive\. + +Together these are known as key\-value pairs\. For information about the number of tags you can have on a project and restrictions on tag keys and values, see [Tags](limits.md#tag-limits)\. + +Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild project that you assign to an S3 bucket\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. + +In CodeBuild, the primary resources are the project and the report group\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a project\. In addition to identifying, organizing, and tracking your project with tags, you can use tags in IAM policies to help control who can view and interact with your project\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +**Topics** ++ [Add a Tag to a Project](how-to-tag-project-add.md) ++ [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) \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-add.md b/doc_source/how-to-tag-report-group-add.md new file mode 100644 index 0000000..f3d47f2 --- /dev/null +++ b/doc_source/how-to-tag-report-group-add.md @@ -0,0 +1,38 @@ +# Add a Tag to a Report Group + +Adding tags to a report group can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a report group\. Keep in mind that there are limits on the number of tags you can have on a report group\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the report group based on these tags\. You can use the the CodeBuild console or the AWS CLI to add tags to a report group\. + +**Important** +Adding tags to a report group can impact access to that report group\. Before you add a tag to a report group, make sure to review any IAM policies that might use tags to control access to resources such as report groups\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +For more information about adding tags to a report group when you create it, see [Create a report group \(console\)](test-report-group-create-console.md)\. + +**Topics** ++ [Add a Tag to a Report Group \(Console\)](#how-to-tag-report-group-add-console) ++ [Add a Tag to a Report Group \(AWS CLI\)](#how-to-tag-report-group-add-cli) + +## Add a Tag to a Report Group \(Console\) + +You can use the CodeBuild console to add one or more tags to a CodeBuild report group\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Report groups**, choose the name of the report group where you want to add tags\. + +1. In the navigation pane, choose **Settings**\. + +1. If no tags have been added to the report group, choose **Add tag**\. You can also choose **Edit**, and then choose **Add tag**\. + +1. In **Key**, enter a name for the tag\. You can add an optional value for the tag in **Value**\. + +1. \(Optional\) To add another tag, choose **Add tag** again\. + +1. When you have finished adding tags, choose **Submit**\. + +## Add a Tag to a Report Group \(AWS CLI\) + +To add a tag to a report group when you create it, see [Create a report group \(CLI\)](test-report-group-create-cli.md)\. In `CreateReportGroup.json`, add your tags\. + + To add tags to an existing report group, see [Update a report group \(CLI\)](update-report-group-cli.md) and add your tags in `UpdateReportGroupInput.json`\. + +In these steps, we assume that you have already installed a recent version of the AWS CLI or updated to the current version\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)\. \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-delete.md b/doc_source/how-to-tag-report-group-delete.md new file mode 100644 index 0000000..cee0cf9 --- /dev/null +++ b/doc_source/how-to-tag-report-group-delete.md @@ -0,0 +1,35 @@ +# Remove a Tag from a Report Group + +You can remove one or more tags associated with a report group\. Removing a tag does not delete the tag from other AWS resources that are associated with that tag\. + +**Important** +Removing tags for a report group can impact access to that report group\. Before you remove a tag from a report group, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as report groups\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +## Remove a Tag from a Report Group \(Console\) + +You can use the CodeBuild console to remove the association between a tag and a CodeBuild report group\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Report groups**, choose the name of the report group where you want to remove tags\. + +1. In the navigation pane, choose **Settings**\. + +1. Choose **Edit**\. + +1. Find the tag you want to remove, and then choose **Remove tag**\. + +1. When you have finished removing tags, choose **Submit**\. + +## Remove a Tag from a Report Group \(AWS CLI\) + +Follow these steps to use the AWS CLI to remove a tag from a CodeBuild report group\. Removing a tag does not delete it, but simply removes the association between the tag and the report group\. + +**Note** +If you delete a CodeBuild report group, all tag associations are removed from the deleted report group\. You do not have to remove tags before you delete a report group\. + + To delete one or more tags from a report group, see [Edit Tags for a Report Group \(AWS CLI\)](how-to-tag-report-group-update.md#how-to-tag-report-group-update-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: + +``` +"tags: []" +``` \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-list.md b/doc_source/how-to-tag-report-group-list.md new file mode 100644 index 0000000..04c2590 --- /dev/null +++ b/doc_source/how-to-tag-report-group-list.md @@ -0,0 +1,72 @@ +# View Tags for a Report Group + +Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. + +## View Tags for a Report Group \(Console\) + +You can use the CodeBuild console to view the tags associated with a CodeBuild report group\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Report groups**, choose the name of the report group where you want to view tags\. + +1. In the navigation pane, choose **Settings**\. + +## View Tags for a Report Group \(AWS CLI\) + +Follow these steps to use the AWS CLI to view the AWS tags for a report group\. If no tags have been added, the returned tags list is empty\. + +1. Use the console or the AWS CLI to locate the ARN of your report group\. Make a note of it\. + +------ +#### [ AWS CLI ] + + Run the following comand\. + + ``` + aws list-report-groups + ``` + + This command returns JSON\-formatted information similar to the following: + + ``` + { + "reportGroups": [ + "arn:aws:codebuild:region:123456789012:report-group/report-group-1", + "arn:aws:codebuild:region:123456789012:report-group/report-group-2", + "arn:aws:codebuild:region:123456789012:report-group/report-group-3" + ] + } + ``` + + A report group ARN ends with its name, which you can use to identify the ARN for your report group\. + +------ +#### [ Console ] + + 1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + + 1. In **Report groups**, choose the name of your report group with the tags you want to view\. + + 1. In **Configuration** locate your report group's ARN\. + +------ + +1. Run the following command\. Use the ARN you made a note of for the `--report-group-arns` parameter\. + + ``` + aws codebuild batch-get-report-groups --report-group-arns arn:aws:codebuild:region:123456789012:report-group/report-group-name + ``` + + If successful, this command returns JSON\-formatted information that contains a `tags` section similar to the following: + + ``` + { + ... + "tags": { + "Status": "Secret", + "Project": "TestBuild" + } + ... + } + ``` \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-update.md b/doc_source/how-to-tag-report-group-update.md new file mode 100644 index 0000000..919a356 --- /dev/null +++ b/doc_source/how-to-tag-report-group-update.md @@ -0,0 +1,28 @@ +# Edit Tags for a Report Group + +You can change the value for a tag associated with a report group\. You can also change the name of the key, which is equivalent to removing the current tag and adding a different one with the new name and the same value as the other key\. Keep in mind that there are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. + +**Important** +Editing tags for a report group can impact access to that report group\. Before you edit the name \(key\) or value of a tag for a report group, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as report groups\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. + +## Edit a Tag for a Report Group \(Console\) + +You can use the CodeBuild console to edit the tags associated with a CodeBuild report group\. + +1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. + +1. In **Report groups**, choose the name of the report group where you want to edit tags\. + +1. In the navigation pane, choose **Settings**\. + +1. Choose **Edit**\. + +1. Do one of the following: + + To change the tag, enter a new name in **Key**\. Changing the name of the tag is the equivalent of removing a tag and adding a new tag with the new key name\. + + To change the value of a tag, enter a new value\. If you want to change the value to nothing, delete the current value and leave the field blank\. + +1. When you have finished editing tags, choose **Submit**\. + +## Edit Tags for a Report Group \(AWS CLI\) + + To add, change, or delete tags from a report group, see [Update a report group \(CLI\)](update-report-group-cli.md)\. Update the tags in `UpdateReportGroupInput.json`\. \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group.md b/doc_source/how-to-tag-report-group.md new file mode 100644 index 0000000..25b26fb --- /dev/null +++ b/doc_source/how-to-tag-report-group.md @@ -0,0 +1,17 @@ +# Tagging Report Groups in AWS CodeBuild + +A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Each AWS tag has two parts: ++ A *tag key* \(for example, `CostCenter`, `Environment`, `Project`, or `Secret`\)\. Tag keys are case sensitive\. ++ An optional field known as a *tag value* \(for example, `111122223333`, `Production`, or a team name\)\. Omitting the tag value is the same as using an empty string\. Like tag keys, tag values are case sensitive\. + +Together these are known as key\-value pairs\. For limits on the number of tags you can have on a report group and restrictions on tag keys and values, see [Tags](limits.md#tag-limits)\. + +Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild report group that you assign to an Amazon S3 bucket\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. + +In CodeBuild, the primary resources are the report group and the project\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a report group\. In addition to identifying, organizing, and tracking your report group with tags, you can use tags in IAM policies to help control who can view and interact with your report group\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. + +**Topics** ++ [Add a Tag to a Report Group](how-to-tag-report-group-add.md) ++ [View Tags for a Report Group](how-to-tag-report-group-list.md) ++ [Edit Tags for a Report Group](how-to-tag-report-group-update.md) ++ [Remove a Tag from a Report Group](how-to-tag-report-group-delete.md) \ No newline at end of file diff --git a/doc_source/index.md b/doc_source/index.md index e8da06b..0966c8c 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -95,6 +95,11 @@ Amazon's trademarks and trade dress may not be used in + [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) + + [Add a Tag to a Project](how-to-tag-project-add.md) + + [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) + [Working with builds in AWS CodeBuild](builds-working.md) + [Run a build in AWS CodeBuild](run-build.md) + [View build details in AWS CodeBuild](view-build-details.md) @@ -116,6 +121,11 @@ Amazon's trademarks and trade dress may not be used in + [Specify test files](report-group-test-cases.md) + [Specify test commands](report-group-test-case-commands.md) + [Report group naming](test-report-group-naming.md) + + [Tagging Report Groups in AWS CodeBuild](how-to-tag-report-group.md) + + [Add a Tag to a Report Group](how-to-tag-report-group-add.md) + + [View Tags for a Report Group](how-to-tag-report-group-list.md) + + [Edit Tags for a Report Group](how-to-tag-report-group-update.md) + + [Remove a Tag from a Report Group](how-to-tag-report-group-delete.md) + [Working with shared report groups](report-groups-sharing.md) + [Working with reports](test-report.md) + [Working with test report permissions](test-permissions.md) diff --git a/doc_source/limits.md b/doc_source/limits.md index b7ae588..12b9351 100644 --- a/doc_source/limits.md +++ b/doc_source/limits.md @@ -44,4 +44,17 @@ The following tables list the current quotas in AWS CodeBuild\. These quotas are | --- | --- | | Maximum duration a test report is available after it is created | 30 days | | Maximum number of report groups per AWS account | 1000 | -| Maximum number of test cases per report | 500 | \ No newline at end of file +| Maximum number of test cases per report | 500 | + +## Tags + + Tag limits apply to tags on CodeBuild build project 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/report-create.md b/doc_source/report-create.md index 045b515..eee2c43 100644 --- a/doc_source/report-create.md +++ b/doc_source/report-create.md @@ -1,10 +1,5 @@ # Create a test report - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - To create a test report, you run a build project that is configured with one to five report groups in its buildspec file\. A test report is created during the run\. It contains the results of the test cases that are specified for the report groups\. A new test report is generated for each subsequent build that uses the same buildspec file\. **To create a test report** diff --git a/doc_source/report-group-create.md b/doc_source/report-group-create.md index 7f5b3b4..52cbea4 100644 --- a/doc_source/report-group-create.md +++ b/doc_source/report-group-create.md @@ -1,11 +1,6 @@ # Create a report group - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - - You can use the AWS CodeBuild console, the AWS CLI, or a buildspec file to create a report group\. Your IAM role must have the permissions required to create a report group\. For more information, see [Working with test report permissions](test-permissions.md)\. + You can use the CodeBuild console, the AWS CLI, or a buildspec file to create a report group\. Your IAM role must have the permissions required to create a report group\. For more information, see [Working with test report permissions](test-permissions.md)\. **Topics** + [Create a report group \(buildspec\)](test-report-group-create-buildspec.md) diff --git a/doc_source/report-group-export-settings.md b/doc_source/report-group-export-settings.md index 49e404e..a96904d 100644 --- a/doc_source/report-group-export-settings.md +++ b/doc_source/report-group-export-settings.md @@ -1,14 +1,18 @@ # Update a report group - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - - When you update a report group, you can specify information about whether to export the raw test result data to files in an S3 bucket\. If you choose to export to an S3 bucket, you can specify the following for your report group: + 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\. - For more information, see [Data encryption](security-encryption.md)\. \ No newline at end of file + 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 CodeBuildTagging a Report Group](how-to-tag-report-group.md)\. + +**Note** +The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. + +**Topics** ++ [Update a report group \(console\)](update-report-group-console.md) ++ [Update a report group \(CLI\)](update-report-group-cli.md) \ No newline at end of file diff --git a/doc_source/report-group-test-case-commands.md b/doc_source/report-group-test-case-commands.md index b6a7086..36c6de4 100644 --- a/doc_source/report-group-test-case-commands.md +++ b/doc_source/report-group-test-case-commands.md @@ -1,10 +1,5 @@ # Specify test commands - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You specify the commands that run your test cases in the `commands` section of your buildspec file\. These commands run the test cases specified for your report groups in the `reports` section of your buildspec file\. The following is a sample `commands` section that includes commands to run the tests in test files: ``` diff --git a/doc_source/report-group-test-cases.md b/doc_source/report-group-test-cases.md index af85125..81756ec 100644 --- a/doc_source/report-group-test-cases.md +++ b/doc_source/report-group-test-cases.md @@ -1,13 +1,8 @@ # Specify test files - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. - The following is a sample `reports` section that specifies two report groups for a build project\. One is specified with its ARN, the other with a name\. The `files` section specifies the files that contain the test case results\. The optional `base-directory` section specifies the directory where the test case files are located\. The optional `discard-paths` section specifies whether paths to test result files uploaded to an S3 bucket are discarded\. + The following is a sample `reports` section that specifies two report groups for a build project\. One is specified with its ARN, the other with a name\. The `files` section specifies the files that contain the test case results\. The optional `base-directory` section specifies the directory where the test case files are located\. The optional `discard-paths` section specifies whether paths to test result files uploaded to an Amazon S3 bucket are discarded\. ``` reports: diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 1216bd8..95f95b9 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -254,11 +254,11 @@ You can create a filter that triggers a build only when the head commit message "filterGroups": [ [ { - "type": "EVENT", + "type": "EVENT", "pattern": "PUSH" }, { - "type": "COMMIT_MESSAGE", + "type": "COMMIT_MESSAGE", "pattern": "\[CodeBuild\]" } ] diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index b34bcb9..a35186c 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -347,8 +347,8 @@ The build project in this example uses source code in the GitHub [AWS Samples](h [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 Running command echo "Installing Go version 1.13 ..." - Installing Go version 1.13 ... + [Container] Date Time Running command echo "Installing Go version 1.13 ..." + Installing Go version 1.12 ... [Container] Date Time Running command echo "Installing Node.js version 10 ..." Installing Node.js version 10 ... diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index ae1445d..be7fe4a 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -1,10 +1,5 @@ # Create a test report in CodeBuild using the AWS CLI sample - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - Tests that you specify in your buildspec file are run during your build\. This sample shows you how to use the AWS CLI to incorporate tests into builds in CodeBuild\. You can use JUnit to create unit tests, or you can use another tool to create configuration tests\. You can then evaluate the test results to fix issues or optimize your application\. You can use the CodeBuild API or the AWS CodeBuild console to access the test results\. This sample shows you how to configure your report so its test results are exported to an S3 bucket\. diff --git a/doc_source/test-permissions.md b/doc_source/test-permissions.md index afb448d..3882e67 100644 --- a/doc_source/test-permissions.md +++ b/doc_source/test-permissions.md @@ -1,10 +1,5 @@ # Working with test report permissions - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - This topic describes important information about permissions related to test reporting\. **Topics** @@ -14,11 +9,6 @@ ## Create a role for test reports - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - 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` @@ -80,12 +70,10 @@ } ``` -## Permissions for test reporting operations - +**Note** +The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | +## Permissions for test reporting operations You can specify permissions for the following test reporting CodeBuild API operations: + `BatchGetReportGroups` @@ -103,11 +91,6 @@ For more information, see [AWS CodeBuild permissions reference](auth-and-access- ## Test reporting permissions examples - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - For information about sample policies related to test reporting, see the following: + [Allow a user to change a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-change-report-group) + [Allow a user to create a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-report-group) diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md index 2574943..034c32a 100644 --- a/doc_source/test-report-group-create-buildspec.md +++ b/doc_source/test-report-group-create-buildspec.md @@ -1,10 +1,5 @@ # Create a report group \(buildspec\) - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Update a report group](report-group-export-settings.md)\. **To create a report group using a buildspec file** diff --git a/doc_source/test-report-group-create-cfn.md b/doc_source/test-report-group-create-cfn.md index bd79f8c..2a93288 100644 --- a/doc_source/test-report-group-create-cfn.md +++ b/doc_source/test-report-group-create-cfn.md @@ -1,13 +1,8 @@ # Create a report group \(AWS CloudFormation\) + **To create a test report using the AWS CloudFormation template** -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - - **To create a test report** - - You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see the [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. + You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. The following AWS CloudFormation YAML template creates a report group that does not export raw test result files\. @@ -22,7 +17,7 @@ Resources: ExportConfigType: NO_EXPORT ``` - The following AWS CloudFormation YAML template creates a report group that exports raw test result files to an S3 bucket\. + The following AWS CloudFormation YAML template creates a report group that exports raw test result files to an Amazon S3 bucket\. ``` Resources: @@ -39,4 +34,7 @@ Resources: Packaging: ZIP EncryptionKey: my-KMS-encryption-key EncryptionDisabled: false -``` \ No newline at end of file +``` + +**Note** +The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. \ No newline at end of file diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index b36b6a4..6b5e76c 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -1,15 +1,11 @@ # Create a report group \(CLI\) - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - **To create a test report** -+ Create a file named `CreateReportGroup.json`\. + +1. Create a file named `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 S3 bucket\. + + Use the following JSON to specify that your test report group exports raw test result files to an Amazon S3 bucket\. ``` { @@ -23,7 +19,13 @@ "packaging": "NONE | ZIP", "encryptionDisabled": "false", "encryptionKey": "your-key" - } + }, + "tags": [ + { + "key": "tag-key", + "value": "tag-value" + } + ] } ``` @@ -39,6 +41,8 @@ } } ``` +**Note** +The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. 1. Run the following command: diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index a1d2b33..68878e5 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -1,10 +1,5 @@ # Create a report group \(console\) - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - **To create a test report** 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -15,7 +10,9 @@ 1. For **Report group name**, enter a name for your report group\. -1. If you want to upload the raw data of your test report results to an S3 bucket: +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. Select **Backup to Amazon S3**\. @@ -31,5 +28,7 @@ + **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)\. +**Note** +The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. 1. Choose **Create report group**\. \ No newline at end of file diff --git a/doc_source/test-report-group-naming.md b/doc_source/test-report-group-naming.md index aa5ad0c..3a0aef2 100644 --- a/doc_source/test-report-group-naming.md +++ b/doc_source/test-report-group-naming.md @@ -1,10 +1,5 @@ # Report group naming - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - When you use the AWS CLI or the AWS CodeBuild console to create a report group, you specify a name for the report group\. If you use the buildspec to create a new report group, it is named using the format `project-name-report-group-name-specified-in-buildspec`\. All reports created by running builds of that build project belong to the new report group that has the new name\. If you do not want CodeBuild to create a new report group, specify the ARN of the report group in a build project's buildspec file\. You can specify a report group's ARN in multiple build projects\. After each build project runs, the report group contains test reports created by each build project\. diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md index ab4c53e..05c7dac 100644 --- a/doc_source/test-report-group.md +++ b/doc_source/test-report-group.md @@ -1,10 +1,5 @@ # Working with report groups - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - A *report group* contains test reports and specifies shared settings\. You use the buildspec file to specify the test cases to run and the commands to run them when it builds\. For each report group configured in a build project, a run of the build project creates a test report\. Multiple runs of a build project configured with a report group create multiple test reports in that report group, each with results of the the same test cases specified for that report group\. The test cases are specified for a report group in the buildspec file of a build project\. You can specify up to 5 report groups in one build project\. When your run a build, all the test cases run\. A new test report is created with the results of each test case specified for a report group\. Each time you run a new build, the test cases run and a new test report is created with the new test results\. @@ -17,4 +12,5 @@ A *report group* contains test reports and specifies shared settings\. You use t + [Specify test files](report-group-test-cases.md) + [Specify test commands](report-group-test-case-commands.md) + [Report group naming](test-report-group-naming.md) ++ [Tagging Report Groups in AWS CodeBuild](how-to-tag-report-group.md) + [Working with shared report groups](report-groups-sharing.md) \ No newline at end of file diff --git a/doc_source/test-report.md b/doc_source/test-report.md index a3e6f4c..5e89eb3 100644 --- a/doc_source/test-report.md +++ b/doc_source/test-report.md @@ -1,10 +1,5 @@ # Working with reports - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - A report contains the results of test cases that are specified for one report group\. A test report is created during the run of a build project\. You specify a report group, test case files, and commands to run the test cases in its buildspec file\. Each time the test cases run, a new test report is created in the report group\. A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Update a report group](report-group-export-settings.md)\. diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index 93a0c0d..00118ae 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -1,17 +1,15 @@ # Working with test reporting in AWS CodeBuild - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - -You can create reports in AWS 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 test file format can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. +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 test file format can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. You can use a test report to help troubleshoot a problem during a build run\. If you have many test reports from multiple builds of a build project, you can use your test reports to view trends and test and failure rates to help you optimize builds\. -A report expires 30 days after it was created\. You cannot view an expired test report\. If you want to keep test reports for more than 30 days, you can export your test results' raw data files to an S3 bucket\. Exported test files do not expire\. Information about the S3 bucket is specified when you create the report group\. +A report expires 30 days after it was created\. You cannot view an expired test report\. If you want to keep test reports for more than 30 days, you can export your test results' raw data files to an Amazon S3 bucket\. Exported test files do not expire\. Information about the S3 bucket is specified when you create the report group\. + +**Note** +The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. **Topics** + [Create a test report](report-create.md) diff --git a/doc_source/test-view-reports.md b/doc_source/test-view-reports.md index 5f394ce..0f585d6 100644 --- a/doc_source/test-view-reports.md +++ b/doc_source/test-view-reports.md @@ -1,10 +1,5 @@ # View test reports - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - You can view details about a test report, such as information about its test cases, pass and fail numbers, and how long it took for it to run\. You can view test reports grouped by build run, report group, or your AWS account\. Choose a test report in the console to see its details and results of its test cases\. You can see view test reports that are not expired\. Test reports expire 30 days after they are created\. You cannot view an expired report in CodeBuild\. @@ -16,11 +11,6 @@ ## View test reports for a build - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - **To view test reports for a build** 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -39,11 +29,6 @@ ## View test reports for a report group - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - **To view test reports in a report group** 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -56,11 +41,6 @@ ## View test reports in your AWS account - -| | -| --- | -| The test reporting feature is in preview release for CodeBuild and is subject to change\. | - **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/update-report-group-cli.md b/doc_source/update-report-group-cli.md index 2d19b29..47e07c8 100644 --- a/doc_source/update-report-group-cli.md +++ b/doc_source/update-report-group-cli.md @@ -18,7 +18,13 @@ "encryptionDisabled": "false", "encryptionKey": "your-key" } - } + }, + "tags": [ + { + "key": "tag-key", + "value": "tag-value" + } + ] } ``` @@ -35,6 +41,11 @@ } } ``` + + 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": [] + ``` 1. Run the following command: diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 757c6b3..d8177fc 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -2,7 +2,7 @@ This topic provides information about how to run the AWS CodeBuild agent and subscribe to notifications about new versions of the agent\. -## Test and debug on a local machine with the CodeBuild agent +## Test and debug on a local machine with the CodeBuild agent You can use the AWS CodeBuild agent to test and debug builds on a local machine\. @@ -16,7 +16,7 @@ codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] ``` - 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 `94467b3eeac4184d28a38feb27a1530691527dd49c17e30ad1b6331d791e82f5`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + 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 `bd69dbcdc9b3da66fd93de0b6d45534086367d6b48d3536d0248a01a459fb7e4`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: ``` docker inspect amazon/aws-codebuild-local diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 7b2ca10..d180e6e 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -14,4 +14,5 @@ You can perform these tasks when working with build projects: + [Edit AWS CodeBuild triggers](triggers-edit.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) \ No newline at end of file ++ [Working with shared projects](project-sharing.md) ++ [Tagging Projects in AWS CodeBuild](how-to-tag-project.md) \ No newline at end of file From 3287e6685b40d1920da64abcd3f3135d9dbe65a4 Mon Sep 17 00:00:00 2001 From: Rusty Conover Date: Thu, 28 May 2020 16:03:02 -0400 Subject: [PATCH 036/156] clarify the root user rather than "the root" --- doc_source/build-spec-ref.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 413bb12..ed8e3f4 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -133,7 +133,7 @@ The buildspec contains the following: + `version`: Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. **Note** Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec versions](#build-spec-ref-versions)\. -+ `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\. ++ `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\. + `env`: Optional sequence\. Represents information for one or more custom environment variables\. **Note** To protect sensitive information, the following are hidden in CodeBuild logs: @@ -492,4 +492,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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From e81fce5a359da9c319165b8c6aee56a56443881e Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 29 May 2020 10:50:28 -0700 Subject: [PATCH 037/156] General update. --- doc_source/build-caching.md | 6 +- doc_source/build-env-ref-available.md | 12 +- doc_source/build-spec-ref.md | 10 +- doc_source/create-project.md | 2 +- ...etting-started-cli-create-build-project.md | 6 +- .../getting-started-cli-monitor-build.md | 2 +- doc_source/getting-started-cli-run-build.md | 2 +- ...ng-started-create-build-project-console.md | 2 +- doc_source/history.md | 3 +- doc_source/how-to-tag-report-group-add.md | 12 +- doc_source/how-to-tag-report-group-delete.md | 8 +- doc_source/how-to-tag-report-group-list.md | 8 +- doc_source/how-to-tag-report-group-update.md | 6 +- doc_source/how-to-tag-report-group.md | 10 +- doc_source/index.md | 15 +- doc_source/report-group-export-settings.md | 2 +- doc_source/sample-bitbucket-pull-request.md | 146 ++++++++--------- doc_source/sample-build-notifications.md | 4 +- doc_source/sample-codedeploy.md | 2 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-efs.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-github-pull-request.md | 4 +- doc_source/sample-multi-in-out.md | 72 ++++----- doc_source/sample-runtime-versions.md | 4 +- doc_source/sample-test-report-cli.md | 151 +++++++++--------- doc_source/test-framework-reporting.md | 9 ++ .../test-report-group-create-console.md | 2 +- doc_source/test-report-group-naming.md | 2 +- doc_source/test-report-group.md | 6 +- doc_source/test-report-jasmine.md | 91 +++++++++++ doc_source/test-report-jest.md | 59 +++++++ doc_source/test-report-pytest.md | 36 +++++ doc_source/test-report-rspec.md | 31 ++++ doc_source/test-reporting.md | 3 +- doc_source/update-report-group-cli.md | 4 +- doc_source/update-report-group-console.md | 2 +- 38 files changed, 490 insertions(+), 254 deletions(-) create mode 100644 doc_source/test-framework-reporting.md create mode 100644 doc_source/test-report-jasmine.md create mode 100644 doc_source/test-report-jest.md create mode 100644 doc_source/test-report-pytest.md create mode 100644 doc_source/test-report-rspec.md diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index fcca734..918eed5 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -77,7 +77,7 @@ CodeBuildProject: Type: AWS::CodeBuild::Project Properties: Name: MyProject - ServiceRole: service-role + ServiceRole: Artifacts: Type: S3 Location: myBucket @@ -87,13 +87,13 @@ CodeBuildProject: Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:2.0 + Image: aws/codebuild/standard:4.0 Certificate: bucket/cert.zip # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE PrivilegedMode: true Source: Type: GITHUB - Location: github-location + Location: InsecureSsl: true GitCloneDepth: 1 ReportBuildStatus: false diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 3954681..4f058e9 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -7,15 +7,17 @@ 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: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: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\-aarch64\-standard:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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) | -| 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) | +| 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\-aarch64\-standard:1\.0 ¹ | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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 | - 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:2.0` instead of a more granular version, such as `aws/codebuild/amazonlinux2-x86_64-standard:2.0-1.0.0`\. +¹ 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)\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 413bb12..7387157 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -133,7 +133,7 @@ The buildspec contains the following: + `version`: Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. **Note** Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec versions](#build-spec-ref-versions)\. -+ `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\. ++ `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\. + `env`: Optional sequence\. Represents information for one or more custom environment variables\. **Note** To protect sensitive information, the following are hidden in CodeBuild logs: @@ -224,12 +224,12 @@ Commands in some build phases might not be run if commands in earlier build phas + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + `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\. + `discard-paths`: Optional mapping\. Represents whether paths to test result files uploaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TesResult.xml`\. - + `file-format`: Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: - + `JunitXml` + + `file-format`: Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: + `CucumberJson` - + `VisualStudioTrx` - + `VisualStudioTrx` + + `JunitXml` + + `NunitXml` + `TestNGXml` + + `VisualStudioTrx` + `artifacts`: 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\. + `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`\)\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index fbcd9b2..8052b10 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -468,7 +468,7 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro + *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`, and `WINDOWS_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:2.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)\. + + *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, and 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*\. diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 6c9df6d..92bd3d1 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:2.0", + "image": "aws/codebuild/amazonlinux2-x86_64-standard:3.0", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "serviceIAMRole" @@ -47,7 +47,7 @@ For this build environment, you instruct CodeBuild to use a Docker image that co + 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:2.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`, `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\. 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`\)\. @@ -79,7 +79,7 @@ Other available values in the original JSON\-formatted data, such as `descriptio "created": 1472661575.244, "environment": { "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "type": "LINUX_CONTAINER", "environmentVariables": [] }, diff --git a/doc_source/getting-started-cli-monitor-build.md b/doc_source/getting-started-cli-monitor-build.md index 976a7c3..c204591 100644 --- a/doc_source/getting-started-cli-monitor-build.md +++ b/doc_source/getting-started-cli-monitor-build.md @@ -52,7 +52,7 @@ If successful, data similar to this appears in the output\. "buildStatus": "SUCCEEDED", "environment": { "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "type": "LINUX_CONTAINER", "environmentVariables": [] }, diff --git a/doc_source/getting-started-cli-run-build.md b/doc_source/getting-started-cli-run-build.md index 257ef82..00fe214 100644 --- a/doc_source/getting-started-cli-run-build.md +++ b/doc_source/getting-started-cli-run-build.md @@ -29,7 +29,7 @@ In this step, you instruct AWS CodeBuild to run the build with the settings in t "buildStatus": "IN_PROGRESS", "environment": { "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "type": "LINUX_CONTAINER", "environmentVariables": [] }, diff --git a/doc_source/getting-started-create-build-project-console.md b/doc_source/getting-started-create-build-project-console.md index 1bdbd0e..82a7232 100644 --- a/doc_source/getting-started-create-build-project-console.md +++ b/doc_source/getting-started-create-build-project-console.md @@ -33,7 +33,7 @@ Both options include administrator permissions that allow you to create a build 1. For **Runtime\(s\)**, choose **Standard**\. -1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. +1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. 1. In **Service role**, leave **New service role** selected, and leave **Role name** unchanged\. diff --git a/doc_source/history.md b/doc_source/history.md index 82bac5d..8d42088 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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: **May 21, 2020 ++ **Latest documentation update: **May 29, 2020 | Change | Description | Date | | --- |--- |--- | +| [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 | diff --git a/doc_source/how-to-tag-report-group-add.md b/doc_source/how-to-tag-report-group-add.md index f3d47f2..4d33edc 100644 --- a/doc_source/how-to-tag-report-group-add.md +++ b/doc_source/how-to-tag-report-group-add.md @@ -1,6 +1,6 @@ -# Add a Tag to a Report Group +# Add a tag to a report group -Adding tags to a report group can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a report group\. Keep in mind that there are limits on the number of tags you can have on a report group\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the report group based on these tags\. You can use the the CodeBuild console or the AWS CLI to add tags to a report group\. +Adding tags to a report group can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a report group\. Keep in mind that there are limits on the number of tags you can have on a report group\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the report group based on these tags\. You can use the CodeBuild console or the AWS CLI to add tags to a report group\. **Important** Adding tags to a report group can impact access to that report group\. Before you add a tag to a report group, make sure to review any IAM policies that might use tags to control access to resources such as report groups\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. @@ -8,10 +8,10 @@ Adding tags to a report group can impact access to that report group\. Before yo For more information about adding tags to a report group when you create it, see [Create a report group \(console\)](test-report-group-create-console.md)\. **Topics** -+ [Add a Tag to a Report Group \(Console\)](#how-to-tag-report-group-add-console) -+ [Add a Tag to a Report Group \(AWS CLI\)](#how-to-tag-report-group-add-cli) ++ [Add a tag to a report group \(console\)](#how-to-tag-report-group-add-console) ++ [Add a tag to a report group \(AWS CLI\)](#how-to-tag-report-group-add-cli) -## Add a Tag to a Report Group \(Console\) +## Add a tag to a report group \(console\) You can use the CodeBuild console to add one or more tags to a CodeBuild report group\. @@ -29,7 +29,7 @@ You can use the CodeBuild console to add one or more tags to a CodeBuild report 1. When you have finished adding tags, choose **Submit**\. -## Add a Tag to a Report Group \(AWS CLI\) +## Add a tag to a report group \(AWS CLI\) To add a tag to a report group when you create it, see [Create a report group \(CLI\)](test-report-group-create-cli.md)\. In `CreateReportGroup.json`, add your tags\. diff --git a/doc_source/how-to-tag-report-group-delete.md b/doc_source/how-to-tag-report-group-delete.md index cee0cf9..e766925 100644 --- a/doc_source/how-to-tag-report-group-delete.md +++ b/doc_source/how-to-tag-report-group-delete.md @@ -1,11 +1,11 @@ -# Remove a Tag from a Report Group +# Remove a tag from a report group You can remove one or more tags associated with a report group\. Removing a tag does not delete the tag from other AWS resources that are associated with that tag\. **Important** Removing tags for a report group can impact access to that report group\. Before you remove a tag from a report group, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as report groups\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. -## Remove a Tag from a Report Group \(Console\) +## Remove a tag from a report group \(console\) You can use the CodeBuild console to remove the association between a tag and a CodeBuild report group\. @@ -21,14 +21,14 @@ You can use the CodeBuild console to remove the association between a tag and a 1. When you have finished removing tags, choose **Submit**\. -## Remove a Tag from a Report Group \(AWS CLI\) +## Remove a tag from a report group \(AWS CLI\) Follow these steps to use the AWS CLI to remove a tag from a CodeBuild report group\. Removing a tag does not delete it, but simply removes the association between the tag and the report group\. **Note** If you delete a CodeBuild report group, all tag associations are removed from the deleted report group\. You do not have to remove tags before you delete a report group\. - To delete one or more tags from a report group, see [Edit Tags for a Report Group \(AWS CLI\)](how-to-tag-report-group-update.md#how-to-tag-report-group-update-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 report group, see [Edit tags for a report group \(AWS CLI\)](how-to-tag-report-group-update.md#how-to-tag-report-group-update-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: ``` "tags: []" diff --git a/doc_source/how-to-tag-report-group-list.md b/doc_source/how-to-tag-report-group-list.md index 04c2590..4073459 100644 --- a/doc_source/how-to-tag-report-group-list.md +++ b/doc_source/how-to-tag-report-group-list.md @@ -1,8 +1,8 @@ -# View Tags for a Report Group +# View tags for a report group Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. -## View Tags for a Report Group \(Console\) +## View tags for a report group \(console\) You can use the CodeBuild console to view the tags associated with a CodeBuild report group\. @@ -12,7 +12,7 @@ You can use the CodeBuild console to view the tags associated with a CodeBuild r 1. In the navigation pane, choose **Settings**\. -## View Tags for a Report Group \(AWS CLI\) +## View tags for a report group \(AWS CLI\) Follow these steps to use the AWS CLI to view the AWS tags for a report group\. If no tags have been added, the returned tags list is empty\. @@ -21,7 +21,7 @@ Follow these steps to use the AWS CLI to view the AWS tags for a report group\. ------ #### [ AWS CLI ] - Run the following comand\. + Run the following command\. ``` aws list-report-groups diff --git a/doc_source/how-to-tag-report-group-update.md b/doc_source/how-to-tag-report-group-update.md index 919a356..c8c898a 100644 --- a/doc_source/how-to-tag-report-group-update.md +++ b/doc_source/how-to-tag-report-group-update.md @@ -1,11 +1,11 @@ -# Edit Tags for a Report Group +# Edit tags for a report group You can change the value for a tag associated with a report group\. You can also change the name of the key, which is equivalent to removing the current tag and adding a different one with the new name and the same value as the other key\. Keep in mind that there are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. **Important** Editing tags for a report group can impact access to that report group\. Before you edit the name \(key\) or value of a tag for a report group, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as report groups\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. -## Edit a Tag for a Report Group \(Console\) +## Edit a tag for a report group \(console\) You can use the CodeBuild console to edit the tags associated with a CodeBuild report group\. @@ -23,6 +23,6 @@ You can use the CodeBuild console to edit the tags associated with a CodeBuild r 1. When you have finished editing tags, choose **Submit**\. -## Edit Tags for a Report Group \(AWS CLI\) +## Edit tags for a report group \(AWS CLI\) To add, change, or delete tags from a report group, see [Update a report group \(CLI\)](update-report-group-cli.md)\. Update the tags in `UpdateReportGroupInput.json`\. \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group.md b/doc_source/how-to-tag-report-group.md index 25b26fb..6af41f8 100644 --- a/doc_source/how-to-tag-report-group.md +++ b/doc_source/how-to-tag-report-group.md @@ -1,4 +1,4 @@ -# Tagging Report Groups in AWS CodeBuild +# Tagging report groups in AWS CodeBuild A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Each AWS tag has two parts: + A *tag key* \(for example, `CostCenter`, `Environment`, `Project`, or `Secret`\)\. Tag keys are case sensitive\. @@ -11,7 +11,7 @@ Tags help you identify and organize your AWS resources\. Many AWS services suppo In CodeBuild, the primary resources are the report group and the project\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a report group\. In addition to identifying, organizing, and tracking your report group with tags, you can use tags in IAM policies to help control who can view and interact with your report group\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. **Topics** -+ [Add a Tag to a Report Group](how-to-tag-report-group-add.md) -+ [View Tags for a Report Group](how-to-tag-report-group-list.md) -+ [Edit Tags for a Report Group](how-to-tag-report-group-update.md) -+ [Remove a Tag from a Report Group](how-to-tag-report-group-delete.md) \ No newline at end of file ++ [Add a tag to a report group](how-to-tag-report-group-add.md) ++ [View tags for a report group](how-to-tag-report-group-list.md) ++ [Edit tags for a report group](how-to-tag-report-group-update.md) ++ [Remove a tag from a report group](how-to-tag-report-group-delete.md) \ No newline at end of file diff --git a/doc_source/index.md b/doc_source/index.md index 0966c8c..03f6e80 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -121,15 +121,20 @@ Amazon's trademarks and trade dress may not be used in + [Specify test files](report-group-test-cases.md) + [Specify test commands](report-group-test-case-commands.md) + [Report group naming](test-report-group-naming.md) - + [Tagging Report Groups in AWS CodeBuild](how-to-tag-report-group.md) - + [Add a Tag to a Report Group](how-to-tag-report-group-add.md) - + [View Tags for a Report Group](how-to-tag-report-group-list.md) - + [Edit Tags for a Report Group](how-to-tag-report-group-update.md) - + [Remove a Tag from a Report Group](how-to-tag-report-group-delete.md) + + [Tagging report groups in AWS CodeBuild](how-to-tag-report-group.md) + + [Add a tag to a report group](how-to-tag-report-group-add.md) + + [View tags for a report group](how-to-tag-report-group-list.md) + + [Edit tags for a report group](how-to-tag-report-group-update.md) + + [Remove a tag from a report group](how-to-tag-report-group-delete.md) + [Working with shared report groups](report-groups-sharing.md) + [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) + + [Set up test reporting with Jasmine](test-report-jasmine.md) + + [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) + [Security in AWS CodeBuild](security.md) + [Data protection in AWS CodeBuild](data-protection.md) + [Data encryption](security-encryption.md) diff --git a/doc_source/report-group-export-settings.md b/doc_source/report-group-export-settings.md index a96904d..e5dea19 100644 --- a/doc_source/report-group-export-settings.md +++ b/doc_source/report-group-export-settings.md @@ -8,7 +8,7 @@ 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 CodeBuildTagging a Report Group](how-to-tag-report-group.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)\. **Note** The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index b453b7f..9918900 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -144,12 +144,12 @@ In this example, a webhook filter group triggers a build for a push event when t ``` "filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" - } - ] + [ + { + "type": "EVENT", + "pattern": "PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" + } + ] ] ``` @@ -159,30 +159,30 @@ In this example, a webhook filter group triggers a build for a push event when t ``` "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$" - } - ] + [ + { + "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$" + } + ] ] ``` @@ -190,17 +190,17 @@ In this example, a webhook filter group triggers a build for a push event when t ``` "filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" - }, - { - "type": "HEAD_REF", - "pattern": "^refs/tags/.*", - "excludeMatchedPattern": true - } - ] + [ + { + "type": "EVENT", + "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" + }, + { + "type": "HEAD_REF", + "pattern": "^refs/tags/.*", + "excludeMatchedPattern": true + } + ] ] ``` @@ -211,16 +211,16 @@ You can create a filter that triggers a build only when a change is made by a Bi ``` "filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" - }, - { - "type": "ACTOR_ACCOUNT_ID", - "pattern": "actor-account-id" - } - ] + [ + { + "type": "EVENT", + "pattern": "PUSH, PULL_REQUEST_CREATED, PULL_REQUEST_UPDATED, PULL_REQUEST_MERGED" + }, + { + "type": "ACTOR_ACCOUNT_ID", + "pattern": "actor-account-id" + } + ] ] ``` @@ -228,34 +228,34 @@ You can create a filter that triggers a build only when files with names that ma ``` "filterGroups": [ - [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "FILE_PATH", - "pattern": "^buildspec.*" - } - ] + [ + { + "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\\\]*\. +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": [ + "filterGroups": [ [ - { - "type": "EVENT", - "pattern": "PUSH" - }, - { - "type": "COMMIT_MESSAGE", - "pattern": "\[CodeBuild\]" - } + { + "type": "EVENT", + "pattern": "PUSH" + }, + { + "type": "COMMIT_MESSAGE", + "pattern": "\[CodeBuild\]" + } ] -] + ] ``` ### Filter Bitbucket webhook events \(AWS CloudFormation\) @@ -276,7 +276,7 @@ CodeBuildProject: Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:2.0 + Image: aws/codebuild/standard:4.0 Source: Type: BITBUCKET Location: source-location diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 07bf56c..785f2fb 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -296,7 +296,7 @@ Build state change notifications use the following format: "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" }, "environment": { - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "privileged-mode": false, "compute-type": "BUILD_GENERAL1_SMALL", "type": "LINUX_CONTAINER", @@ -427,7 +427,7 @@ Build phase change notifications use the following format: "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" }, "environment": { - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "privileged-mode": false, "compute-type": "BUILD_GENERAL1_SMALL", "type": "LINUX_CONTAINER", diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 892c66b..1de2d69 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -139,7 +139,7 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP }, "environment": { "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "arn:aws:iam::account-ID:role/role-name", diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 7c8f2ea..967f1c5 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -86,7 +86,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. For **Runtime**, choose **Standard**\. - 1. For **Image**, choose **aws/codebuild/standard:2\.0**\. + 1. For **Image**, choose **aws/codebuild/standard:4\.0**\. 1. Because you use this build project to build a Docker image, select **Privileged**\. **Note** @@ -112,7 +112,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo }, "environment": { "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [ { diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 0986ed8..272dbce 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -37,7 +37,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains }, "environment": { "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "computeType": "BUILD_GENERAL1_SMALL" }, "serviceRole": "arn:aws:iam::account-ID:role/role-name", diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 084301c..c23e5ac 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -79,7 +79,7 @@ Data in transit for your file system is encrypted\. To encrypt data in transit u 1. From **Runtime\(s\)**, choose **Standard**\. -1. From **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:2\.0**\. +1. From **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. 1. From **Environment type**, choose **Linux**\. diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index c81864a..c647522 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -262,7 +262,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi eb_codebuild_settings: CodeBuildServiceRole: my-service-role-name ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:2.0 + Image: aws/codebuild/standard:4.0 Timeout: 60 ``` diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 95f95b9..4af9836 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -248,7 +248,7 @@ You can create a filter that triggers a build only when a change is made by a sp ] ``` -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\\\]*\. +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": [ @@ -283,7 +283,7 @@ CodeBuildProject: Environment: Type: LINUX_CONTAINER ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:2.0 + Image: aws/codebuild/standard:4.0 Source: Type: GITHUB Location: source-location diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index b01d1b9..90cd4dc 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -18,43 +18,43 @@ You can create an AWS CodeBuild build project with more than one input source an ``` { - "name": "sample-project", - "source": { - "type": "S3", - "location": "bucket/sample.zip" + "name": "sample-project", + "source": { + "type": "S3", + "location": "bucket/sample.zip" + }, + "secondarySources": [ + { + "type": "CODECOMMIT", + "location": "https://git-codecommit.us-west-2.amazonaws.com/v1/repos/repo" + "sourceIdentifier": "source1" }, - "secondarySources": [ - { - "type": "CODECOMMIT", - "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" - "sourceIdentifier": "source2" - } - ], - "secondaryArtifacts": [ - { - "type": "S3", - "location": "output-bucket", - "artifactIdentifier": "artifact1" - }, - { - "type": "S3", - "location": "other-output-bucket", - "artifactIdentifier": "artifact2" - } - ], - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", - "computeType": "BUILD_GENERAL1_SMALL" + { + "type": "GITHUB", + "location": "https://github.com/awslabs/aws-codebuild-jenkins-plugin" + "sourceIdentifier": "source2" + } + ], + "secondaryArtifacts": [ + { + "type": "S3", + "location": "output-bucket", + "artifactIdentifier": "artifact1" }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } + { + "type": "S3", + "location": "other-output-bucket", + "artifactIdentifier": "artifact2" + } + ], + "environment": { + "type": "LINUX_CONTAINER", + "image": "aws/codebuild/standard:4.0", + "computeType": "BUILD_GENERAL1_SMALL" + }, + "serviceRole": "arn:aws:iam::account-ID:role/role-name", + "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" + } ``` Your primary source is defined under the `source` attribute\. All other sources are called secondary sources and appear under `secondarySources`\. All secondary sources are installed in their own directory\. This directory is stored in the built\-in environment variable `CODEBUILD_SRC_DIR_sourceIdentifer`\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. @@ -127,7 +127,7 @@ artifacts: }, "environment": { "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", + "image": "aws/codebuild/standard:4.0", "computeType": "BUILD_GENERAL1_SMALL", }, "serviceRole": "arn:aws:iam::account-ID:role/role-name", diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index a35186c..e46aebb 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -114,7 +114,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains + 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 **Start build**\. @@ -183,7 +183,7 @@ 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. For **Build specifications**, choose **Insert build commands**, and then choose **Switch to editor**\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index be7fe4a..e457e42 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -106,7 +106,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re - enter commands to run your tests reports: - report-name-or-arn: #test file information + report-name-or-arn: #test file information files: - 'test-result-files' base-directory: 'optional-base-directory' @@ -120,25 +120,26 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re 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\. ``` - {create-project-with-report - "name": "test-report-project", - "description": "sample-test-report-project", - "source": { - "type": "your-repository-type", - "location": "https://github.com/your-repository/your-folder" - }, - "artifacts": { - "type": "NO_ARTIFACTS" - }, - "cache": { - "type": "NO_CACHE" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:2.0", - "computeType": "small" - }, "serviceRole": "arn:aws:iam::your-aws-account-id:role/service-role/your-role-name" - } + { + "name": "test-report-project", + "description": "sample-test-report-project", + "source": { + "type": "your-repository-type", + "location": "https://github.com/your-repository/your-folder" + }, + "artifacts": { + "type": "NO_ARTIFACTS" + }, + "cache": { + "type": "NO_CACHE" + }, + "environment": { + "type": "LINUX_CONTAINER", + "image": "aws/codebuild/standard:4.0", + "computeType": "small" + }, + "serviceRole": "arn:aws:iam:your-aws-account-id:role/service-role/your-role-name" + } ``` 1. Run the following command in the directory that contains `project.json`\. This creates a project named `test-project`\. @@ -179,40 +180,40 @@ 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", - "created": 1573324770.154, - "exportConfig": { - "type": "S3", - "s3": { - "bucket": "your-s3-bucket", - "path": "path-to-your-report-results", - "packaging": "NONE", - "encryptionKey": "encryption-key" - } - }, - "expired": 1575916770.0, - "truncated": false, - "executionId": "arn:aws:codebuild:us-west-2:123456789012:build/name-of-build-project:2c254862-ddf6-4831-a53f-6839a73829c1", - "type": "TEST", - "arn": "report-arn", - "testSummary": { - "durationInNanoSeconds": 6657770, - "total": 11, - "statusCounts": { - "FAILED": 3, - "SKIPPED": 7, - "ERROR": 0, - "SUCCEEDED": 1, - "UNKNOWN": 0 - } - } + "reports": [ + { + "status": "FAILED", + "reportGroupArn": "report-group-arn", + "name": "report-group-name", + "created": 1573324770.154, + "exportConfig": { + "type": "S3", + "s3": { + "bucket": "your-s3-bucket", + "path": "path-to-your-report-results", + "packaging": "NONE", + "encryptionKey": "encryption-key" + } + }, + "expired": 1575916770.0, + "truncated": false, + "executionId": "arn:aws:codebuild:us-west-2:123456789012:build/name-of-build-project:2c254862-ddf6-4831-a53f-6839a73829c1", + "type": "TEST", + "arn": "report-arn", + "testSummary": { + "durationInNanoSeconds": 6657770, + "total": 11, + "statusCounts": { + "FAILED": 3, + "SKIPPED": 7, + "ERROR": 0, + "SUCCEEDED": 1, + "UNKNOWN": 0 } - ], - "reportsNotFound": [] + } + } + ], + "reportsNotFound": [] } ``` @@ -229,27 +230,27 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re ``` { - "testCases": [ - { - "status": "FAILED", - "name": "Test case 1", - "expired": 1575916770.0, - "reportArn": "report-arn", - "prefix": "Cucumber tests for agent", - "message": "A test message", - "durationInNanoSeconds": 1540540, - "testRawDataPath": "path-to-output-report-files" - }, - { - "status": "SUCCEEDED", - "name": "Test case 2", - "expired": 1575916770.0, - "reportArn": "report-arn", - "prefix": "Cucumber tests for agent", - "message": "A test message", - "durationInNanoSeconds": 1540540, - "testRawDataPath": "path-to-output-report-files" - } - ] + "testCases": [ + { + "status": "FAILED", + "name": "Test case 1", + "expired": 1575916770.0, + "reportArn": "report-arn", + "prefix": "Cucumber tests for agent", + "message": "A test message", + "durationInNanoSeconds": 1540540, + "testRawDataPath": "path-to-output-report-files" + }, + { + "status": "SUCCEEDED", + "name": "Test case 2", + "expired": 1575916770.0, + "reportArn": "report-arn", + "prefix": "Cucumber tests for agent", + "message": "A test message", + "durationInNanoSeconds": 1540540, + "testRawDataPath": "path-to-output-report-files" + } + ] } ``` \ No newline at end of file diff --git a/doc_source/test-framework-reporting.md b/doc_source/test-framework-reporting.md new file mode 100644 index 0000000..c674de3 --- /dev/null +++ b/doc_source/test-framework-reporting.md @@ -0,0 +1,9 @@ +# Test reporting with test frameworks + +The topics in this section demonstrate how to set up test reporting in AWS CodeBuild for various test frameworks\. + +**Topics** ++ [Set up test reporting with Jasmine](test-report-jasmine.md) ++ [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) \ 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 68878e5..6c384c8 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -27,7 +27,7 @@ + **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\.\) - 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-group-naming.md b/doc_source/test-report-group-naming.md index 3a0aef2..d25d1ea 100644 --- a/doc_source/test-report-group-naming.md +++ b/doc_source/test-report-group-naming.md @@ -11,4 +11,4 @@ If you use the ARN of the report group named `my-report-group` in both projects, and then run builds of each project, you still have one report group \(`my-report-group`\)\. That report group contains test reports with results of tests run by both build projects\. - If you a choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. \ No newline at end of file + If you choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. \ No newline at end of file diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md index 05c7dac..1e2e856 100644 --- a/doc_source/test-report-group.md +++ b/doc_source/test-report-group.md @@ -1,8 +1,8 @@ # Working with report groups -A *report group* contains test reports and specifies shared settings\. You use the buildspec file to specify the test cases to run and the commands to run them when it builds\. For each report group configured in a build project, a run of the build project creates a test report\. Multiple runs of a build project configured with a report group create multiple test reports in that report group, each with results of the the same test cases specified for that report group\. +A *report group* contains test reports and specifies shared settings\. You use the buildspec file to specify the test cases to run and the commands to run them when it builds\. For each report group configured in a build project, a run of the build project creates a test report\. Multiple runs of a build project configured with a report group create multiple test reports in that report group, each with results of the same test cases specified for that report group\. - The test cases are specified for a report group in the buildspec file of a build project\. You can specify up to 5 report groups in one build project\. When your run a build, all the test cases run\. A new test report is created with the results of each test case specified for a report group\. Each time you run a new build, the test cases run and a new test report is created with the new test results\. + The test cases are specified for a report group in the buildspec file of a build project\. You can specify up to five report groups in one build project\. When you run a build, all the test cases run\. A new test report is created with the results of each test case specified for a report group\. Each time you run a new build, the test cases run and a new test report is created with the new test results\. Report groups can be used in more than one build project\. All test reports created with one report group share the same configuration, such as its export option and permissions, even if the test reports are created using different build projects\. Test reports created with one report group in multiple build projects can contain the results from running different sets of test cases \(one set of test cases for each build project\)\. This is because you can specify different test case files for the report group in each project's buildspec file\. You can also change the test case files for a report group in a build project by editing its buildspec file\. Subsequent build runs create new test reports that contain the results of the test case files in the updated buildspec\. @@ -12,5 +12,5 @@ A *report group* contains test reports and specifies shared settings\. You use t + [Specify test files](report-group-test-cases.md) + [Specify test commands](report-group-test-case-commands.md) + [Report group naming](test-report-group-naming.md) -+ [Tagging Report Groups in AWS CodeBuild](how-to-tag-report-group.md) ++ [Tagging report groups in AWS CodeBuild](how-to-tag-report-group.md) + [Working with shared report groups](report-groups-sharing.md) \ No newline at end of file diff --git a/doc_source/test-report-jasmine.md b/doc_source/test-report-jasmine.md new file mode 100644 index 0000000..dfbd92a --- /dev/null +++ b/doc_source/test-report-jasmine.md @@ -0,0 +1,91 @@ +# Set up test reporting with Jasmine + +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\. ++ 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\. + +``` +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\. + +``` +{ + "scripts": { + "test": "npx jasmine" + } +} +``` + +AWS CodeBuild supports the following Jasmine test reporters: + +JUnitXmlReporter +Used to generate reports in the `JunitXml` format\. + +NUnitXmlReporter +Used to generate reports in the `NunitXml` format\. + +A Node\.js project with Jasmine will, by default, have a `spec` sub\-directory, which contains the Jasmine configuration and test scripts\. + +To configure Jasmine to generate reports in the `JunitXML` format, instantiate the `JUnitXmlReporter` reporter by adding the following code to your tests\. + +``` +var reporters = require('jasmine-reporters'); + +var junitReporter = new reporters.JUnitXmlReporter({ + savePath: , + filePrefix: , + consolidateAll: true +}); + +jasmine.getEnv().addReporter(junitReporter); +``` + +To configure Jasmine to generate reports in the `NunitXML` format, instantiate the `NUnitXmlReporter` reporter by adding the following code to your tests\. + +``` +var reporters = require('jasmine-reporters'); + +var nunitReporter = new reporters.NUnitXmlReporter({ + savePath: , + filePrefix: , + consolidateAll: true +}); + +jasmine.getEnv().addReporter(nunitReporter) +``` + +The test reports are exported to the file specified by **/**\. + +In your `buildspec.yml` file, add/update the following sections\. + +``` +version: 0.2 + +phases: + pre_build: + commands: + - npm install + build: + commands: + - npm build + - npm test + +reports: + jasmine_reports: + files: + - + 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 +``` \ No newline at end of file diff --git a/doc_source/test-report-jest.md b/doc_source/test-report-jest.md new file mode 100644 index 0000000..36e6e1e --- /dev/null +++ b/doc_source/test-report-jest.md @@ -0,0 +1,59 @@ +# Set up test reporting with Jest + +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\. ++ 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\. + +``` +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\. + +``` +{ + "scripts": { + "test": "jest" + } +} +``` + +Configure Jest to use the `JunitXml` reporter by adding the following to your Jest configuration file\. If your project does not have a Jest configuration file, create a file named `jest.config.js` in the root of your project and add the following\. The test reports are exported to the file specified by **/**\. + +``` +module.exports = { + reporters: [ + 'default', + [ 'jest-junit', { + outputDirectory: , + outputName: , + } ] + ] +}; +``` + +In your `buildspec.yml` file, add/update the following sections\. + +``` +version: 0.2 + +phases: + pre_build: + commands: + - npm install + build: + commands: + - npm build + - npm test + +reports: + jest_reports: + files: + - + 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 new file mode 100644 index 0000000..b4e6a4b --- /dev/null +++ b/doc_source/test-report-pytest.md @@ -0,0 +1,36 @@ +# Set up test reporting with pytest + +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\. ++ 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\. + +``` + - python -m pytest --junitxml=/ +``` + +In your `buildspec.yml` file, add/update the following sections\. + +``` +version: 0.2 + +phases: + install: + runtime-versions: + python: 3.7 + commands: + - pip3 install pytest + build: + commands: + - python -m pytest --junitxml=/ + +reports: + pytest_reports: + files: + - + base-directory: + 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 new file mode 100644 index 0000000..86afeb9 --- /dev/null +++ b/doc_source/test-report-rspec.md @@ -0,0 +1,31 @@ +# Set up test reporting with RSpec + +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\. ++ 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\. + +``` +version: 0.2 + +phases: + install: + runtime-versions: + ruby: 2.6 + pre_build: + commands: + - gem install rspec + - gem install rspec_junit_formatter + build: + commands: + - rspec /* --format RspecJunitFormatter --out / +reports: + rspec_reports: + files: + - + base-directory: + file-format: JunitXml +``` \ No newline at end of file diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index 00118ae..cd9e27c 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -16,4 +16,5 @@ The CodeBuild service role specified in the project is used for permissions to u + [Working with report groups](test-report-group.md) + [Working with reports](test-report.md) + [Working with test report permissions](test-permissions.md) -+ [View test reports](test-view-reports.md) \ No newline at end of file ++ [View test reports](test-view-reports.md) ++ [Test reporting with test frameworks](test-framework-reporting.md) \ 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 47e07c8..7cc52f7 100644 --- a/doc_source/update-report-group-cli.md +++ b/doc_source/update-report-group-cli.md @@ -28,10 +28,10 @@ } ``` -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 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\)\. + + 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: ``` diff --git a/doc_source/update-report-group-console.md b/doc_source/update-report-group-console.md index f89c282..6573ba7 100644 --- a/doc_source/update-report-group-console.md +++ b/doc_source/update-report-group-console.md @@ -4,7 +4,7 @@ 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 naviagation pane, choose **Report groups**\. +1. In the navigation pane, choose **Report groups**\. 1. Choose the report group you want to update\. From f121178049f9e6edd6709e90bc6561a4671df2f1 Mon Sep 17 00:00:00 2001 From: Joe Niland Date: Mon, 1 Jun 2020 10:02:09 +1000 Subject: [PATCH 038/156] Update sample-test-report-cli.md Correct example JSON for `CreateReportGroupInput.json` --- doc_source/sample-test-report-cli.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index e457e42..b0e106a 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -46,13 +46,14 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "name": "report-name", "type": "TEST", "exportConfig": { - "type": "S3", - "s3": { + "exportConfigType": "S3", + "s3Destination": { "bucket": "bucket-name", "path": "path-to-folder", "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`\)\. @@ -253,4 +254,4 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re } ] } - ``` \ No newline at end of file + ``` From ede43714958270d12c2f62da472d9ea73489bcc4 Mon Sep 17 00:00:00 2001 From: Atsushi Yamamoto Date: Wed, 3 Jun 2020 21:29:35 -0700 Subject: [PATCH 039/156] Add info about sh --- doc_source/build-env-ref-cmd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index 8fb0fa0..389a397 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.md @@ -7,10 +7,10 @@ You provide a set of commands for AWS CodeBuild to run in a build environment du + 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)\. -You can specify any Shell command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: +You can specify any Shell Command Language (sh) command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: + Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell\. For example, you could include a file named `my-script.sh` in your source code that contains commands such as `cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;`\. Then, in your buildspec file, specify the command `./my-script.sh`\. + In your buildspec file or on the **Build commands** setting for the `build` phase only, enter a single command that includes all of the commands you want to run in a single instance of the default shell \(for example, `cd MyDir && mkdir -p mySubDir && cd mySubDir && pwd`\)\. 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 2016 image use the Powershell shell\. From bd77dba5638f8e3593ce9d4450c4a728542979d2 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 4 Jun 2020 09:48:13 -0700 Subject: [PATCH 040/156] Correct deprecated images --- doc_source/build-env-ref-available.md | 4 ++-- doc_source/build-spec-ref.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 4f058e9..88cf0fa 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -9,9 +9,9 @@ AWS CodeBuild manages the following Docker images that are available in the Code | --- | --- | --- | | 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\-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:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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: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 | diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index a70b2d2..7387157 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -492,4 +492,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 From 0440757a96ba2e147e350f2f9ac7384179fdae79 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 8 Jun 2020 10:19:54 -0700 Subject: [PATCH 041/156] Correct report group syntax per https://github.com/awsdocs/aws-codebuild-user-guide/pull/64 --- doc_source/sample-test-report-cli.md | 58 +++++++++++----------- doc_source/test-report-group-create-cli.md | 6 +-- doc_source/update-report-group-cli.md | 6 +-- 3 files changed, 35 insertions(+), 35 deletions(-) diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index b0e106a..fcebcb0 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -43,16 +43,16 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re ``` { - "name": "report-name", - "type": "TEST", - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "bucket-name", - "path": "path-to-folder", - "packaging": "NONE" - } + "name": "report-name", + "type": "TEST", + "exportConfig": { + "exportConfigType": "S3", + "s3Destination": { + "bucket": "bucket-name", + "path": "path-to-folder", + "packaging": "NONE" } + } } ``` @@ -68,23 +68,23 @@ 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", - "type": "TEST", - "exportConfig": { - "type": "S3", - "s3": { - "bucket": "s3-bucket-name", - "path": "folder-path", - "packaging": "NONE", - "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" - } - }, - "created": 1570837165.885, - "lastModified": 1570837165.885 - } - } + "reportGroup": { + "arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/report-name", + "name": "report-name", + "type": "TEST", + "exportConfig": { + "exportConfigType": "S3", + "s3Destination": { + "bucket": "s3-bucket-name", + "path": "folder-path", + "packaging": "NONE", + "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" + } + }, + "created": 1570837165.885, + "lastModified": 1570837165.885 + } + } ``` ## Configure a project with a report group @@ -188,8 +188,8 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re "name": "report-group-name", "created": 1573324770.154, "exportConfig": { - "type": "S3", - "s3": { + "exportConfigType": "S3", + "s3Destination": { "bucket": "your-s3-bucket", "path": "path-to-your-report-results", "packaging": "NONE", @@ -254,4 +254,4 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re } ] } - ``` + ``` \ No newline at end of file diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index 6b5e76c..78e25f7 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -12,8 +12,8 @@ "name": "report-name", "type": "TEST", "exportConfig": { - "type": "S3", - "s3": { + "exportConfigType": "S3", + "s3Destination": { "bucket": "bucket-name", "path": "path", "packaging": "NONE | ZIP", @@ -37,7 +37,7 @@ "name": "report-name", "type": "TEST", "exportConfig": { - "type": "NO_EXPORT" + "exportConfigType": "NO_EXPORT" } } ``` diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md index 7cc52f7..ef42efb 100644 --- a/doc_source/update-report-group-cli.md +++ b/doc_source/update-report-group-cli.md @@ -10,8 +10,8 @@ { "arn": "", "exportConfig": { - "type": "S3", - "s3": { + "exportConfigType": "S3", + "s3Destination": { "bucket": "bucket-name", "path": "path", "packaging": "NONE | ZIP", @@ -37,7 +37,7 @@ ``` { "exportConfig": { - "type": "NO_EXPORT" + "exportConfigType": "NO_EXPORT" } } ``` From 16dc5b64260a394b651f666685958644e28902ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Bouteruche?= Date: Wed, 10 Jun 2020 21:10:43 +0200 Subject: [PATCH 042/156] Fix supported test file format Add Visual Studio TRX or TestNG XML as supported test file format. --- doc_source/test-reporting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index cd9e27c..fa69723 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -1,6 +1,6 @@ # Working with test reporting in AWS CodeBuild -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 test file format can be JUnit XML or Cucumber JSON\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. +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 test file format can be JUnit XML, Cucumber JSON, Visual Studio TRX or TestNG XML\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. @@ -17,4 +17,4 @@ 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) From 713504333038e91ac162b25358114e209eb98556 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 10 Jun 2020 15:21:43 -0700 Subject: [PATCH 043/156] General update. --- ...ntrol-iam-access-control-identity-based.md | 2 +- ...nd-access-control-permissions-reference.md | 193 ++++++++++++++---- doc_source/build-caching.md | 2 +- doc_source/build-env-ref-env-vars.md | 8 +- doc_source/build-spec-ref.md | 2 +- doc_source/codecov-integration.md | 2 +- doc_source/create-project.md | 14 +- doc_source/history.md | 2 +- doc_source/index.md | 2 +- doc_source/run-build.md | 18 +- doc_source/sample-access-tokens.md | 6 +- doc_source/sample-efs.md | 2 +- doc_source/sample-github-enterprise.md | 24 +-- doc_source/sample-github-pull-request.md | 12 +- doc_source/sample-multi-in-out.md | 2 +- doc_source/sample-source-version.md | 4 +- doc_source/sample-test-report-cli.md | 11 +- doc_source/samples.md | 2 +- doc_source/test-reporting.md | 13 +- doc_source/troubleshooting.md | 2 +- doc_source/use-case-based-samples.md | 2 +- 21 files changed, 231 insertions(+), 94 deletions(-) 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 847da99..1790e4f 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 @@ -22,7 +22,7 @@ In AWS CodeBuild, the primary resource is a build project\. In a policy, you use | --- | --- | | Build project | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | | Build | `arn:aws:codebuild:region-ID:account-ID:build/build-ID` | -| Report group | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | +| Report group | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-group\-name | | Report | arn:aws:codebuild:region\-ID:account\-ID:report/report\-ID | | All CodeBuild resources | `arn:aws:codebuild:*` | | All CodeBuild resources owned by the specified account in the specified AWS Region | `arn:aws:codebuild:region-ID:account-ID:*` | diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 14d7669..dfa3e14 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -12,41 +12,160 @@ 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 + +BatchDeleteBuilds +**Action:** `codebuild:BatchDeleteBuilds` +Required to delete builds\. +**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` + +BatchGetProjects +**Action:** `codebuild:BatchGetProjects` +Required to get information about build projects\. +**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` + +BatchGetReports +**Action:** `codebuild:BatchGetReports` +Required to get information about reports\. +**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` + +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` + +CreateReport ¹ +**Action:** `codebuild:CreateReport` +Required to create a test report\. +**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` + +CreateWebhook +**Action:** `codebuild:CreateWebhook` +Required to create a webhook\. +**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` + +DeleteReportGroup +**Action:** `codebuild:DeleteReportGroup` +Required to delete a report group\. +**Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name` + +DeleteSourceCredentials +**Action:** `codebuild:DeleteSourceCredentials` +Required to delete a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise Server, or Bitbucket repository\. +**Resource:** `*` + +DeleteWebhook +**Action:** `codebuild:DeleteWebhook` +Required to create a webhook\. +**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` + +ImportSourceCredentials +**Action:** `codebuild:ImportSourceCredentials` +Required to import a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise Server, or Bitbucket repository\. +**Resource:** `*` + +InvalidateProjectCache +**Action:** `codebuild:InvalidateProjectCache` +Required to reset the cache for a project\. +**Resource:** `arn:aws:codebuild:region-ID:account-ID:project/project-name` + +ListBuilds +**Action:** `codebuild:ListBuilds` +Required to get a list of build IDs\. +**Resource:** `*` + +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` + +ListCuratedEnvironmentImages +**Action:** `codebuild:ListCuratedEnvironmentImages` +Required to get information about all Docker images that are managed by AWS CodeBuild\. +**Resource:** `*` \(required, but does not refer to an addressable AWS resource\) + +ListProjects +**Action:** `codebuild:ListProjects` +Required to get a list of build project names\. +**Resource:** `*` + +ListReportGroups +**Action:** `codebuild:ListReportGroups` +Required to get a list of report groups\. +**Resource:** `*` + +ListReports +**Action:** `codebuild:ListReports` +Required to get a list of reports\. +**Resource:** `*` + +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` + +StartBuild +**Action:** `codebuild:StartBuild` +Required to start running builds\. +**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` + +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` + +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` + +UpdateReportGroup +**Action:** `codebuild:UpdateReportGroup` +Required to update a report group\. +**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` -Use the scroll bars to see the rest of the table\. - - -**CodeBuild API Operations and Required Permissions for Actions** - -| AWS CodeBuild API operations | Required permissions \(API actions\) | Resources | -| --- | --- | --- | -| BatchDeleteBuilds | `codebuild:BatchDeleteBuilds` Required to delete builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| BatchGetBuilds | `codebuild:BatchGetBuilds` Required to get information about builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| BatchGetProjects | `codebuild:BatchGetProjects` Required to get information about build projects\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| BatchGetReportGroups | codebuild:BatchGetReportGroupsRequired to get information about report groups\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| BatchGetReports | codebuild:BatchGetReportsRequired to get information about reports\. | `arn:aws:codebuild:region-ID:account-ID:report-group/report-name` | -| CreateProject | `codebuild:CreateProject` `iam:PassRole` Required to create build projects\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` `arn:aws:iam:account-ID:role/role-name` | -| CreateReportGroup | codebuild:CreateReportGroupRequired to create a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| CreateWebhook | `codebuild:CreateWebhook` Required to create a webhook\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| DeleteProject | `codebuild:DeleteProject` Required to delete build projects\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| DeleteReport | codebuild:DeleteReportRequired to delete a report\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| DeleteReportGroup | codebuild:DeleteReportGroupRequired to delete a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| DeleteSourceCredentials | `codebuild:DeleteSourceCredentials` Required to delete a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | -| DeleteWebhook | `codebuild:DeleteWebhook` Required to delete a webhook\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| DescribeTestCases | codebuild:DescribeTestCasesRequired to return a paginated list of test cases\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| ImportSourceCredentials | `codebuild:ImportSourceCredentials` Required to import a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | -| InvalidateProjectCache | `codebuild:InvalidateProjectCache` Required to reset the cache for a project\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| ListBuilds | codebuild:ListBuildsRequired to get a list of build IDs\. | `*` | -| ListBuildsForProject | `codebuild:ListBuildsForProject` Required to get a list of build IDs for a build project\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| ListCuratedEnvironmentImages | `codebuild:ListCuratedEnvironmentImages` Required to get information about all Docker images that are managed by CodeBuild\. | `*` \(required, but does not refer to an addressable AWS resource\) | -| ListProjects | `codebuild:ListProjects` Required to get a list of build project names\. | `*` | -| ListReportGroups | codebuild:ListReportGroupsRequired to get a list of report groups\. | \* | -| ListReports | codebuild:ListReportsRequired to get a list of reports\. | \* | -| ListReportsForReportGroup | codebuild:ListReportsForReportGroupRequired to get a list of reports for a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| ListSourceCredentials | `codebuild:ListSourceCredentials` Required to get a list of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise, or Bitbucket repository\. | `*` | -| StartBuild | `codebuild:StartBuild` Required to start running builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| StopBuild | `codebuild:StopBuild` Required to attempt to stop running builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| UpdateProject | `codebuild:UpdateProject` `iam:PassRole` Required to change information about builds\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` `arn:aws:iam:account-ID:role/role-name` | -| UpdateReportGroup | codebuild:UpdateReportGroupRequired to update a report group\. | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-name | -| UpdateWebhook | `codebuild:UpdateWebhook` Required to update a webhook\. | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | \ No newline at end of file +¹ Used for permission only\. There is no API for this action\. \ No newline at end of file diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 918eed5..39ac4e1 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -16,7 +16,7 @@ Docker layer cache mode is available for the Linux environment only\. If you cho ## 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, or Bitbucket\), the option is ignored\. ++ 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\. diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index afca63e..1df0a7d 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -12,16 +12,16 @@ AWS CodeBuild provides several environment variables that you can use in your bu + `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, and Bitbucket, it is the commit ID\. For these repositories, `CODEBUILD_RESOLVED_SOURCE_VERSION` is only available after the `DOWNLOAD_SOURCE` phase\. + + 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, and Bitbucket it is the commit ID, branch name, or tag 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 build that is triggered by a webhook pull request event, it is `pr/pull-request-number`\. +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)\. @@ -31,7 +31,7 @@ If you use a secondary source, the environment variable for its directory path i + `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, or Bitbucket\. The value's format depends on what type of event triggered the build\. ++ `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`\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 7387157..3eeec77 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -101,7 +101,7 @@ reports: - location base-directory: location discard-paths: yes - file-format: JunitXml | CucumberJson | VisualStudioTrx | TestNGXml + file-format: JunitXml | NunitXml | CucumberJson | VisualStudioTrx | TestNGXml artifacts: files: - location diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index 56802a5..d2c612b 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -1,6 +1,6 @@ # Use AWS CodeBuild with Codecov -Codecov is a tool that measures the test coverage of your code\. Codecov identifies which methods and statements in your code are not tested\. Use the results to determine where to write tests to improve the quality of your code\. Codecov is available for three of the source repositories supported by CodeBuild: GitHub, GitHub Enterprise, and Bitbucket\. If your build project uses GitHub Enterprise, you must use Codecov Enterprise\. +Codecov is a tool that measures the test coverage of your code\. Codecov identifies which methods and statements in your code are not tested\. Use the results to determine where to write tests to improve the quality of your code\. Codecov is available for three of the source repositories supported by CodeBuild: GitHub, GitHub Enterprise Server, and Bitbucket\. If your build project uses GitHub Enterprise Server, you must use Codecov Enterprise\. When you run a build of a CodeBuild project that is integrated with Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov Supported Languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 8052b10..bad8b54 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -356,15 +356,15 @@ For information about using the AWS CLI with CodeBuild, see the [Command line re 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, 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 account\. To do this, use the CodeBuild console to create a build project\. + + 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\. + 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 in GitHub Enterprise](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) on the GitHub Help website\. + 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 account\. + 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\.\) @@ -372,9 +372,9 @@ For information about using the AWS CLI with CodeBuild, see the [Command line re + *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, or Bitbucket, an `invalidInputException` is thrown\. - + *gitSubmodulesConfig*: Optional\. Information about the Git submodules configuration\. Used with CodeCommit, GitHub, GitHub Enterprise, 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 only\. Set this value to `true` to ignore TLS warnings while connecting to your GitHub Enterprise project repository\. The default value is `false`\. *InsecureSsl* should be used for testing purposes only\. It should not be used in a production environment\. + + *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\. + + *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\. diff --git a/doc_source/history.md b/doc_source/history.md index 8d42088..c4fd191 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -55,7 +55,7 @@ The following table describes important changes in each release of the *AWS Code | 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 support | CodeBuild can now build from source code stored in a GitHub Enterprise repository\. For more information, see [GitHub Enterprise sample](sample-github-enterprise.md)\. | January, 25, 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 | diff --git a/doc_source/index.md b/doc_source/index.md index 03f6e80..faf6563 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -58,7 +58,7 @@ Amazon's trademarks and trade dress may not be used in + [Create a test report in CodeBuild using the AWS CLI sample](sample-test-report-cli.md) + [Docker in custom image sample for CodeBuild](sample-docker-custom-image.md) + [Docker sample for CodeBuild](sample-docker.md) - + [GitHub Enterprise sample for CodeBuild](sample-github-enterprise.md) + + [GitHub Enterprise Server sample for CodeBuild](sample-github-enterprise.md) + [GitHub pull request and webhook filter sample for CodeBuild](sample-github-pull-request.md) + [Create a static website with build output hosted in an S3 bucket](sample-disable-artifact-encryption.md) + [Runtime versions in buildspec file sample for CodeBuild](sample-runtime-versions.md) diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 4eb18c0..26b2095 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -22,7 +22,7 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll 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 you 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, 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 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.md#create-project-source-provider)\. @@ -189,10 +189,10 @@ For more information about using the AWS CLI with CodeBuild, see the [Command li + *gitCloneDepthOverride*: Optional\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. + *imageOverride*: Optional\. The name of an image for this build that overrides the one specified in the build project\. + *idempotencyToken*: Optional\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 5 minutes after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. - + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project\. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise\. + + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project\. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise Server\. + *privilegedModeOverride*: Optional boolean\. If set to true, the build overrides privileged mode in the build project\. + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out\. Its minimum value is five minutes and its maximum value is 480 minutes \(eight hours\)\. - + *reportBuildStatusOverride*: Optional boolean that 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, or Bitbucket, an invalidInputException is thrown\. + + *reportBuildStatusOverride*: Optional boolean that 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\. + *sourceAuthOverride*: Optional string\. An authorization type for this build that overrides the one defined in the build project\. This override applies only if the build project's source is Bitbucket or GitHub\. + *sourceLocationOverride*: Optional string\. A location that overrides for this build the source location for the one defined in the build project\. + *serviceRoleOverride*: Optional string\. The name of a service role for this build that overrides the one specified in the build project\. @@ -222,7 +222,7 @@ To work with detailed information about this build, make a note of the `id` valu ## Start running builds automatically \(AWS CLI\) -If your source code is stored in a GitHub or a GitHub Enterprise repository, you can use GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. +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: @@ -242,19 +242,19 @@ For GitHub, information similar to the following appears in the output: ``` + where *url* is the URL to the GitHub webhook\. -For GitHub Enterprise, information similar to the following appears in the output: +For GitHub Enterprise Server, information similar to the following appears in the output: ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) -1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise\. +1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise Server\. -1. In GitHub Enterprise, choose the repository where your CodeBuild project is stored\. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. +1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored\. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. 1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. ## Stop running builds automatically \(AWS CLI\) -If your source code is stored in a GitHub or a GitHub Enterprise repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start running builds automatically \(AWS CLI\)](#run-build-cli-auto-start)\. +If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start running builds automatically \(AWS CLI\)](#run-build-cli-auto-start)\. If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: @@ -266,7 +266,7 @@ aws codebuild delete-webhook --project-name If this command is successful, no information and no errors appear in the output\. **Note** -This deletes the webhook from your CodeBuild project only\. You should also delete the webhook from your GitHub or GitHub Enterprise repository\. +This deletes the webhook from your CodeBuild project only\. You should also delete the webhook from your GitHub or GitHub Enterprise Server repository\. ## Run a build \(AWS SDKs\) diff --git a/doc_source/sample-access-tokens.md b/doc_source/sample-access-tokens.md index a414638..51ef6d4 100644 --- a/doc_source/sample-access-tokens.md +++ b/doc_source/sample-access-tokens.md @@ -1,6 +1,6 @@ # 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, you use a personal access token\. For Bitbucket, you use an app password\. + 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 @@ -74,9 +74,9 @@ Follow these steps to use the AWS CLI to connect your project to GitHub or Bitbu 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, 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\. + + *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, this is the personal access token\. For Bitbucket, this is the app password\. + + *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\. diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index c23e5ac..4873fa1 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -2,7 +2,7 @@ You might want to create your AWS CodeBuild builds on Amazon Elastic File System, a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What Is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) in the *Amazon Elastic File System User Guide*\. - This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repository\. + This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket repository\. Data in transit for your file system is encrypted\. To encrypt data in transit using a different image, see [Encrypting Data in Transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)\. diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index f175564..172458b 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -1,15 +1,15 @@ -# GitHub Enterprise sample for CodeBuild +# GitHub Enterprise Server sample for CodeBuild -AWS CodeBuild supports GitHub Enterprise as a source repository\. This sample shows how to set up your CodeBuild projects when your GitHub Enterprise repository has a certificate installed\. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise repository\. +AWS CodeBuild supports GitHub Enterprise Server as a source repository\. This sample shows how to set up your CodeBuild projects when your GitHub Enterprise Server repository has a certificate installed\. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise Server repository\. ## Prerequisites -1. Generate a personal access token for your CodeBuild project\. We recommend that you create a GitHub Enterprise user and generate a personal access token for this user\. Copy it to your clipboard so that it can be used when you create your CodeBuild project\. For more information, see [Creating a Personal Access Token in GitHub Enterprise](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) on the GitHub Help website\. +1. Generate a personal access token for your CodeBuild project\. We recommend that you create a GitHub Enterprise user and generate a personal access token for this user\. Copy it to your clipboard so that it can be used 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\. When you create the personal access token, include the **repo** scope in the definition\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png) -1. Download your certificate from GitHub Enterprise\. CodeBuild uses the certificate to make a trusted SSL connection to the repository\. +1. Download your certificate from GitHub Enterprise Server\. CodeBuild uses the certificate to make a trusted SSL connection to the repository\. **Linux/macOS clients:** @@ -22,7 +22,7 @@ AWS CodeBuild supports GitHub Enterprise as a source repository\. This sample sh Replace the placeholders in the command with the following values: - *HOST*\. The IP address of your GitHub Enterprise repository\. + *HOST*\. The IP address of your GitHub Enterprise Server repository\. *PORTNUMBER*\. The port number you are using to connect \(for example, 443\)\. @@ -34,7 +34,7 @@ Save the certificate as a \.pem file\. **Windows clients:** - Use your browser to download your certificate from GitHub Enterprise\. To see the site's certificate details, choose the padlock icon\. For information about how to export the certificate, see your browser documentation\. + Use your browser to download your certificate from GitHub Enterprise Server\. To see the site's certificate details, choose the padlock icon\. For information about how to export the certificate, see your browser documentation\. **Important** Save the certificate as a \.pem file\. @@ -42,7 +42,7 @@ Save the certificate as a \.pem file\. **Note** This bucket must be in the same AWS region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, the bucket must be in the US East \(Ohio\) Region\. -## Create a build project with GitHub Enterprise as the source repository and enable webhooks \(console\) +## Create a build project with GitHub Enterprise Server as the source repository and enable webhooks \(console\) 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -51,13 +51,13 @@ This bucket must be in the same AWS region as your builds\. For example, if you 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 **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 repository\. + + 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\. **Note** You only need to enter and save the personal access token once\. All future AWS CodeBuild projects use this token\. + In **Repository URL**, enter the path to your repository, including the name of the repository\. + Expand **Additional configuration**\. + Select **Rebuild every time a code change is pushed to this repository** to rebuild every time a code change is pushed to this repository\. - + Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise project repository\. + + Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise Server project repository\. **Note** We recommend that you use **Enable insecure SSL** for testing only\. It should not be used in a production environment\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) @@ -114,10 +114,10 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro 1. If you enabled webhooks in **Source**, a **Create webhook** dialog box is displayed with values for **Payload URL** and **Secret**\. **Important** -The **Create webhook** dialog box appears only once\. Copy the payload URL and secret key\. You need them when you add a webhook in GitHub Enterprise\. -If you need to generate a payload URL and secret key again, you must first delete the webhook from your GitHub Enterprise repository\. In your CodeBuild project, clear the **Webhook** check box and then choose **Save**\. You can then create or update a CodeBuild project with the **Webhook** check box selected\. The **Create webhook** dialog box appears again\. +The **Create webhook** dialog box appears only once\. Copy the payload URL and secret key\. You need them when you add a webhook in GitHub Enterprise Server\. +If you need to generate a payload URL and secret key again, you must first delete the webhook from your GitHub Enterprise Server repository\. In your CodeBuild project, clear the **Webhook** check box and then choose **Save**\. You can then create or update a CodeBuild project with the **Webhook** check box selected\. The **Create webhook** dialog box appears again\. -1. In GitHub Enterprise, choose the repository where your CodeBuild project is stored\. +1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored\. 1. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 4af9836..e9f3e16 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -82,13 +82,13 @@ When you use the console to create or update a build project, you can create a C + 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 only\. + 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 account ID matches the regular expression pattern\. This value is found in the `id` property of the `sender` object in the webhook payload\. + + `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 push events\. It cannot be used with GitHub Enterprise 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 push events\. It cannot be used with GitHub Enterprise pull request events\. + + `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\. @@ -132,7 +132,7 @@ In this example, a webhook filter group triggers a build only when files with na ![\[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 user with an account ID that matches the regular expression `actor-account-id`\. +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\. @@ -228,7 +228,7 @@ You can create a filter that triggers a build only when files with names that ma ] ``` -You can create a filter that triggers a build only when a change is made by a specified GitHub or GitHub Enterprise user with account ID `actor-account-id`\. +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\. diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index 90cd4dc..455d322 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -6,7 +6,7 @@ You can create an AWS CodeBuild build project with more than one input source an In this sample, you create a build project and use it to run a build\. The sample uses the build project's buildspec file to show you how to incorporate more than one source and create more than one set of artifacts\. -1. Upload your sources to one or more S3 buckets, CodeCommit, GitHub, GitHub Enterprise, or Bitbucket repositories\. +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\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index e79fc76..ed66719 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -2,7 +2,7 @@ This sample demonstrates how to specify a version of your source using a format other than a commit ID \(also known as a commit SHA\)\. You can specify the version of your source in the following ways: + For an Amazon S3 source provider, use the version ID of the object that represents the build input ZIP file\. -+ For CodeCommit, Bitbucket, GitHub, and GitHub Enterprise, use one of the following: ++ For CodeCommit, Bitbucket, GitHub, and GitHub Enterprise Server, use one of the following: + Pull request as a pull request reference \(for example, `refs/pull/1/head`\)\. + Branch as a branch name\. + Commit ID\. @@ -13,7 +13,7 @@ + A pull request \(for example, `refs/pull/1/head^{full-commit-SHA}`\)\. **Note** - You can specify the version of a pull request source only if your repository is GitHub or GitHub Enterprise\. + You can specify the version of a pull request source only if your repository is GitHub or GitHub Enterprise Server\. 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\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index fcebcb0..3d7bf8c 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -11,7 +11,16 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re + [Run and view results of a report](#sample-test-report-cli-run-and-view-report-results) ## Prerequisites -+ 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 format of your test cases can be JUnit XML, Cucumber JSON, Visual Studio TRX, or TestNG XML\. Create your test cases with any test framework that can create test files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. ++ 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 + + 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*\. + Create an IAM role and make a note of its ARN\. You need the ARN when you create your build project\. + If your role does not have the following permissions, add them\. diff --git a/doc_source/samples.md b/doc_source/samples.md index 95bf6a0..0b6de01 100644 --- a/doc_source/samples.md +++ b/doc_source/samples.md @@ -20,7 +20,7 @@ | [Create a test report in CodeBuild using the AWS CLI sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | | [Docker in custom image sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | | [Docker sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | -| [GitHub Enterprise sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | +| [GitHub Enterprise Server sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise Server as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | | [GitHub pull request and webhook filter sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | | [ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | | [Private registry with AWS Secrets Manager sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment\. The private registry credentials are stored in Secrets Manager\. | diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index fa69723..b3ab5ca 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -1,6 +1,15 @@ # Working with test reporting in AWS CodeBuild -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 test file format can be JUnit XML, Cucumber JSON, Visual Studio TRX or TestNG XML\. Create your test cases with any test framework that can create files in one of those formats \(for example, Surefire JUnit plugin, TestNG, and Cucumber\)\. +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 + +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\)\. To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. @@ -17,4 +26,4 @@ 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) ++ [Test reporting with test frameworks](test-framework-reporting.md) \ No newline at end of file diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index e234a64..8d94b98 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -310,7 +310,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo **Recommended solutions:** + Edit your project\. For **Certificate**, choose **Install certificate from S3**\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. For **Object key of certificate**, enter the name of your S3 object key\. -+ Edit your project\. Select **Insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise project repository\. ++ Edit your project\. Select **Insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise Server project repository\. **Note** We recommend that you use **Insecure SSL** for testing only\. It should not be used in a production environment\. diff --git a/doc_source/use-case-based-samples.md b/doc_source/use-case-based-samples.md index 2bf1f55..99debb9 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -21,7 +21,7 @@ You can use these use case\-based samples to experiment with AWS CodeBuild: | [Create a test report using the AWS CLI sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | | [Docker in custom image sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | | [Docker sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | -| [GitHub Enterprise sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | +| [GitHub Enterprise Server sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise Server as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | | [GitHub pull request and webhook filter sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | | [ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. | | [ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | From 2dbfdb447a561a363fff4087ab73d381dac61530 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 10 Jun 2020 16:52:42 -0700 Subject: [PATCH 044/156] Fix formatting --- ...nd-access-control-permissions-reference.md | 136 +++++++++--------- 1 file changed, 69 insertions(+), 67 deletions(-) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index dfa3e14..dce479b 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -12,160 +12,162 @@ 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` + **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` + **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` + **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` + **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` + **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` + **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` + **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` + **Resources:** ++ `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` ++ `arn:aws:iam:account-ID:role/ role-name ` CreateReport ¹ -**Action:** `codebuild: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` + **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` + **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 ` DeleteReport -**Action:** `codebuild:DeleteReport` -Required to delete a report\. -**Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name` + **Action:** `codebuild:DeleteReport` +Required to delete a report\. + **Resource:** `arn:aws:codebuild:region-ID: account-ID:report-group/ report-group-name ` DeleteReportGroup -**Action:** `codebuild: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` + **Action:** `codebuild:DeleteSourceCredentials` Required to delete a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise Server, or Bitbucket repository\. -**Resource:** `*` + **Resource:** `*` DeleteWebhook -**Action:** `codebuild: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` + **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` + **Action:** `codebuild:ImportSourceCredentials` Required to import a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise Server, or Bitbucket repository\. -**Resource:** `*` + **Resource:** `*` InvalidateProjectCache -**Action:** `codebuild: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 ` ListBuilds -**Action:** `codebuild:ListBuilds` + **Action:** `codebuild:ListBuilds` Required to get a list of build IDs\. -**Resource:** `*` + **Resource:** `*` ListBuildsForProject -**Action:** `codebuild: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` -Required to get information about all Docker images that are managed by AWS CodeBuild\. -**Resource:** `*` \(required, but does not refer to an addressable AWS resource\) + **Action:** `codebuild:ListCuratedEnvironmentImages` +Required to get information about all Docker images that are managed by AWS CodeBuild\. + **Resource:** `*` \(required, but does not refer to an addressable AWS resource\) ListProjects -**Action:** `codebuild:ListProjects` + **Action:** `codebuild:ListProjects` Required to get a list of build project names\. -**Resource:** `*` + **Resource:** `*` ListReportGroups -**Action:** `codebuild:ListReportGroups` + **Action:** `codebuild:ListReportGroups` Required to get a list of report groups\. -**Resource:** `*` + **Resource:** `*` ListReports -**Action:** `codebuild:ListReports` + **Action:** `codebuild:ListReports` Required to get a list of reports\. -**Resource:** `*` + **Resource:** `*` ListReportsForReportGroup -**Action:** `codebuild: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 ` StartBuild -**Action:** `codebuild: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` + **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` + **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` + **Resources:** ++ `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` ++ `arn:aws:iam:account-ID:role/ role-name ` UpdateReport ¹ -**Action:** `codebuild: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` + **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` + **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 From 8baa93be804ebab9920041659e40135df7193ff2 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 12 Jun 2020 11:49:01 -0700 Subject: [PATCH 045/156] Update title casing --- doc_source/build-env-ref-env-vars.md | 2 +- doc_source/build-env-ref.md | 2 +- doc_source/build-spec-ref.md | 8 ++--- doc_source/cloudtrail.md | 12 +++---- doc_source/codebuild-compliance-validation.md | 8 ++--- .../codebuild-disaster-recovery-resiliency.md | 2 +- doc_source/codecov-integration.md | 2 +- doc_source/create-project.md | 4 +-- doc_source/data-protection.md | 6 ++-- doc_source/endpoint-specify.md | 6 ++-- .../getting-started-build-log-console.md | 2 +- doc_source/getting-started-cli-build-log.md | 2 +- ...etting-started-cli-create-build-project.md | 4 +-- doc_source/getting-started-cli.md | 2 +- ...ng-started-create-build-project-console.md | 6 ++-- doc_source/getting-started.md | 2 +- doc_source/history.md | 2 +- doc_source/how-to-create-pipeline.md | 34 +++++++++---------- doc_source/how-to-integrate-config.md | 6 ++-- doc_source/how-to-tag-project-add.md | 12 +++---- doc_source/how-to-tag-project-delete.md | 6 ++-- doc_source/how-to-tag-project-list.md | 8 ++--- doc_source/how-to-tag-project-update.md | 6 ++-- doc_source/how-to-tag-project.md | 12 +++---- doc_source/how-to-tag-report-group-list.md | 2 +- doc_source/how-to-tag-report-group.md | 2 +- doc_source/index.md | 12 +++---- doc_source/infrastructure-security.md | 2 +- doc_source/jenkins-plugin.md | 2 +- doc_source/monitoring-alarms.md | 2 +- doc_source/monitoring-builds.md | 2 +- doc_source/monitoring-metrics.md | 2 +- doc_source/project-sharing.md | 8 ++--- doc_source/report-groups-sharing.md | 8 ++--- doc_source/run-build.md | 4 +-- doc_source/sample-access-tokens.md | 2 +- doc_source/sample-bitbucket-pull-request.md | 2 +- doc_source/sample-build-notifications.md | 10 +++--- doc_source/sample-codedeploy.md | 14 ++++---- .../sample-disable-artifact-encryption.md | 4 +-- doc_source/sample-docker-custom-image.md | 2 +- doc_source/sample-docker.md | 6 ++-- doc_source/sample-ecr.md | 2 +- doc_source/sample-efs.md | 6 ++-- doc_source/sample-elastic-beanstalk.md | 12 +++---- doc_source/sample-github-enterprise.md | 2 +- doc_source/sample-lambda.md | 4 +-- .../sample-pipeline-multi-input-output.md | 4 +-- doc_source/sample-private-registry.md | 6 ++-- doc_source/sample-runtime-versions.md | 2 +- doc_source/sample-test-report-cli.md | 2 +- doc_source/sample-windows.md | 2 +- doc_source/sdk-ref.md | 4 +-- doc_source/security-encryption.md | 6 ++-- doc_source/security-key-management.md | 2 +- doc_source/security-traffic-privacy.md | 2 +- doc_source/security.md | 2 +- .../test-report-group-create-console.md | 4 +-- doc_source/troubleshooting.md | 14 ++++---- doc_source/update-report-group-console.md | 4 +-- doc_source/use-proxy-server.md | 10 +++--- .../use-vpc-endpoints-with-codebuild.md | 8 ++--- doc_source/vpc-support.md | 4 +-- doc_source/welcome.md | 2 +- doc_source/working-with-build-projects.md | 2 +- 65 files changed, 174 insertions(+), 174 deletions(-) diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 1df0a7d..5525e31 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -48,4 +48,4 @@ To list all of the available environment variables in a build environment, you c **Important** We strongly discourage the use of environment variables to store sensitive values, especially AWS access key IDs and secret access keys\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. -We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your buildspec\. To store sensitive values, 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)\. \ No newline at end of file +We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your buildspec\. To store sensitive values, 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*\. To retrieve them, see the `parameter-store` mapping in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. \ No newline at end of file diff --git a/doc_source/build-env-ref.md b/doc_source/build-env-ref.md index 6e63cbe..51956dd 100644 --- a/doc_source/build-env-ref.md +++ b/doc_source/build-env-ref.md @@ -6,7 +6,7 @@ A build environment contains a Docker image\. For information, see [the Docker g When you provide information to CodeBuild about the build environment, you specify the identifier of a Docker image in a supported repository type\. These include the CodeBuild Docker image repository, publicly available images in Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\) repositories that your AWS account has permissions to access\. + We recommend that you use Docker images stored in the CodeBuild Docker image repository, because they are optimized for use with the service\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. -+ To get the identifier of a publicly available Docker image stored in Docker Hub, see [Searching for Images](https://docs.docker.com/docker-hub/repos/#searching-for-images) on the Docker Docs website\. ++ To get the identifier of a publicly available Docker image stored in Docker Hub, see [Searching for Repositories](https://docs.docker.com/docker-hub/repos/#searching-for-repositories) on the Docker Docs website\. + To learn how to work with Docker images stored in Amazon ECR repositories in your AWS account, see [Amazon ECR sample](sample-ecr.md)\. In addition to a Docker image identifier, you also specify a set of computing resources that the build environment uses\. For more information, see [Build environment compute types](build-env-ref-compute-types.md)\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 3eeec77..825e44d 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -21,7 +21,7 @@ You can specify only one buildspec for a build project, regardless of the builds To override the default buildspec file name, location, or both, do one of the following: + Run the AWS CLI `create-project` or `update-project` command, setting the `buildspec` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `create project` operation in the AWS SDKs\. For more information, see [Create a build project](create-project.md) or [Change a build project's settings](change-project.md)\. + Run the AWS CLI `start-build` command, setting the `buildspecOverride` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `start build` operation in the AWS SDKs\. For more information, see [Run a build](run-build.md)\. -+ In an AWS CloudFormation template, set the `BuildSpec` property of `Source` in a resource of type `AWS::CodeBuild::Project` to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. For more information, see the BuildSpec property in [AWS CodeBuild Project Source](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html) in the *AWS CloudFormation User Guide*\. ++ In an AWS CloudFormation template, set the `BuildSpec` property of `Source` in a resource of type `AWS::CodeBuild::Project` to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. For more information, see the BuildSpec property in [AWS CodeBuild project source](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html) in the *AWS CloudFormation User Guide*\. ## Buildspec syntax @@ -149,7 +149,7 @@ If an environment variable with the same name is defined in multiple places, the 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 buildspec declaration takes lowest precedence\. - + `parameter-store`: Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. + + `parameter-store`: Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. **Important** To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add the `ssm:GetParameters` action to your CodeBuild service role\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Store 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 retrieve 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 retrieve 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`\. @@ -166,7 +166,7 @@ The value in the buildspec declaration takes lowest precedence\. + `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*\. + 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*\. + `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\. @@ -243,7 +243,7 @@ Commands in some build phases might not be run if commands in earlier build phas + 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.md#create-project-console)\. - 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/)\. + 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\. diff --git a/doc_source/cloudtrail.md b/doc_source/cloudtrail.md index 2866004..838eb4e 100644 --- a/doc_source/cloudtrail.md +++ b/doc_source/cloudtrail.md @@ -6,13 +6,13 @@ To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs ## AWS CodeBuild information in CloudTrail -CloudTrail is enabled on your AWS account when you create the account\. When activity occurs in CodeBuild, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**\. You can view, search, and download recent events in your AWS account\. For more information, see [Viewing Events with CloudTrail Event History](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*\. +CloudTrail is enabled on your AWS account when you create the account\. When activity occurs in CodeBuild, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**\. You can view, search, and download recent events in your AWS account\. For more information, see [Viewing events with CloudTrail event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*\. For an ongoing record of events in your AWS account, including events for CodeBuild, create a trail\. A trail enables CloudTrail to deliver log files to an S3 bucket\. By default, when you create a trail in the console, the trail applies to all regions\. The trail logs events from all regions in the AWS partition and delivers the log files to the S3 bucket that you specify\. You can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs\. For more information, see: -+ [Overview for Creating a Trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) -+ [CloudTrail Supported Services and Integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) -+ [Configuring Amazon SNS Notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html) -+ [Receiving CloudTrail Log Files from Multiple Regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail Log Files from Multiple Accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) ++ [Overview for creating a trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) ++ [CloudTrail supported services and integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) ++ [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html) ++ [Receiving CloudTrail log files from multiple regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) All CodeBuild actions are logged by CloudTrail and are documented in the [CodeBuild API Reference](https://docs.aws.amazon.com/codebuild/latest/APIReference/)\. For example, calls to the `CreateProject` \(in the AWS CLI, `create-project`\), `StartBuild` \(in the AWS CLI, `start-project`\), and `UpdateProject` \(in the AWS CLI, `update-project`\) actions generate entries in the CloudTrail log files\. @@ -21,7 +21,7 @@ Every event or log entry contains information about who generated the request\. + Whether the request was made with temporary security credentials for a role or federated user\. + Whether the request was made by another AWS service\. -For more information, see the [CloudTrail userIdentity Element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)in the *AWS CloudTrail User Guide*\. +For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)in the *AWS CloudTrail User Guide*\. ## Understanding AWS CodeBuild log file entries diff --git a/doc_source/codebuild-compliance-validation.md b/doc_source/codebuild-compliance-validation.md index 020e52f..b5a01f1 100644 --- a/doc_source/codebuild-compliance-validation.md +++ b/doc_source/codebuild-compliance-validation.md @@ -2,13 +2,13 @@ Third\-party auditors assess the security and compliance of AWS CodeBuild as part of multiple AWS compliance programs\. These include SOC, PCI, FedRAMP, HIPAA, and others\. -For a list of AWS services in scope of specific compliance programs, see [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/)\. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/)\. +For a list of AWS services in scope of specific compliance programs, see [AWS services in scope by compliance program](https://aws.amazon.com/compliance/services-in-scope/)\. For general information, see [AWS compliance programs](https://aws.amazon.com/compliance/programs/)\. -You can download third\-party audit reports using AWS Artifact\. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)\. +You can download third\-party audit reports using AWS Artifact\. For more information, see [Downloading reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)\. Your compliance responsibility when using CodeBuild is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations\. If your use of CodeBuild is subject to compliance with standards such as HIPAA, PCI, or FedRAMP, AWS provides resources to help: -+ [Security and Compliance Quick Start Guides](https://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – These deployment guides discuss architectural considerations and provide steps for deploying security\- and compliance\-focused baseline environments on AWS\. ++ [Security and compliance quick start guides](https://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – These deployment guides discuss architectural considerations and provide steps for deploying security\- and compliance\-focused baseline environments on AWS\. + [Architecting for HIPAA Security and Compliance Whitepaper ](https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf) – This whitepaper describes how companies can use AWS to create HIPAA\-compliant applications\. -+ [AWS Compliance Resources](https://aws.amazon.com/compliance/resources/) – This collection of workbooks and guides might apply to your industry and location\. ++ [AWS compliance resources](https://aws.amazon.com/compliance/resources/) – This collection of workbooks and guides might apply to your industry and location\. + [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) – This AWS service assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations\. + [AWS Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) – This AWS service provides a comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices\. \ No newline at end of file diff --git a/doc_source/codebuild-disaster-recovery-resiliency.md b/doc_source/codebuild-disaster-recovery-resiliency.md index abe4be9..267921f 100644 --- a/doc_source/codebuild-disaster-recovery-resiliency.md +++ b/doc_source/codebuild-disaster-recovery-resiliency.md @@ -2,4 +2,4 @@ The AWS global infrastructure is built around AWS Regions and Availability Zones\. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low\-latency, high\-throughput, and highly redundant networking\. With Availability Zones, you can design and operate applications and databases that automatically fail over between Availability Zones without interruption\. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures\. -For more information about AWS Regions and Availability Zones, see [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/)\. \ No newline at end of file +For more information about AWS Regions and Availability Zones, see [AWS global infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/)\. \ No newline at end of file diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index d2c612b..de4e9f1 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -2,7 +2,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identifies which methods and statements in your code are not tested\. Use the results to determine where to write tests to improve the quality of your code\. Codecov is available for three of the source repositories supported by CodeBuild: GitHub, GitHub Enterprise Server, and Bitbucket\. If your build project uses GitHub Enterprise Server, you must use Codecov Enterprise\. - When you run a build of a CodeBuild project that is integrated with Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov Supported Languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. + When you run a build of a CodeBuild project that is integrated with Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov supported languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. ## Integrate Codecov into a build project diff --git a/doc_source/create-project.md b/doc_source/create-project.md index bad8b54..8a0cf45 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -416,7 +416,7 @@ For information about using the AWS CLI with CodeBuild, see the [Command line re **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*\. + + *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`\. @@ -465,7 +465,7 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro + *location*: Required\. The location specified in the format *EFS\-DNS\-name*:/*directory\-path*\. + *mountPoint*: Required\. The name of a directory in your build container that mounts the file system\. 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*\. + + *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`, and `WINDOWS_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)\. diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 950407b..6d58469 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -12,11 +12,11 @@ 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\. 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*\. ++ 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)\. -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*\. +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*\. **Topics** + [Data encryption](security-encryption.md) diff --git a/doc_source/endpoint-specify.md b/doc_source/endpoint-specify.md index 4734bb3..38cdea4 100644 --- a/doc_source/endpoint-specify.md +++ b/doc_source/endpoint-specify.md @@ -1,13 +1,13 @@ # Specify the AWS CodeBuild endpoint - You can use the AWS Command Line Interface \(AWS CLI\) or one of the AWS SDKs to specify the endpoint used by AWS CodeBuild\. There is an endpoint for each region in which CodeBuild is available\. In addition to a regional endpoint, four regions also have a Federal Information Processing Standards \(FIPS\) endpoint\. For more information about FIPS endpoints, see [FIPS 140\-2 Overview](https://aws.amazon.com/compliance/fips/)\. + You can use the AWS Command Line Interface \(AWS CLI\) or one of the AWS SDKs to specify the endpoint used by AWS CodeBuild\. There is an endpoint for each region in which CodeBuild is available\. In addition to a regional endpoint, four regions also have a Federal Information Processing Standards \(FIPS\) endpoint\. For more information about FIPS endpoints, see [FIPS 140\-2 overview](https://aws.amazon.com/compliance/fips/)\. Specifying an endpoint is optional\. If you don't explicitly tell CodeBuild which endpoint to use, the service uses the endpoint associated with the region your AWS account uses\. CodeBuild never defaults to a FIPS endpoint\. If you want to use a FIPS endpoint, you must associate CodeBuild with it using one of the following methods\. **Note** You can use an alias or region name to specify an endpoint using an AWS SDK\. If you use the AWS CLI, then you must use the full endpoint name\. - For endpoints that can be used with CodeBuild, see [CodeBuild Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region)\. + For endpoints that can be used with CodeBuild, see [CodeBuild regions and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region)\. **Topics** + [Specify the AWS CodeBuild endpoint \(AWS CLI\)](#endpoint-specify-cli) @@ -40,7 +40,7 @@ AWSCodeBuild awsCodeBuild = AWSCodeBuildClientBuilder.standard(). For information about `AWSCodeBuildClientBuilder`, see [Class AWSCodeBuildClientBuilder](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/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/v1/developer-guide/credentials.html)\. Do not include `https://` at the begining of the endpoint\. diff --git a/doc_source/getting-started-build-log-console.md b/doc_source/getting-started-build-log-console.md index 78b399a..7f81e96 100644 --- a/doc_source/getting-started-build-log-console.md +++ b/doc_source/getting-started-build-log-console.md @@ -16,7 +16,7 @@ In this step, you view detailed information about your build in CloudWatch Logs\ 1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. -1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. +1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and pattern syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. ## Next step diff --git a/doc_source/getting-started-cli-build-log.md b/doc_source/getting-started-cli-build-log.md index fc5a2bc..6f8c691 100644 --- a/doc_source/getting-started-cli-build-log.md +++ b/doc_source/getting-started-cli-build-log.md @@ -16,7 +16,7 @@ In this step, you view detailed information about your build in CloudWatch Logs\ 1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. -1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and Pattern Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. +1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and pattern syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. These portions of a CloudWatch Logs log stream pertain to this tutorial\. diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 92bd3d1..b0fda7f 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -2,7 +2,7 @@ \(Previous step: [Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md)\) -In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. +In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker overview](https://docs.docker.com/get-started/overview/) on the Docker Docs website\. For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. @@ -104,7 +104,7 @@ Other available values in the original JSON\-formatted data, such as `descriptio **Note** After you run the create\-project command, an error message similar to the following might be output: **User: *user\-ARN* is not authorized to perform: codebuild:CreateProject**\. This is most likely because you configured the AWS CLI with the credentials of an IAM user who does not have sufficient permissions to use CodeBuild to create build projects\. To fix this, configure the AWS CLI with credentials belonging to one of the following IAM entities: -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 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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS managed \(predefined\) policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. ## Next step diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md index 11ceb46..c54b118 100644 --- a/doc_source/getting-started-cli.md +++ b/doc_source/getting-started-cli.md @@ -5,7 +5,7 @@ In this tutorial, you use AWS CodeBuild to build a collection of sample source c 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)\. **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)\. +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) diff --git a/doc_source/getting-started-create-build-project-console.md b/doc_source/getting-started-create-build-project-console.md index 82a7232..d348586 100644 --- a/doc_source/getting-started-create-build-project-console.md +++ b/doc_source/getting-started-create-build-project-console.md @@ -2,7 +2,7 @@ \(Previous step: [Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md)\) -In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker Overview](https://docs.docker.com/engine/docker-overview/) on the Docker Docs website\. +In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker overview](https://docs.docker.com/get-started/overview/) on the Docker Docs website\. For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. @@ -10,14 +10,14 @@ For this build environment, you instruct CodeBuild to use a Docker image that co 1. Sign in to the AWS Management Console and open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. -1. Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild Endpoints and Quotas](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. +1. Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. 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**, for **Project name**, enter a name for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across each AWS account\. If you use a different name, be sure to use it throughout this tutorial\. **Note** On the **Create build project** page, you might see an error message similar to the following: **You are not authorized to perform this operation\.**\. This is most likely because you signed in to the AWS Management Console as an IAM user who does not have permissions to create a build project\.\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: -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 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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS managed \(predefined\) policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. Both options include administrator permissions that allow you to create a build project so you can complete this tutorial\. We recommend that you always use the minimum permissions required to accomplish your task\. For more information, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index 97c30af..e87fe5c 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -5,7 +5,7 @@ In this tutorial, you use AWS CodeBuild to build a collection of sample source c 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)\. **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)\. +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) diff --git a/doc_source/history.md b/doc_source/history.md index c4fd191..d808f4d 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -16,7 +16,7 @@ The following table describes the important changes to the documentation since t | [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 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 | diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index e5299fa..e4dc183 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -23,9 +23,9 @@ The following table lists tasks and the methods available for performing them\. 1. Answer the questions in [Plan a build](planning.md)\. -1. If you are using an IAM user to access CodePipeline instead of an AWS root account or an administrator IAM user, attach the managed policy named `AWSCodePipelineFullAccess` to the user \(or to the IAM group to which the user belongs\)\. Using an AWS root account is not recommended\. This policy grants the user permission to create the pipeline in CodePipeline\. For more information, see [Attaching Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) in the *IAM User Guide*\. +1. If you are using an IAM user to access CodePipeline instead of an AWS root account or an administrator IAM user, attach the managed policy named `AWSCodePipelineFullAccess` to the user \(or to the IAM group to which the user belongs\)\. Using an AWS root account is not recommended\. This policy grants the user permission to create the pipeline in CodePipeline\. For more information, see [Attaching managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) in the *IAM User Guide*\. **Note** -The IAM entity that attaches the policy to the user \(or to the IAM group to which the user belongs\) must have permission in IAM to attach policies\. For more information, see [Delegating Permissions to Administer IAM Users, Groups, and Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_delegate-permissions.html) in the *IAM User Guide*\. +The IAM entity that attaches the policy to the user \(or to the IAM group to which the user belongs\) must have permission in IAM to attach policies\. For more information, see [Delegating permissions to administer IAM users, groups, and credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_delegate-permissions.html) in the *IAM User Guide*\. 1. Create a CodePipeline service role, if you do not already have one available in your AWS account\. CodePipeline uses this service role to interact with other AWS services, including AWS CodeBuild, on your behalf\. For example, to use the AWS CLI to create a CodePipeline service role, run the IAM `create-role` command: @@ -43,16 +43,16 @@ The IAM entity that attaches the policy to the user \(or to the IAM group to whi **Note** The IAM entity that creates this CodePipeline service role must have permission in IAM to create service roles\. -1. After you create a CodePipeline service role or identify an existing one, you must add the default CodePipeline service role policy to the service role as described in [Review the Default CodePipeline Service Role Policy](https://docs.aws.amazon.com/codepipeline/latest/userguide/iam-identity-based-access-control.html#how-to-custom-role) in the *AWS CodePipeline User Guide*, if it isn't already a part of the policy for the role\. +1. After you create a CodePipeline service role or identify an existing one, you must add the default CodePipeline service role policy to the service role as described in [Review the default CodePipeline service role policy](https://docs.aws.amazon.com/codepipeline/latest/userguide/iam-identity-based-access-control.html#how-to-custom-role) in the *AWS CodePipeline User Guide*, if it isn't already a part of the policy for the role\. **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)\. **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*\. +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\) @@ -65,8 +65,8 @@ To create a pipeline that only tests your source code: **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*\. + + 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: ``` @@ -163,13 +163,13 @@ You can also get the build output artifact by choosing the **Build artifacts** l 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*\. +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.md#create-project-cli)\. -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. 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: @@ -244,12 +244,12 @@ The build project must define build output artifact settings \(even though CodeP 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 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 `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*\. + 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: @@ -313,8 +313,8 @@ You can also get the build output artifact by choosing the **Build artifacts** l ## 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*\. + + 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: ``` @@ -453,8 +453,8 @@ You can also get the build output artifact by choosing the **Build artifacts** l ## 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*\. + + 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: ``` diff --git a/doc_source/how-to-integrate-config.md b/doc_source/how-to-integrate-config.md index 0d2fd24..1468894 100644 --- a/doc_source/how-to-integrate-config.md +++ b/doc_source/how-to-integrate-config.md @@ -1,6 +1,6 @@ # Use AWS Config with CodeBuild sample -AWS Config provides an inventory of your AWS resources and a history of configuration changes to these resources\. AWS Config now supports AWS CodeBuild as an AWS resource, which means the service can track your CodeBuild projects\. For more information about AWS Config, see [What Is AWS Config?](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) in the *AWS Config Developer Guide*\. +AWS Config provides an inventory of your AWS resources and a history of configuration changes to these resources\. AWS Config now supports AWS CodeBuild as an AWS resource, which means the service can track your CodeBuild projects\. For more information about AWS Config, see [What is AWS Config?](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) in the *AWS Config Developer Guide*\. You can see the following information about CodeBuild resources on the **Resource Inventory** page in the AWS Config console: + A timeline of your CodeBuild configuration changes\. @@ -21,7 +21,7 @@ The procedures in this topic show you how to set up AWS Config and look up and v Create your AWS CodeBuild project\. For instructions, see [Create a build project](create-project.md)\. ## Set up AWS Config -+ [Setting up AWS Config \(Console\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-console.html) ++ [Setting up AWS Config \(console\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-console.html) + [Setting up AWS Config \(AWS CLI\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-cli.html) **Note** @@ -44,7 +44,7 @@ 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*\. +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: diff --git a/doc_source/how-to-tag-project-add.md b/doc_source/how-to-tag-project-add.md index f739466..4a7ba68 100644 --- a/doc_source/how-to-tag-project-add.md +++ b/doc_source/how-to-tag-project-add.md @@ -1,17 +1,17 @@ -# Add a Tag to a Project +# Add a tag to a project Adding tags to a project can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a project\. Keep in mind that there are limits on the number of tags you can have on a project\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the project based on these tags\. You can use the CodeBuild console or the AWS CLI to add tags to a project\. **Important** Before you add a tag to a project, make sure to review any IAM policies that might use tags to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. -For more information about adding tags to a project when you create it, see [Add a Tag to a Project \(Console\)](#how-to-tag-project-add-console)\. +For more information about adding tags to a project when you create it, see [Add a tag to a project \(console\)](#how-to-tag-project-add-console)\. **Topics** -+ [Add a Tag to a Project \(Console\)](#how-to-tag-project-add-console) -+ [Add a Tag to a Project \(AWS CLI\)](#how-to-tag-project-add-cli) ++ [Add a tag to a project \(console\)](#how-to-tag-project-add-console) ++ [Add a tag to a project \(AWS CLI\)](#how-to-tag-project-add-cli) -## Add a Tag to a Project \(Console\) +## Add a tag to a project \(console\) You can use the CodeBuild console to add one or more tags to a CodeBuild project\. @@ -29,7 +29,7 @@ You can use the CodeBuild console to add one or more tags to a CodeBuild project 1. When you have finished adding tags, choose **Submit**\. -## Add a Tag to a Project \(AWS CLI\) +## Add a tag to a project \(AWS CLI\) To add a tag to a project when you create it, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. In `create-project.json`, add your tags\. diff --git a/doc_source/how-to-tag-project-delete.md b/doc_source/how-to-tag-project-delete.md index 21620e1..d6b8896 100644 --- a/doc_source/how-to-tag-project-delete.md +++ b/doc_source/how-to-tag-project-delete.md @@ -1,11 +1,11 @@ -# Remove a Tag from a Project +# Remove a tag from a project You can remove one or more tags associated with a project\. Removing a tag does not delete the tag from other AWS resources that are associated with that tag\. **Important** Removing tags for a project can impact access to that project\. Before you remove a tag from a project, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. -## Remove a Tag from a Project \(Console\) +## Remove a tag from a project \(console\) You can use the CodeBuild console to remove the association between a tag and a CodeBuild project\. @@ -21,7 +21,7 @@ You can use the CodeBuild console to remove the association between a tag and a 1. When you have finished removing tags, choose **Submit**\. -## Remove a Tag from a Project \(AWS CLI\) +## 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: diff --git a/doc_source/how-to-tag-project-list.md b/doc_source/how-to-tag-project-list.md index 139e0d3..118d73c 100644 --- a/doc_source/how-to-tag-project-list.md +++ b/doc_source/how-to-tag-project-list.md @@ -1,8 +1,8 @@ -# View Tags for a Project +# View tags for a project -Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. +Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. -## View Tags for a Project \(Console\) +## View tags for a project \(console\) You can use the CodeBuild console to view the tags associated with a CodeBuild project\. @@ -12,7 +12,7 @@ You can use the CodeBuild console to view the tags associated with a CodeBuild p 1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. -## View Tags for a Project \(AWS CLI\) +## View tags for a project \(AWS CLI\) To view tags for a build project, run the following command\. Use the name of your project for the `--names` parameter\. diff --git a/doc_source/how-to-tag-project-update.md b/doc_source/how-to-tag-project-update.md index 90d96b5..d822274 100644 --- a/doc_source/how-to-tag-project-update.md +++ b/doc_source/how-to-tag-project-update.md @@ -1,11 +1,11 @@ -# Edit Tags for a Project +# Edit tags for a project You can change the value for a tag associated with a project\. You can also change the name of the key, which is equivalent to removing the current tag and adding a different one with the new name and the same value as the other key\. Keep in mind that there are limits on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. **Important** Editing tags for a project can impact access to that project\. Before you edit the name \(key\) or value of a tag for a project, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. -## Edit a Tag for a Project \(Console\) +## Edit a tag for a project \(console\) You can use the CodeBuild console to edit the tags associated with a CodeBuild project\. @@ -23,6 +23,6 @@ You can use the CodeBuild console to edit the tags associated with a CodeBuild p 1. When you have finished editing tags, choose **Submit**\. -## Edit Tags for a Project \(AWS CLI\) +## 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 diff --git a/doc_source/how-to-tag-project.md b/doc_source/how-to-tag-project.md index 2a9c514..fc9344e 100644 --- a/doc_source/how-to-tag-project.md +++ b/doc_source/how-to-tag-project.md @@ -1,4 +1,4 @@ -# Tagging Projects in AWS CodeBuild +# Tagging projects in AWS CodeBuild A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Each AWS tag has two parts: + A *tag key* \(for example, `CostCenter`, `Environment`, `Project`, or `Secret`\)\. Tag keys are case sensitive\. @@ -6,12 +6,12 @@ A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Together these are known as key\-value pairs\. For information about the number of tags you can have on a project and restrictions on tag keys and values, see [Tags](limits.md#tag-limits)\. -Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild project that you assign to an S3 bucket\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. +Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild project that you assign to an S3 bucket\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. In CodeBuild, the primary resources are the project and the report group\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a project\. In addition to identifying, organizing, and tracking your project with tags, you can use tags in IAM policies to help control who can view and interact with your project\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. **Topics** -+ [Add a Tag to a Project](how-to-tag-project-add.md) -+ [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) \ No newline at end of file ++ [Add a tag to a project](how-to-tag-project-add.md) ++ [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) \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-list.md b/doc_source/how-to-tag-report-group-list.md index 4073459..124ffbe 100644 --- a/doc_source/how-to-tag-report-group-list.md +++ b/doc_source/how-to-tag-report-group-list.md @@ -1,6 +1,6 @@ # View tags for a report group -Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. +Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. ## View tags for a report group \(console\) diff --git a/doc_source/how-to-tag-report-group.md b/doc_source/how-to-tag-report-group.md index 6af41f8..d41d1c7 100644 --- a/doc_source/how-to-tag-report-group.md +++ b/doc_source/how-to-tag-report-group.md @@ -6,7 +6,7 @@ A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Together these are known as key\-value pairs\. For limits on the number of tags you can have on a report group and restrictions on tag keys and values, see [Tags](limits.md#tag-limits)\. -Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild report group that you assign to an Amazon S3 bucket\. For more information about using tags, see the [Tagging Best Practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. +Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild report group that you assign to an Amazon S3 bucket\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. In CodeBuild, the primary resources are the report group and the project\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a report group\. In addition to identifying, organizing, and tracking your report group with tags, you can use tags in IAM policies to help control who can view and interact with your report group\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. diff --git a/doc_source/index.md b/doc_source/index.md index faf6563..d4bb893 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,4 +1,4 @@ -# AWS CodeBuild User guide +# AWS CodeBuild User Guide ----- *****Copyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** @@ -95,11 +95,11 @@ Amazon's trademarks and trade dress may not be used in + [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) - + [Add a Tag to a Project](how-to-tag-project-add.md) - + [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) + + [Tagging projects in AWS CodeBuild](how-to-tag-project.md) + + [Add a tag to a project](how-to-tag-project-add.md) + + [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) + [Working with builds in AWS CodeBuild](builds-working.md) + [Run a build in AWS CodeBuild](run-build.md) + [View build details in AWS CodeBuild](view-build-details.md) diff --git a/doc_source/infrastructure-security.md b/doc_source/infrastructure-security.md index 78e1e61..45786b0 100644 --- a/doc_source/infrastructure-security.md +++ b/doc_source/infrastructure-security.md @@ -1,6 +1,6 @@ # Infrastructure security in AWS CodeBuild -As a managed service, AWS CodeBuild is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of Security Processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper\. +As a managed service, AWS CodeBuild is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of security processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper\. You use AWS published API calls to access CodeBuild through the network\. Clients must support Transport Layer Security \(TLS\) 1\.0 or later\. We recommend TLS 1\.2 or later\. Clients must also support cipher suites with perfect forward secrecy \(PFS\) such as Ephemeral Diffie\-Hellman \(DHE\) or Elliptic Curve Ephemeral Diffie\-Hellman \(ECDHE\)\. Most modern systems such as Java 7 and later support these modes\. diff --git a/doc_source/jenkins-plugin.md b/doc_source/jenkins-plugin.md index 73b58aa..4e562e7 100644 --- a/doc_source/jenkins-plugin.md +++ b/doc_source/jenkins-plugin.md @@ -4,7 +4,7 @@ You can use the Jenkins plugin for AWS CodeBuild to integrate CodeBuild with you ## Setting up Jenkins -For information about setting up Jenkins with the AWS CodeBuild plugin, see the [ Simplify Your Jenkins Builds with CodeBuild](https://aws.amazon.com/blogs/devops/simplify-your-jenkins-builds-with-aws-codebuild/) blog post on the AWS DevOps Blog\. You can download the CodeBuild Jenkins plugin from [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. +For information about setting up Jenkins with the AWS CodeBuild plugin, see the [ Simplify your Jenkins builds with CodeBuild](https://aws.amazon.com/blogs/devops/simplify-your-jenkins-builds-with-aws-codebuild/) blog post on the AWS DevOps Blog\. You can download the CodeBuild Jenkins plugin from [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. ## Installing the plugin diff --git a/doc_source/monitoring-alarms.md b/doc_source/monitoring-alarms.md index 3a3a6c6..76e4348 100644 --- a/doc_source/monitoring-alarms.md +++ b/doc_source/monitoring-alarms.md @@ -18,7 +18,7 @@ 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 **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*\. +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/) diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index cd7c906..6a7a62b 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.md @@ -48,4 +48,4 @@ + `FailedBuild`\. You can create an alarm that is triggered when a certain number of failed builds are detected within a predetermined number of seconds\. In CloudWatch you specify the number of seconds and how many faild builds trigger an alarm\. + `Duration`\. You can create an alarm that is triggered when a build takes longer than expected\. You specify how many seconds must elapse after a build is started and before a build is completed before the alarm is triggered\. - For information about how to create alarms for CodeBuild metrics, see [Monitoring builds with CloudWatch alarms](monitoring-alarms.md)\. For more information about alarms, see [Creating Amazon CloudWatch Alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file + For information about how to create alarms for CodeBuild metrics, see [Monitoring builds with CloudWatch alarms](monitoring-alarms.md)\. For more information about alarms, see [Creating Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/monitoring-metrics.md b/doc_source/monitoring-metrics.md index 7496e8f..8f768c2 100644 --- a/doc_source/monitoring-metrics.md +++ b/doc_source/monitoring-metrics.md @@ -54,4 +54,4 @@ The graphs in the CodeBuild console show three days of metrics\. You cannot cust 1. Choose one or more project and metric combinations\. For each project, you can choose the **SucceededBuilds**, **FailedBuilds**, **Builds**, and **Duration** metrics\. All selected project and metric combinations are displayed in the graph on the page\. -1. \(Optional\) You can customize your metrics and graphs\. For example, from the drop\-down list in the **Statistic** columm, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. For more information, see [Graph Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [View Available Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file +1. \(Optional\) You can customize your metrics and graphs\. For example, from the drop\-down list in the **Statistic** columm, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. For more information, see [Graph metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [View available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index 0ea958a..6aaaaf3 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -48,7 +48,7 @@ You can add a project to an existing resource share or you can create one in the **Note** You cannot delete a project with builds that has been added to a resource share\. -To share a project with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. +To share a project with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. You can use the AWS CodeBuild console, AWS RAM console, or the AWS CLI to share a project that you own\. @@ -60,10 +60,10 @@ You can use the AWS CodeBuild console, AWS RAM console, or the AWS CLI to share **Note** By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. -1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. +1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a resource share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. **To share a project that you own \(AWS RAM console\)** -See [Creating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. +See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. **To share a project that you own \(AWS RAM command\)** Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. @@ -125,7 +125,7 @@ An unshared project, including its builds, can be accessed only by its owner\. I To unshare a shared project that you own, you must remove it from the resource share\. You can use the AWS CodeBuild console, AWS RAM console, or AWS CLI to do this\. **To unshare a shared project that you own \(AWS RAM console\)** -See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. +See [Updating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. **To unshare a shared project that you own \(AWS CLI\)** Use the [disassociate\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command\. diff --git a/doc_source/report-groups-sharing.md b/doc_source/report-groups-sharing.md index 870d818..78d7b32 100644 --- a/doc_source/report-groups-sharing.md +++ b/doc_source/report-groups-sharing.md @@ -48,7 +48,7 @@ For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ You can use the CodeBuild console to add a report group to an existing resource share\. If you want to add the report group to a new resource share, you must first create it in the [AWS RAM console](https://console.aws.amazon.com/ram)\. -To share a report group with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. +To share a report group with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. You can use the CodeBuild console, AWS RAM console, or AWS CLI to share report groups that you own\. @@ -58,10 +58,10 @@ You can use the CodeBuild console, AWS RAM console, or AWS CLI to share report g 1. In the navigation pane, choose **Report groups**\. -1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. +1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a resource share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. **To share report groups that you own \(AWS RAM console\)** -See [Creating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. +See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. **To share report groups that you own \(AWS RAM command\)** Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. @@ -126,7 +126,7 @@ An unshared report group, including its reports and their test case results, can To unshare a shared report group that you own, you must remove it from the resource share\. You can use the AWS RAM console or AWS CLI to do this\. **To unshare a shared report group that you own \(AWS RAM console\)** -See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. +See [Updating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. **To unshare a shared report group that you own \(AWS RAM command\)** Use the [disassociate\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command\. diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 26b2095..74018df 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -82,7 +82,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 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`\. **Important** -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 [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*\. +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`\. @@ -199,7 +199,7 @@ For more information about using the AWS CLI with CodeBuild, see the [Command li + *sourceTypeOverride*: Optional string\. A source input type for this build that overrides the source input defined in the build project\. Valid strings are `NO_SOURCE`, `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `S3`, `BITBUCKET`, and `GITHUB_ENTERPRISE`\. + *timeoutInMinutesOverride*: Optional number\. The number of build timeout minutes that overrides for this build the one defined in the build project\. **Important** -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\. CodeBuild can use a parameter stored in Amazon EC2 Systems Manager Parameter Store only if that parameter's name starts 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\. However, if you use the Amazon EC2 Systems Manager Parameter Store console to create a parameter, you must start the parameter's name with `/CodeBuild/`, and you must set **Type** to **Secure String**\. 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*\. +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\. CodeBuild can use a parameter stored in Amazon EC2 Systems Manager Parameter Store only if that parameter's name starts 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\. However, if you use the Amazon EC2 Systems Manager Parameter Store console to create a parameter, you must start the parameter's name with `/CodeBuild/`, and you must set **Type** to **Secure String**\. For more information, see [AWS Systems Manager parameter store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.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 new 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\. 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\. diff --git a/doc_source/sample-access-tokens.md b/doc_source/sample-access-tokens.md index 51ef6d4..2001b64 100644 --- a/doc_source/sample-access-tokens.md +++ b/doc_source/sample-access-tokens.md @@ -11,7 +11,7 @@ + **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 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\. diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 9918900..a1b5218 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -54,7 +54,7 @@ CodeBuild does not support Bitbucket Server\. 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. 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. On the Bitbucket webhooks page, choose **View request** to see a list of recent events\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 785f2fb..e891fed 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -3,7 +3,7 @@ Amazon CloudWatch Events has built\-in support for AWS CodeBuild\. CloudWatch Events is a stream of system events describing changes in your AWS resources\. With CloudWatch Events, you write declarative rules to associate events of interest with automated actions to be taken\. This sample uses Amazon CloudWatch Events and Amazon Simple Notification Service \(Amazon SNS\) to send build notifications to subscribers whenever builds succeed, fail, go from one build phase to another, or any combination of these events\. **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 CloudWatch and Amazon SNS\. For more information, see [CodeBuild Pricing](http://aws.amazon.com/codebuild/pricing), [Amazon CloudWatch Pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon SNS Pricing](http://aws.amazon.com/sns/pricing)\. +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 CloudWatch and Amazon SNS\. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon SNS pricing](http://aws.amazon.com/sns/pricing)\. ## Running the sample @@ -35,7 +35,7 @@ Running this sample might result in charges to your AWS account\. These include ``` **Note** The IAM entity that modifies this policy must have permission in IAM to modify policies\. -For more information, see [Editing Customer Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with Inline Policies \(Console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. +For more information, see [Editing customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with inline policies \(console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. 1. Create or identify a topic in Amazon SNS\. AWS CodeBuild uses CloudWatch Events to send build notifications to this topic through Amazon SNS\. @@ -52,7 +52,7 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a 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*\. + 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\. @@ -71,7 +71,7 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a 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\. - For more information, see [Subscribe to a Topic](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html) in the *Amazon SNS Developer Guide*\. + For more information, see [Subscribe to a topic](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html) in the *Amazon SNS Developer Guide*\. 1. If you are using an IAM user instead of an AWS root account or an administrator IAM user to work with CloudWatch Events, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\. This statement is used to allow the user to work with CloudWatch Events\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. @@ -95,7 +95,7 @@ For more information, see [Editing Customer Managed Policies](https://docs.aws.a ``` **Note** The IAM entity that modifies this policy must have permission in IAM to modify policies\. -For more information, see [Editing Customer Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with Inline Policies \(Console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. +For more information, see [Editing customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with inline policies \(console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. 1. Create a rule in CloudWatch Events\. To do this, open the CloudWatch console, at [https://console\.aws\.amazon\.com/cloudwatch](https://console.aws.amazon.com/cloudwatch)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 1de2d69..795a890 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -3,7 +3,7 @@ This sample instructs AWS CodeBuild to use Maven to produce as build output a single JAR file named `my-app-1.0-SNAPSHOT.jar`\. This sample then uses CodeDeploy to deploy the JAR file to an Amazon Linux instance\. You can also use AWS CodePipeline to automate the use of CodeDeploy to deploy the JAR file to an Amazon Linux instance\. This sample is based on the [Maven in 5 Minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html) topic on the Apache Maven website\. **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)\. +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)\. ## Running the sample @@ -150,17 +150,17 @@ Do not add `(root directory name)` or `(root directory name)/my-app` to the ZIP 1. If you plan to deploy the build output artifact with CodeDeploy, follow the steps in [Run a build](run-build.md)\. Otherwise, skip this step\. \(This is because if you plan to deploy the build output artifact with CodePipeline, CodePipeline uses CodeBuild to run the build automatically\.\) 1. Complete the setup steps for using CodeDeploy, including: - + Grant the IAM user access to CodeDeploy and the AWS services and actions CodeDeploy depends on\. For more information, see [Provision an IAM User](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-setup.html#getting-started-user) in the *AWS CodeDeploy User Guide*\. - + Create or identify a service role to enable CodeDeploy to identify the instances where it deploys the build output artifact\. For more information, see [Creating a Service Role for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) in the *AWS CodeDeploy User Guide*\. - + Create or identify an IAM instance profile to enable your instances to access the S3 input bucket or GitHub repository that contains the build output artifact\. For more information, see [Creating an IAM Instance Profile for Your Amazon EC2 Instances](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-iam-instance-profile.html) in the *AWS CodeDeploy User Guide*\. + + Grant the IAM user access to CodeDeploy and the AWS services and actions CodeDeploy depends on\. For more information, see [Provision an IAM user](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-setup.html#getting-started-user) in the *AWS CodeDeploy User Guide*\. + + Create or identify a service role to enable CodeDeploy to identify the instances where it deploys the build output artifact\. For more information, see [Creating a service role for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) in the *AWS CodeDeploy User Guide*\. + + Create or identify an IAM instance profile to enable your instances to access the S3 input bucket or GitHub repository that contains the build output artifact\. For more information, see [Creating an IAM instance profile for your Amazon EC2 instances](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-iam-instance-profile.html) in the *AWS CodeDeploy User Guide*\. -1. Create or identify an Amazon Linux instance compatible with CodeDeploy where the build output artifact is deployed\. For more information, see [Working with Instances for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-instances.html) in the *AWS CodeDeploy User Guide*\. +1. Create or identify an Amazon Linux instance compatible with CodeDeploy where the build output artifact is deployed\. For more information, see [Working with instances for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-instances.html) in the *AWS CodeDeploy User Guide*\. -1. Create or identify a CodeDeploy application and deployment group\. For more information, see [Creating an Application with CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-application.html) in the *AWS CodeDeploy User Guide*\. +1. Create or identify a CodeDeploy application and deployment group\. For more information, see [Creating an application with CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-application.html) in the *AWS CodeDeploy User Guide*\. 1. Deploy the build output artifact to the instance\. - 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 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)\. diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index 593d647..f2ba604 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -2,7 +2,7 @@ You can disable the encryption of artifacts in a build\. You might want to do this so that you can publish artifacts to a location that is configured to host a website\. \(You cannot publish encrypted artifacts\.\) This sample shows how you can use webhooks to trigger a build and publish its artifacts to an S3 bucket that is configured to be a website\. -1. Follow the instructions in [Setting Up a Static Website](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html) to configure an S3 bucket to function like a website\. +1. Follow the instructions in [Setting up a static website](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html) to configure an S3 bucket to function like a website\. 1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -46,4 +46,4 @@ When you use the console to create or update a build project, you can create a C 1. Choose **Create build project**\. On the build project page, in **Build history**, choose **Start build** to run the build\. -1. \(Optional\) Follow the instructions in [Example: Speed Up Your Website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-cloudfront-walkthrough.html) in the *Amazon S3 Developer Guide*\. \ No newline at end of file +1. \(Optional\) Follow the instructions in [Example: Speed up your website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-cloudfront-walkthrough.html) in the *Amazon S3 Developer Guide*\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index f2557d6..ac74700 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -5,7 +5,7 @@ This sample builds and runs a Docker image by using AWS CodeBuild and a custom D To learn how to build a Docker image by using a build image provided by CodeBuild with Docker support instead, see our [Docker sample](sample-docker.md)\. **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, 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)\. +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, 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)\. **Topics** + [Running the sample](#sample-docker-custom-image-running) diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 967f1c5..3884774 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -9,7 +9,7 @@ This sample was tested referencing `golang:1.12`\. This sample uses the new multi\-stage Docker builds feature, which produces a Docker image as build output\. It then pushes the Docker image to an Amazon ECR image repository\. Multi\-stage Docker image builds help to reduce the size of the final Docker image\. For more information, see [Use multi\-stage builds with Docker](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)\. **Important** -Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry Pricing](http://aws.amazon.com/ecr/pricing)\. +Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing)\. **Topics** + [Running the sample](#sample-docker-running) @@ -22,7 +22,7 @@ Running this sample might result in charges to your AWS account\. These include **To run this sample** -1. If you already have an image repository in Amazon ECR you want to use, skip to step 3\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon ECR, add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\.This statement allows the creation of Amazon ECR repositories for storing Docker images\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. For more information, see [Working with Inline Policies Using the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. +1. If you already have an image repository in Amazon ECR you want to use, skip to step 3\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon ECR, add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\.This statement allows the creation of Amazon ECR repositories for storing Docker images\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. For more information, see [Working with inline policies using the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. ``` { @@ -44,7 +44,7 @@ Running this sample might result in charges to your AWS account\. These include **Note** The IAM entity that modifies this policy must have permission in IAM to modify policies\. -1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS Region where you create your build environment and run your build\. For more information, see [Creating a Repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. +1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS Region where you create your build environment and run your build\. For more information, see [Creating a repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. 1. Add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the policy you attached to your AWS CodeBuild service role\. This statement allows CodeBuild to upload Docker images to Amazon ECR repositories\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 272dbce..eaad273 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -3,7 +3,7 @@ This sample uses a Docker image in an Amazon Elastic Container Registry \(Amazon ECR\) image repository to build a sample Go project\. **Important** -Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry Pricing](http://aws.amazon.com/ecr/pricing)\. +Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing)\. ## Running the sample diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 4873fa1..603748a 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -1,10 +1,10 @@ # Amazon Elastic File System sample for AWS CodeBuild - You might want to create your AWS CodeBuild builds on Amazon Elastic File System, a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What Is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) in the *Amazon Elastic File System User Guide*\. + You might want to create your AWS CodeBuild builds on Amazon Elastic File System, a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) in the *Amazon Elastic File System User Guide*\. This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket repository\. -Data in transit for your file system is encrypted\. To encrypt data in transit using a different image, see [Encrypting Data in Transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)\. +Data in transit for your file system is encrypted\. To encrypt data in transit using a different image, see [Encrypting data in transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)\. ## High\-level steps @@ -129,4 +129,4 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + 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*\. \ No newline at end of file diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index c647522..202fd71 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -3,7 +3,7 @@ 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\. **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)\. +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)\. ## Create the source code @@ -125,9 +125,9 @@ In this step, you use the AWS Elastic Beanstalk console to create an application Use the AWS Region selector to choose the AWS Region where your S3 output bucket is stored\. -1. Create an Elastic Beanstalk application\. For more information, see [Managing and Configuring AWS Elastic Beanstalk Applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. +1. Create an Elastic Beanstalk application\. For more information, see [Managing and configuring AWS Elastic Beanstalk applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. -1. Create an Elastic Beanstalk environment for this application\. For more information, see [The Create New Environment Wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Leave all settings at their default values, except for these settings\. +1. Create an Elastic Beanstalk environment for this application\. For more information, see [The create new environment wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Leave all settings at their default values, except for these settings\. + For **Platform**, choose **Tomcat**\. + For **Application code**, choose **Upload your code**, and then choose **Upload**\. For **Source code origin**, choose **Public S3 URL**, and then enter the full URL to the build output ZIP file in the output bucket\. Choose **Upload**\. @@ -208,9 +208,9 @@ In this step, you create an Elastic Beanstalk application and environment to use 1. Open the Elastic Beanstalk console at [https://console\.aws\.amazon\.com/elasticbeanstalk/](https://console.aws.amazon.com/elasticbeanstalk/)\. -1. Use the AWS Elastic Beanstalk console to create an application\. For more information, see [Managing and Configuring AWS Elastic Beanstalk Applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. +1. Use the AWS Elastic Beanstalk console to create an application\. For more information, see [Managing and configuring AWS Elastic Beanstalk applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. -1. Use the AWS Elastic Beanstalk console to create an environment\. For more information, see [The Create New Environment Wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Except for **Platform**, leave all settings at their default values\. For **Platform**, choose **Tomcat**\. +1. Use the AWS Elastic Beanstalk console to create an environment\. For more information, see [The create new environment wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Except for **Platform**, leave all settings at their default values\. For **Platform**, choose **Tomcat**\. ### Step b4: Create the pipeline and deploy @@ -288,7 +288,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi ### 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. 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\. diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 172458b..84abb3e 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -38,7 +38,7 @@ Save the certificate as a \.pem file\. **Important** Save the certificate as a \.pem file\. -1. Upload your certificate file to an S3 bucket\. For information about how to create an S3 bucket, see [How Do I Create an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) For information about how to upload objects to an S3 bucket, see [How Do I Upload Files and Folders to a Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html) +1. Upload your certificate file to an S3 bucket\. For information about how to create an S3 bucket, see [How do I create an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) For information about how to upload objects to an S3 bucket, see [How do I upload files and folders to a bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html) **Note** This bucket must be in the same AWS region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, the bucket must be in the US East \(Ohio\) Region\. diff --git a/doc_source/sample-lambda.md b/doc_source/sample-lambda.md index 5c780bb..36eb55c 100644 --- a/doc_source/sample-lambda.md +++ b/doc_source/sample-lambda.md @@ -1,10 +1,10 @@ # AWS Lambda sample for CodeBuild -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\. +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 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*\. ## 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/sample-pipeline-multi-input-output.md b/doc_source/sample-pipeline-multi-input-output.md index a940f6b..cfbab88 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 [AWS CodePipeline Pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*\. ``` { @@ -128,4 +128,4 @@ An AWS CodeBuild project can take more than one input source\. It can also creat - source2_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 + 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-private-registry.md b/doc_source/sample-private-registry.md index 5b292b3..e27aa47 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -23,7 +23,7 @@ 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. 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/) @@ -38,9 +38,9 @@ 1. When you review your settings, write down the ARN to use later in this sample\. - For more information, see [What Is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) + 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 *AWS Identity and Management 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 e46aebb..38d04ca 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -171,7 +171,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 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\. +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)\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 3d7bf8c..95ff6a1 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -21,7 +21,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re + Visual Studio 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*\. ++ 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*\. + Create an IAM role and make a note of its ARN\. You need the ARN when you create your build project\. + If your role does not have the following permissions, add them\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index 35808ae..eeb1941 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -3,7 +3,7 @@ These samples use an AWS CodeBuild build environment running Microsoft Windows Server 2016, the \.NET Framework, and the \.NET Core SDK to build executables file out of code written in C\#, 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)\. +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)\. ## Running the samples diff --git a/doc_source/sdk-ref.md b/doc_source/sdk-ref.md index fcbadee..17ffaa0 100644 --- a/doc_source/sdk-ref.md +++ b/doc_source/sdk-ref.md @@ -9,8 +9,8 @@ If you want to use the AWS CLI to run CodeBuild, see the [Command line reference The following AWS SDKs and tools support CodeBuild: + The [AWS SDK for C\+\+](https://aws.amazon.com/sdk-for-cpp)\. For more information, see the [Aws::CodeBuild](http://sdk.amazonaws.com/cpp/api/LATEST/namespace_aws_1_1_code_build.html) namespace section of the *AWS SDK for C\+\+ API Reference*\. + The [AWS SDK for Go](https://aws.amazon.com/sdk-for-go/)\. For more information, see the [codebuild](http://docs.aws.amazon.com/sdk-for-go/api/service/codebuild/) section of the *AWS SDK for Go API Reference*\. -+ The [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/)\. For more information, see the `com.amazonaws.services.codebuild` and `com.amazonaws.services.codebuild.model` sections of the [AWS SDK for Java API Reference](http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/index.html)\. -+ The [AWS SDK for JavaScript in the Browser](https://aws.amazon.com/sdk-for-browser/) and the [AWS SDK for JavaScript in Node\.js](https://aws.amazon.com/sdk-for-node-js/)\. For more information, see the [Class: AWS\.CodeBuild](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CodeBuild.html) section of the *AWS SDK for JavaScript API Reference*\. ++ The [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/)\. For more information, see the `com.amazonaws.services.codebuild` and `com.amazonaws.services.codebuild.model` sections of the [AWS SDK for Java API reference](http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/index.html)\. ++ The [AWS SDK for JavaScript in the browser](https://aws.amazon.com/sdk-for-browser/) and the [AWS SDK for JavaScript in Node\.js](https://aws.amazon.com/sdk-for-node-js/)\. For more information, see the [Class: AWS\.CodeBuild](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CodeBuild.html) section of the *AWS SDK for JavaScript API Reference*\. + The [AWS SDK for \.NET](https://aws.amazon.com/sdk-for-net/)\. For more information, see the [Amazon\.CodeBuild](http://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CodeBuild/NCodeBuild.html) and [Amazon\.CodeBuild\.Model](http://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CodeBuild/NCodeBuildModel.html) namespace sections of the *AWS SDK for \.NET API Reference*\. + The [AWS SDK for PHP](https://aws.amazon.com/sdk-for-php/)\. For more information, see the [Namespace Aws\\CodeBuild](http://docs.aws.amazon.com/aws-sdk-php/v3/api/namespace-Aws.CodeBuild.html) section of the *AWS SDK for PHP API Reference*\. + The [AWS SDK for Python \(Boto3\)](https://aws.amazon.com/sdk-for-python/)\. For more information, see the [CodeBuild](https://boto3.readthedocs.io/en/latest/reference/services/codebuild.html) section of the *Boto 3 Documentation*\. diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index db68b35..af5ab1f 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*\. ++ **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.md#encryptionkey-console) and [Set the Encryption Key Using the CLI](create-project.md#encryptionkey-cli)\. 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 KMS Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file ++ **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 diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index 225c9be..495e7da 100644 --- a/doc_source/security-key-management.md +++ b/doc_source/security-key-management.md @@ -1,6 +1,6 @@ # 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 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)\. 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)\. diff --git a/doc_source/security-traffic-privacy.md b/doc_source/security-traffic-privacy.md index 79e0a6e..01ba121 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 8edf32c..0e15889 100644 --- a/doc_source/security.md +++ b/doc_source/security.md @@ -2,7 +2,7 @@ Cloud security at AWS is the highest priority\. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security\-sensitive organizations\. -Security and compliance is a shared responsibility between AWS and you\. This shared model can help relieve your operational burden: AWS operates, manages, and controls the components from the host operating system and virtualization layer down to the physical security of the service facilities\. You assume responsibility and management of the guest operating system \(including updates and security patches\) and other associated application software\. You're also responsible for the configuration of the AWS provided security group firewall\. Your responsibilities vary with the services you use, the integration of those services into your IT environment, and applicable laws and regulations\. Therefore, you should carefully consider the services that your organization uses\. For more information, see [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/)\. +Security and compliance is a shared responsibility between AWS and you\. This shared model can help relieve your operational burden: AWS operates, manages, and controls the components from the host operating system and virtualization layer down to the physical security of the service facilities\. You assume responsibility and management of the guest operating system \(including updates and security patches\) and other associated application software\. You're also responsible for the configuration of the AWS provided security group firewall\. Your responsibilities vary with the services you use, the integration of those services into your IT environment, and applicable laws and regulations\. Therefore, you should carefully consider the services that your organization uses\. For more information, see [Shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/)\. To learn how to secure your CodeBuild resources, see the following topics\. diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index 6c384c8..85458cb 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -23,8 +23,8 @@ 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*\. + + **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\.\) For more information about encryption of data at rest, see [Data encryption](security-encryption.md)\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 8d94b98..1c22dce 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -209,7 +209,7 @@ pre_build: + The cache has recently been invalidated through the `InvalidateProjectCache` API\. + The service role being used by CodeBuild does not have `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. -**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. For more information, see [Specifying S3 Permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html) in the *Amazon S3 Developer Guide*\. +**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. For more information, see [Specifying S3 permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html) in the *Amazon S3 Developer Guide*\. ## Error: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image @@ -282,7 +282,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + The AWS CodeBuild service role associated with the build project does not exist or does not have sufficient permissions to trust CodeBuild\. **Recommended solutions:** -+ Make sure AWS STS is activated for the AWS region where you are attempting to create or update the build project\. For more information, see [Activating and Deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) in the *IAM User Guide*\. ++ Make sure AWS STS is activated for the AWS region where you are attempting to create or update the build project\. For more information, see [Activating and deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) in the *IAM User Guide*\. + Make sure the target CodeBuild service role exists in your AWS account\. If you are not using the console, make sure you did not misspell the Amazon Resource Name \(ARN\) of the service role when you created or updated the build project\. + Make sure the target CodeBuild service role has sufficient permissions to trust CodeBuild\. For more information, see the trust relationship policy statement in [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. @@ -381,11 +381,11 @@ artifacts: **Possible causes:** The IPv4 CIDR block specified for your VPC uses a reserved IP address\. The first four IP addresses and the last IP address in each subnet CIDR block are not available for you to use and cannot be assigned to an instance\. For example, in a subnet with CIDR block `10.0.0.0/24`, the following five IP addresses are reserved: + `10.0.0.0:` Network address\. + `10.0.0.1`: Reserved by AWS for the VPC router\. -+ `10.0.0.2`: Reserved by AWS\. The IP address of the DNS server is always the base of the VPC network range plus two; however, we also reserve the base of each subnet range plus two\. For VPCs with multiple CIDR blocks, the IP address of the DNS server is located in the primary CIDR\. For more information, see [Amazon DNS Server](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS) in the *Amazon VPC User Guide*\. ++ `10.0.0.2`: Reserved by AWS\. The IP address of the DNS server is always the base of the VPC network range plus two; however, we also reserve the base of each subnet range plus two\. For VPCs with multiple CIDR blocks, the IP address of the DNS server is located in the primary CIDR\. For more information, see [Amazon DNS server](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS) in the *Amazon VPC User Guide*\. + `10.0.0.3`: Reserved by AWS for future use\. + `10.0.0.255`: Network broadcast address\. We do not support broadcast in a VPC\. This address is reserved\. -**Recommended solutions:** Check if your VPC uses a reserved IP address\. Replace any reserved IP address with one that is not reserved\. For more information, see [VPC and Subnet Sizing](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#VPC_Sizing) in the *Amazon VPC User Guide*\. +**Recommended solutions:** Check if your VPC uses a reserved IP address\. Replace any reserved IP address with one that is not reserved\. For more information, see [VPC and subnet sizing](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#VPC_Sizing) in the *Amazon VPC User Guide*\. ## Error: "Unable to download cache: RequestError: Send request failed caused by: x509: Failed to load system roots and no roots provided" @@ -463,11 +463,11 @@ artifacts: + Make sure `ssl-bump` is configured properly\. If you use Squid for your proxy server, see [ Configure Squid as an explicit proxy server](use-proxy-server.md#use-proxy-server-explicit-squid-configure)\. + Follow these steps to use private endpoints for Amazon S3 and CloudWatch Logs: - 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. 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 \(AWS PrivateLink\)](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*\. + 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)\. ``` diff --git a/doc_source/update-report-group-console.md b/doc_source/update-report-group-console.md index 6573ba7..9fb9985 100644 --- a/doc_source/update-report-group-console.md +++ b/doc_source/update-report-group-console.md @@ -19,6 +19,6 @@ 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*\. + + **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 diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index 9c73d84..da4f2ae 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -36,15 +36,15 @@ There are two primary use cases for running CodeBuild in a proxy server: 1. Create two subnets in your VPC\. One is a public subnet named `Public Subnet` in which your proxy server runs\. The other is a private subnet named `Private Subnet` in which CodeBuild runs\. - For information, see [Creating a Subnet in Your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet)\. + For information, see [Creating a subnet in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet)\. -1. Create and attach an internet gateway to your VPC\. For more information, see [Creating and Attaching an Internet Gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. +1. Create and attach an internet gateway to your VPC\. For more information, see [Creating and attaching an internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. -1. Add a rule to the default route table that routes outgoing traffic from the VPC \(0\.0\.0\.0/0\) to the internet gateway\. For information, see [Adding and Removing Routes from a Route Table](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#AddRemoveRoutes)\. +1. Add a rule to the default route table that routes outgoing traffic from the VPC \(0\.0\.0\.0/0\) to the internet gateway\. For information, see [Adding and removing routes from a route table](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#AddRemoveRoutes)\. 1. Add a rule to the default security group of your VPC that allows ingress SSH traffic \(TCP 22\) from your VPC \(0\.0\.0\.0/0\)\. -1. Follow the instructions in [Launching an Instance Using the Launch Instance Wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) in the *Amazon EC2 User Guide* to launch an Amazon Linux instance\. When you run the wizard, choose the following options: +1. Follow the instructions in [Launching an instance using the launch instance wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) in the *Amazon EC2 User Guide* to launch an Amazon Linux instance\. When you run the wizard, choose the following options: + In **Choose an Instance Type**, choose an Amazon Linux Amazon Machine Image \(AMI\)\. + In **Subnet**, choose the public subnet you created earlier in this topic\. If you used the suggested name, it is **Public Subnet**\. + In **Auto\-assign Public IP**, choose **Enable**\. @@ -53,7 +53,7 @@ There are two primary use cases for running CodeBuild in a proxy server: Choose the default settings for all other options\. -1. After your EC2 instance is running, disable source/destination checks\. For information, see [Disabling Source/Destination Checks](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) in the *Amazon VPC User Guide*\. +1. After your EC2 instance is running, disable source/destination checks\. For information, see [Disabling Source/Destination checks](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) in the *Amazon VPC User Guide*\. 1. Create a route table in your VPC\. Add a rule to the route table that routes traffic destined for the internet to your proxy server\. Associate this route table with your private subnet\. This is required so that outbound requests from instances in your private subnet, where CodeBuild runs, are always routed through the proxy server\. diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index 70642b7..3411440 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 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*\. ## Before you create VPC endpoints @@ -8,12 +8,12 @@ **Note** Use a [NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html) if you want to use CodeBuild with AWS services that do not support Amazon VPC PrivateLink connections\. -+ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP Option Sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. ++ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP option sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. + VPC endpoints currently do not support cross\-Region requests\. Make sure that you create your endpoint in the same AWS Region as any S3 buckets that store your build input and output\. You can use the Amazon S3 console or the [get\-bucket\-location](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-bucket-location.html) command to find the location of your bucket\. Use a Region\-specific Amazon S3 endpoint to access your bucket \(for example, `mybucket.s3-us-west-2.amazonaws.com`\)\. For more information about Region\-specific endpoints for Amazon S3, see [Amazon Simple Storage Service](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the *Amazon Web Services General Reference*\. If you use the AWS CLI to make requests to Amazon S3, set your default Region to the same Region where your bucket was created, or use the `--region` parameter in your requests\. ## Creating VPC endpoints for CodeBuild -Follow the instructions in [Creating an Interface Endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. +Follow the instructions in [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) @@ -45,4 +45,4 @@ The following example policy specifies that all principals can only start and vi } ``` - For more information, see [Controlling Access to Services with VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html) in the *Amazon VPC User Guide*\. \ No newline at end of file + For more information, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html) in the *Amazon VPC User Guide*\. \ No newline at end of file diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index d4ba181..93a8c07 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -61,11 +61,11 @@ 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\. 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\. + Include multiple Availability Zones with your VPC\. -+ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security Groups Rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*\. ++ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security groups rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*\. + Set up separate subnets for your builds\. + When you set up your CodeBuild projects to access your VPC, choose private subnets only\. diff --git a/doc_source/welcome.md b/doc_source/welcome.md index e903bcb..552b8a1 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -33,7 +33,7 @@ The CodeBuild console also provides a way to quickly search for your resources, ## Pricing for CodeBuild -For information, see [CodeBuild Pricing](https://aws.amazon.com/codebuild/pricing)\. +For information, see [CodeBuild pricing](https://aws.amazon.com/codebuild/pricing)\. ## How do I get started with CodeBuild? diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index d180e6e..31a2c4f 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -15,4 +15,4 @@ You can perform these tasks when working with build projects: + [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) \ No newline at end of file From 146d4f8589c5529cfc14373d4bcceab3f3b37e49 Mon Sep 17 00:00:00 2001 From: Janice Huang <60631893+huanjani@users.noreply.github.com> Date: Sun, 14 Jun 2020 13:08:02 -0700 Subject: [PATCH 046/156] Update how-to-create-pipeline.md Fix: delete extra word; now matches wording in "Add a CodeBuild test action" below. --- doc_source/how-to-create-pipeline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index e4dc183..97e3106 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -363,7 +363,7 @@ This procedure shows you how to add a build stage between the **Source** and **B 1. Inside of the selected stage, choose **Add action**\. **Note** -This procedure shows you want 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\. +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\. @@ -572,4 +572,4 @@ To store and retrieve sensitive values, we recommend your build commands use the 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 +1. Scroll through the build log to view the test results\. From 27bea5c69eb8c757b9aefe0c81b10822cd44450a Mon Sep 17 00:00:00 2001 From: anibalsanchez Date: Tue, 16 Jun 2020 19:57:10 +0200 Subject: [PATCH 047/156] Sample policy for CodeBuildAccess, with both cases --- doc_source/sample-ecr.md | 50 +++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index eaad273..1b1ee60 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -2,7 +2,7 @@ This sample uses a Docker image in an Amazon Elastic Container Registry \(Amazon ECR\) image repository to build a sample Go project\. -**Important** +**Important** Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing)\. ## Running the sample @@ -11,11 +11,11 @@ Running this sample might result in charges to your AWS account\. These include 1. To create and push the Docker image to your image repository in Amazon ECR, complete the steps in the "Running the sample" section of the [Docker sample](sample-docker.md)\. -1. Create a Go project: +1. Create a Go project: - 1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. -**Important** -Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. + 1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. +**Important** +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 view related build information by following the steps in [Run AWS CodeBuild directly](how-to-run.md)\. @@ -47,11 +47,11 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. To get the build output artifact, open your S3 output bucket\. - 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file\. In the extracted contents, get the `hello` file\. + 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file\. In the extracted contents, get the `hello` file\. -1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment\. - + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`\. - + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`\. +1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment\. + + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`\. + + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`\. 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. @@ -64,7 +64,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. For **Effect**, leave **Allow** selected\. This indicates that you want to allow access to another AWS account\. 1. For **Principal**, do one of the following: - + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild\.amazonaws\.com**\. + + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild\.amazonaws\.com**\. + If your project uses a cross\-account Amazon ECR image, for **AWS account IDs**, enter IDs of the AWS accounts that you want to give access\. 1. Skip the **All IAM entities** list\. @@ -84,10 +84,22 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains "Version": "2012-10-17", "Statement": [ { - "Sid": "CodeBuildAccess", + "Sid": "CodeBuildAccessPrincipal", "Effect": "Allow", "Principal": { - "AWS": "arn:aws:iam::AWS-account-ID:root" + "Service": "codebuild.amazonaws.com" + }, + "Action": [ + "ecr:BatchCheckLayerAvailability", + "ecr:BatchGetImage", + "ecr:GetDownloadUrlForLayer" + ] + }, + { + "Sid": "CodeBuildAccessCrossaccount", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::AWS-account-ID:root" }, "Action": [ "ecr:GetDownloadUrlForLayer", @@ -99,7 +111,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)\. +2. Create a build project, run the build, and view 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\.\) @@ -126,9 +138,9 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains } ``` -1. To get the build output artifact, open your S3 output bucket\. +3. To get the build output artifact, open your S3 output bucket\. -1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file\. In the extracted contents, get the `hello` file\. +4. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file\. In the extracted contents, get the `hello` file\. ## Go project structure @@ -150,14 +162,14 @@ This sample uses these files\. version: 0.2 phases: - install: - runtime-versions: - golang: 1.13 + install: + runtime-versions: + golang: 1.13 build: commands: - echo Build started on `date` - echo Compiling the Go code... - - go build hello.go + - go build hello.go post_build: commands: - echo Build completed on `date` From b59f342a6160272219be76370fc9816c52ecae14 Mon Sep 17 00:00:00 2001 From: anibalsanchez Date: Tue, 16 Jun 2020 19:58:46 +0200 Subject: [PATCH 048/156] Styling --- doc_source/sample-ecr.md | 50 ++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 1b1ee60..f34f99d 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -81,32 +81,32 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains ``` { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "CodeBuildAccessPrincipal", - "Effect": "Allow", - "Principal": { - "Service": "codebuild.amazonaws.com" + "Version":"2012-10-17", + "Statement":[ + { + "Sid":"CodeBuildAccessPrincipal", + "Effect":"Allow", + "Principal":{ + "Service":"codebuild.amazonaws.com" + }, + "Action":[ + "ecr:BatchCheckLayerAvailability", + "ecr:BatchGetImage", + "ecr:GetDownloadUrlForLayer" + ] }, - "Action": [ - "ecr:BatchCheckLayerAvailability", - "ecr:BatchGetImage", - "ecr:GetDownloadUrlForLayer" - ] - }, - { - "Sid": "CodeBuildAccessCrossaccount", - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::AWS-account-ID:root" - }, - "Action": [ - "ecr:GetDownloadUrlForLayer", - "ecr:BatchGetImage", - "ecr:BatchCheckLayerAvailability" - ] - } + { + "Sid":"CodeBuildAccessCrossaccount", + "Effect":"Allow", + "Principal":{ + "AWS":"arn:aws:iam::AWS-account-ID:root" + }, + "Action":[ + "ecr:GetDownloadUrlForLayer", + "ecr:BatchGetImage", + "ecr:BatchCheckLayerAvailability" + ] + } ] } ``` From e12d3c72bc93fe9e365bca37cc6d09b7ab805e5f Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 18 Jun 2020 13:15:48 -0700 Subject: [PATCH 049/156] General update --- doc_source/build-env-ref-cmd.md | 4 +- doc_source/build-spec-ref.md | 549 +++++++++++++++------------ doc_source/create-project.md | 8 +- doc_source/how-to-create-pipeline.md | 2 +- doc_source/monitoring-builds.md | 86 ++++- doc_source/sample-ecr.md | 84 ++-- 6 files changed, 423 insertions(+), 310 deletions(-) diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index 389a397..54a3197 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.md @@ -7,10 +7,10 @@ You provide a set of commands for AWS CodeBuild to run in a build environment du + 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)\. -You can specify any Shell Command Language (sh) command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: +You can specify any Shell Command Language \(sh\) command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: + Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell\. For example, you could include a file named `my-script.sh` in your source code that contains commands such as `cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;`\. Then, in your buildspec file, specify the command `./my-script.sh`\. + In your buildspec file or on the **Build commands** setting for the `build` phase only, enter a single command that includes all of the commands you want to run in a single instance of the default shell \(for example, `cd MyDir && mkdir -p mySubDir && cd mySubDir && pwd`\)\. 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\. +Commands that are run in a Windows Server Core 2016 image use the Powershell shell\. \ No newline at end of file diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 825e44d..caa8c1f 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -52,12 +52,12 @@ env: - variable secrets-manager: key: secret-id:json-key:version-stage:version-id - git-credential-helper: yes + git-credential-helper: no | yes proxy: - upload-artifacts: yes - logs: yes - + upload-artifacts: no | yes + logs: no | yes + phases: install: run-as: Linux-user-name @@ -95,19 +95,19 @@ phases: - command - command reports: - report-name-or-arn: + report-group-name-or-arn: files: - location - location base-directory: location - discard-paths: yes + discard-paths: no | yes file-format: JunitXml | NunitXml | CucumberJson | VisualStudioTrx | TestNGXml artifacts: files: - location - location name: artifact-name - discard-paths: yes + discard-paths: no | yes base-directory: location secondary-artifacts: artifactIdentifier: @@ -115,13 +115,13 @@ artifacts: - location - location name: secondary-artifact-name - discard-paths: yes + discard-paths: no | yes base-directory: location artifactIdentifier: files: - location - location - discard-paths: yes + discard-paths: no | yes base-directory: location cache: paths: @@ -130,262 +130,327 @@ cache: ``` The buildspec contains the following: -+ `version`: Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. + +### version + +Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. + **Note** Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec versions](#build-spec-ref-versions)\. -+ `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\. -+ `env`: Optional sequence\. Represents information for one or more custom environment variables\. + +### 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\. + +### env + +Optional sequence\. Represents information for one or more custom environment variables\. + **Note** 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 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)\. - + `variables`: Required if `env` is specified, and you want to define custom environment variables in plain text\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable in plain text\. *key* is the name of the custom environment variable, and *value* is that variable's value\. -**Important** + +env/**variables** +Required if `env` is specified, and you want to define custom environment variables in plain text\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable in plain text\. *key* is the name of the custom environment variable, and *value* is that variable's value\. We strongly discourage the storing of sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. For sensitive values, we recommend that you use `parameter-store` or `secrets-manager` mapping instead, as described later in this section\. 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 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 buildspec declaration takes lowest precedence\. - + `parameter-store`: Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. -**Important** ++ 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 buildspec declaration takes lowest precedence\. + +env/**parameter\-store** +Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add the `ssm:GetParameters` action to your CodeBuild service role\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Store 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 retrieve 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 retrieve 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 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 buildspec declaration takes lowest precedence\. - + `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: ++ 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 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*\. + +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\. + 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 ++ Environment variables that start with `AWS_`\. - `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\. +env/**git\-credential\-help** +Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. + `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. - 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*\. - + `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\. +### proxy + +Optional sequence\. Used to represent settings if you run your build in an explicit proxy server\. For more information, see [ Run CodeBuild in an explicit proxy server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. + +proxy/**upload\-artifacts** +Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default is `no`\. + +proxy/**logs** +Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch logs\. The default is `no`\. + +### phases + +Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. - 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\. -**Note** - 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 - Environment variables that start with `AWS_`\. - + `git-credential-helper`: Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. -**Note** - `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. -+ `proxy`: Optional sequence\. Used to represent settings if you run your build in an explicit proxy server\. For more information, see [ Run CodeBuild in an explicit proxy server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. - + `upload-artifacts`: Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default is `no`\. - + `logs`: Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch logs\. The default is `no`\. -+ `phases`: Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. **Note** In buildspec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend the approaches in [Shells and commands in build environments](build-env-ref-cmd.md)\. - + `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\. - - The allowed build phase names are: - + `install`: Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. - + `runtime-versions`: Optional sequence\. A runtime version is supported with the Ubuntu standard image 2\.0 or later and the Amazon Linux 2 standard image 1\.0 or later\. If specified, at least one runtime must be included in this section\. Specify a runtime using a specific version, a major version followed by `.x` to specify that CodeBuild uses that major version with its latest minor version, or `latest` to use the most recent major and minor version \(for example, `java: openjdk11`, `ruby: 2.6`, `nodejs: 12.x`, or `java: latest`\)\. You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - - ``` - phases: - install: - runtime-versions: - java: corretto8 - 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\. - + 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\. + +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\. + +The allowed build phase names are: + +phases/**install** +Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. +phases/install/**runtime\-versions** +Optional sequence\. A runtime version is supported with the Ubuntu standard image 2\.0 or later and the Amazon Linux 2 standard image 1\.0 or later\. If specified, at least one runtime must be included in this section\. Specify a runtime using a specific version, a major version followed by `.x` to specify that CodeBuild uses that major version with its latest minor version, or `latest` to use the most recent major and minor version \(for example, `java: openjdk11`, `ruby: 2.6`, `nodejs: 12.x`, or `java: latest`\)\. You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. + +``` +phases: + install: + runtime-versions: + java: corretto8 + 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\. +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) -**Note** - 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`\." - + `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\. - + `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\. - + `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\. - + `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\. - + `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\. - + `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\. - + `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\. + 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\. + +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\. + +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\. + +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)\. -+ `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\. -+ `report-name-or-arn`: Optional sequence\. Represents information about where you want the files with your test results\. A project can have a maximum of five report groups\. Specify a name for a new report group or the ARN of an existing report group\. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format project\-name\-report\-group\-name\-in\-buildspec\. For more information, see [Report group naming](test-report-group-naming.md)\. - + `files`: Required sequence\. Represents the locations that contain the raw data of test results generated by the report\. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find test files, relative to the original build location or, if set, the `base-directory`\. Locations can include the following: - + A single file \(for example, `my-test-report-file.json`\)\. - + A single file in a subdirectory \(for example, `my-subdirectory/my-test-report-file.json` or `my-parent-subdirectory/my-subdirectory/my-test-report-file.json`\)\. - + `'**/*'` represents all files recursively\. - + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. - + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. - + `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\. - + `discard-paths`: Optional mapping\. Represents whether paths to test result files uploaded to an S3 bucket are discarded\. `yes` if paths are discarded\. Otherwise, `no` or not specified \(the default\)\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` shortens this path to `TesResult.xml`\. - + `file-format`: Optional mapping\. Represents the test file format\. If not specified, `JunitXml` is used\. The valid values are: - + `CucumberJson` - + `JunitXml` - + `NunitXml` - + `TestNGXml` - + `VisualStudioTrx` -+ `artifacts`: 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\. - + `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`\)\. - + A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. - + `'**/*'` represents all files recursively\. - + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. - + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. - - When you specify build output artifact locations, CodeBuild can locate the original build location in the build environment\. You do not have to prepend your build artifact output locations with the path to the original build location or specify `./` or similar\. If you want to know the path to this location, you can run a command such as `echo $CODEBUILD_SRC_DIR` during a build\. The location for each build environment might be slightly different\. - + `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.md#create-project-console)\. - - 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: +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)\. + +### reports + +**report\-group\-name\-or\-arn** +Optional sequence\. Specifies the report group that the reports are sent to\. A project can have a maximum of five report groups\. Specify the ARN of an existing report group, or the name of a new report group\. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format `-`\. For more information, see [Report group naming](test-report-group-naming.md)\. + +reports//**files** +Required sequence\. Represents the locations that contain the raw data of test results generated by the report\. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find test files, relative to the original build location or, if set, the `base-directory`\. Locations can include the following: ++ A single file \(for example, `my-test-report-file.json`\)\. ++ A single file in a subdirectory \(for example, `my-subdirectory/my-test-report-file.json` or `my-parent-subdirectory/my-subdirectory/my-test-report-file.json`\)\. ++ `'**/*'` represents all files recursively\. ++ `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. ++ `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` + +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\. + +reports//**discard\-paths** +Optional\. Specifies if the report file directories are flattened in the output\. If this is not specified, or contains `no`, report files are output with their directory structure intact\. If this contains `yes`, all of the test files are placed in the same output directory\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` will place this file in `/TestResult.xml`\. + +### artifacts + +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\. + +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`\)\. ++ A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. ++ `'**/*'` represents all files recursively\. ++ `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. ++ `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. +When you specify build output artifact locations, CodeBuild can locate the original build location in the build environment\. You do not have to prepend your build artifact output locations with the path to the original build location or specify `./` or similar\. If you want to know the path to this location, you can run a command such as `echo $CODEBUILD_SRC_DIR` during a build\. The location for each build environment might be slightly different\. + +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.md#create-project-console)\. +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\. + +``` +version: 0.2 +phases: + build: + commands: + - rspec HelloWorld_spec.rb +artifacts: + files: + - '**/*' + name: $AWS_REGION-$(date +%Y-%m-%d) +``` + +artifacts/**discard\-paths** +Optional\. Specifies if the build artifact directories are flattened in the output\. If this is not specified, or contains `no`, build artifacts are output with their directory structure intact\. If this contains `yes`, all of the build artifacts are placed in the same output directory\. For example, if a path to a file in the build output artifact is `com/mycompany/app/HelloWorld.java`, specifying `yes` will place this file in `/HelloWorld.java`\. + +artifacts/**base\-directory** +Optional mapping\. Represents one or more top\-level directories, relative to the original build location, that CodeBuild uses to determine which files and subdirectories to include in the build output artifact\. Valid values include: ++ A single top\-level directory \(for example, `my-directory`\)\. ++ `'my-directory*'` represents all top\-level directories with names starting with `my-directory`\. +Matching top\-level directories are not included in the build output artifact, only their files and subdirectories\. +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 +``` +And for the following `artifacts` sequence: + +``` +artifacts: + files: + - '*/my-file3.txt' + base-directory: my-build2 +``` +The following subdirectory and file would be included in the build output artifact: + +``` +my-subdirectory + `-- my-file3.txt +``` +While for the following `artifacts` sequence: + +``` +artifacts: + files: + - '**/*' + base-directory: 'my-build*' + discard-paths: yes +``` +The following files would be included in the build output artifact: + +``` +|-- my-file1.txt +|-- my-file2.txt +`-- my-file3.txt +``` + +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\. For example, if your project has the following structure: + +``` +{ + "name": "sample-project", + "secondaryArtifacts": [ + { + "type": "S3", + "location": "output-bucket1", + "artifactIdentifier": "artifact1", + "name": "secondary-artifact-name-1" + }, + { + "type": "S3", + "location": "output-bucket2", + "artifactIdentifier": "artifact2", + "name": "secondary-artifact-name-2" + } + ] +} +``` +Then your buildspec looks like the following: + +``` +version: 0.2 + +phases: +build: + commands: + - echo Building... +artifacts: + secondary-artifacts: + artifact1: 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: + - directory/file + name: secondary-artifact-name-1 + artifact2: files: - - '**/*' - name: $AWS_REGION-$(date +%Y-%m-%d) - ``` - + `discard-paths`: Optional mapping\. Represents whether paths to files in the build output artifact are discarded\. `yes` if paths are discarded; otherwise, `no` or not specified \(the default\)\. For example, if a path to a file in the build output artifact would be `com/mycompany/app/HelloWorld.java`, then specifying `yes` would shorten this path to simply `HelloWorld.java`\. - + `base-directory`: Optional mapping\. Represents one or more top\-level directories, relative to the original build location, that CodeBuild uses to determine which files and subdirectories to include in the build output artifact\. Valid values include: - + A single top\-level directory \(for example, `my-directory`\)\. - + `'my-directory*'` represents all top\-level directories with names starting with `my-directory`\. - - Matching top\-level directories are not included in the build output artifact, only their files and subdirectories\. - - 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 - ``` - - And for the following `artifacts` sequence: - - ``` - artifacts: - files: - - '*/my-file3.txt' - base-directory: my-build2 - ``` - - The following subdirectory and file would be included in the build output artifact: - - ``` - my-subdirectory - `-- my-file3.txt - ``` - - While for the following `artifacts` sequence: - - ``` - artifacts: - files: - - '**/*' - base-directory: 'my-build*' - discard-paths: yes - ``` - - The following files would be included in the build output artifact: - - ``` - |-- my-file1.txt - |-- my-file2.txt - `-- my-file3.txt - ``` - + `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\. For example, if your project has the following structure: - - ``` - { - "name": "sample-project", - "secondaryArtifacts": [ - { - "type": "S3", - "location": "output-bucket1", - "artifactIdentifier": "artifact1", - "name": "secondary-artifact-name-1" - }, - { - "type": "S3", - "location": "output-bucket2", - "artifactIdentifier": "artifact2", - "name": "secondary-artifact-name-2" - } - ] - } - ``` - - Then your buildspec looks like the following: - - ``` - version: 0.2 - - phases: - build: - commands: - - echo Building... - artifacts: - secondary-artifacts: - artifact1: - files: - - directory/file - name: secondary-artifact-name-1 - artifact2: - files: - - directory/file2 - name: secondary-artifact-name-2 - ``` -+ `cache`: Optional sequence\. Represents information about where CodeBuild can prepare the files for uploading cache to an S3 cache bucket\. This sequence is not required if the cache type of the project is `No Cache`\. - + `paths`: Required sequence\. Represents the locations of the cache\. 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`\)\. - + A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. - + `'**/*'` represents all files recursively\. - + `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. - + `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. + - directory/file2 + name: secondary-artifact-name-2 +``` + +### cache + +Optional sequence\. Represents information about where CodeBuild can prepare the files for uploading cache to an S3 cache bucket\. This sequence is not required if the cache type of the project is `No Cache`\. + +cache/**paths** +Required sequence\. Represents the locations of the cache\. 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`\)\. ++ A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. ++ `'**/*'` represents all files recursively\. ++ `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. ++ `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. **Important** Because a buildspec declaration must be valid YAML, the spacing in a buildspec declaration is important\. If the number of spaces in your buildspec declaration is invalid, builds might fail immediately\. You can use a YAML validator to test whether your buildspec declarations are valid YAML\. @@ -480,15 +545,13 @@ In these examples: + `files` represents the files to upload to the build output location\. In this example, CodeBuild uploads the single file `messageUtil-1.0.jar`\. The `messageUtil-1.0.jar` file can be found in the relative directory named `target` in the build environment\. Because `discard-paths: yes` is specified, `messageUtil-1.0.jar` is uploaded directly \(and not to an intermediate `target` directory\)\. The file name `messageUtil-1.0.jar` and the relative directory name of `target` is based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own scenarios, these file names and directories will be different\. + `reports` represents two report groups that generate reports during the build: + `arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1` specifies the ARN of a report group\. Test results generated by the test framework are in the `target/tests/reports` directory\. The file format is `JunitXml` and the path is not removed from the files that contain test results\. - + `reportGroupCucumberJson` specifies a new report group\. If the name of the project is `my-project`, a report group with the name `my-project-reportGroupCucumberJson` is created when a build is run\.\. Test results generated by the test framework are in `cucumber/target/cucumber-tests.xml`\. The test file format is `CucumberJson` and the path is removed from the files that contain test results\. + + `reportGroupCucumberJson` specifies a new report group\. If the name of the project is `my-project`, a report group with the name `my-project-reportGroupCucumberJson` is created when a build is run\. Test results generated by the test framework are in `cucumber/target/cucumber-tests.xml`\. The test file format is `CucumberJson` and the path is removed from the files that contain test results\. ## Buildspec versions The following table lists the buildspec versions and the changes between versions\. -**** - | Version | Changes | | --- | --- | | 0\.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) | diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 8a0cf45..869a3ab 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -224,10 +224,10 @@ For information about using the AWS CLI with CodeBuild, see the [Command line re "resource": "resource" } }, - ”sourceVersion”: “source-version”, - “secondarySourceVersions”: { - “sourceIdentifier”: ”secondary-source-identifier”, - “sourceVersion”: ”secondary-source-version” + "sourceVersion": "source-version", + "secondarySourceVersions": { + "sourceIdentifier": "secondary-source-identifier", + "sourceVersion": "secondary-source-version" }, "artifacts": { "type": "artifacts-type", diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 97e3106..8498b52 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -572,4 +572,4 @@ To store and retrieve sensitive values, we recommend your build commands use the 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\. +1. Scroll through the build log to view the test results\. \ No newline at end of file diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index 6a7a62b..b2b078d 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.md @@ -18,25 +18,75 @@ The following metrics can be tracked per AWS account or build project\. +BuildDuration +Measures the duration of the build's `BUILD` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum -**** - -| Metric | Description | -| --- | --- | -| BuildDuration | Measures the duration of the build's BUILD phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| `Builds` | Measures the number of builds triggered\. Units: Count Valid CloudWatch statistics: Sum | -| DownloadSourceDuration | Measures the duration of the build's DOWNLOAD\_SOURCE phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| `Duration` | Measures the duration of all builds over time\. Units: Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| `FailedBuilds` | Measures the number of builds that failed because of client error or a timeout\. Units: Count Valid CloudWatch statistics: Sum | -| FinalizingDuration | Measures the duration of the build's FINALIZING phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| InstallDuration | Measures the duration of the build's INSTALL phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| PostBuildDuration | Measures the duration of the build's POST\_BUILD phase Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| PreBuildDuration | Measures the duration of the build's PRE\_BUILD phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| ProvisioningDuration | Measures the duration of the build's PROVISIONING phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| QueuedDuration | Measures the duration of the build's QUEUED phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| SubmittedDuration | Measures the duration of the build's SUBMITTED phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | -| `SucceededBuilds` | Measures the number of successful builds\. Units: Count Valid CloudWatch statistics: Sum | -| UploadArtifactsDuration | Measures the duration of the build's UPLOAD\_ARTIFACTS phase\. Units:Seconds Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum | +Builds + Measures the number of builds triggered\. + Units: Count + Valid CloudWatch statistics: Sum + +DownloadSourceDuration +Measures the duration of the build's `DOWNLOAD_SOURCE` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +Duration + Measures the duration of all builds over time\. + Units: Seconds + Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +FailedBuilds + Measures the number of builds that failed because of client error or a timeout\. + Units: Count + Valid CloudWatch statistics: Sum + +FinalizingDuration +Measures the duration of the build's `FINALIZING` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +InstallDuration +Measures the duration of the build's `INSTALL` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +PostBuildDuration +Measures the duration of the build's `POST_BUILD` phase +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +PreBuildDuration +Measures the duration of the build's `PRE_BUILD` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +ProvisioningDuration +Measures the duration of the build's `PROVISIONING` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +QueuedDuration +Measures the duration of the build's `QUEUED` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +SubmittedDuration +Measures the duration of the build's `SUBMITTED` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +SucceededBuilds + Measures the number of successful builds\. + Units: Count + Valid CloudWatch statistics: Sum + +UploadArtifactsDuration +Measures the duration of the build's `UPLOAD_ARTIFACTS` phase\. +Units: Seconds +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum ## CodeBuild CloudWatch dimensions diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index f34f99d..af085d8 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -2,7 +2,7 @@ This sample uses a Docker image in an Amazon Elastic Container Registry \(Amazon ECR\) image repository to build a sample Go project\. -**Important** +**Important** Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing)\. ## Running the sample @@ -11,11 +11,11 @@ Running this sample might result in charges to your AWS account\. These include 1. To create and push the Docker image to your image repository in Amazon ECR, complete the steps in the "Running the sample" section of the [Docker sample](sample-docker.md)\. -1. Create a Go project: +1. Create a Go project: - 1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. -**Important** -Do not upload `(root directory name)`, just the files inside of `(root directory name)`\. + 1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. +**Important** +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 view related build information by following the steps in [Run AWS CodeBuild directly](how-to-run.md)\. @@ -47,11 +47,11 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. To get the build output artifact, open your S3 output bucket\. - 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file\. In the extracted contents, get the `hello` file\. + 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file\. In the extracted contents, get the `hello` file\. -1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment\. - + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`\. - + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`\. +1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment\. + + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`\. + + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`\. 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. @@ -64,7 +64,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 1. For **Effect**, leave **Allow** selected\. This indicates that you want to allow access to another AWS account\. 1. For **Principal**, do one of the following: - + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild\.amazonaws\.com**\. + + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild\.amazonaws\.com**\. + If your project uses a cross\-account Amazon ECR image, for **AWS account IDs**, enter IDs of the AWS accounts that you want to give access\. 1. Skip the **All IAM entities** list\. @@ -77,41 +77,41 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains + If your project uses CodeBuild credentials to pull an Amazon ECR image, `"codebuild.amazonaws.com"` appears under **Service principals**\. + If your project uses a cross\-account Amazon ECR image, the ID of the AWS account that you want to give access appears under **AWS Account IDs**\. - The following sample policy uses a cross\-account Amazon ECR image\. + 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:BatchCheckLayerAvailability", - "ecr:BatchGetImage", - "ecr:GetDownloadUrlForLayer" - ] + { + "Sid":"CodeBuildAccessPrincipal", + "Effect":"Allow", + "Principal":{ + "Service":"codebuild.amazonaws.com" }, - { - "Sid":"CodeBuildAccessCrossaccount", - "Effect":"Allow", - "Principal":{ - "AWS":"arn:aws:iam::AWS-account-ID:root" - }, - "Action":[ - "ecr:GetDownloadUrlForLayer", - "ecr:BatchGetImage", - "ecr:BatchCheckLayerAvailability" - ] - } + "Action":[ + "ecr:GetDownloadUrlForLayer", + "ecr:BatchGetImage", + "ecr:BatchCheckLayerAvailability" + ] + }, + { + "Sid":"CodeBuildAccessCrossAccount", + "Effect":"Allow", + "Principal":{ + "AWS":"arn:aws:iam:::root" + }, + "Action":[ + "ecr:GetDownloadUrlForLayer", + "ecr:BatchGetImage", + "ecr:BatchCheckLayerAvailability" + ] + } ] } ``` -2. 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 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\.\) @@ -138,9 +138,9 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains } ``` -3. To get the build output artifact, open your S3 output bucket\. +1. To get the build output artifact, open your S3 output bucket\. -4. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file\. In the extracted contents, get the `hello` file\. +1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file\. In the extracted contents, get the `hello` file\. ## Go project structure @@ -162,14 +162,14 @@ This sample uses these files\. version: 0.2 phases: - install: - runtime-versions: - golang: 1.13 + install: + runtime-versions: + golang: 1.13 build: commands: - echo Build started on `date` - - echo Compiling the Go code... - - go build hello.go + - echo Compiling the Go code + - go build hello.go post_build: commands: - echo Build completed on `date` From 74617b879da92cf6c1a768f26b0ef78db3770e89 Mon Sep 17 00:00:00 2001 From: AdrianP873 <31646350+AdrianP873@users.noreply.github.com> Date: Sat, 20 Jun 2020 08:18:46 +1000 Subject: [PATCH 050/156] Fix spelling mistake "mulitple" to "multiple" --- doc_source/sample-buildspec-artifact-naming.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/sample-buildspec-artifact-naming.md b/doc_source/sample-buildspec-artifact-naming.md index dc06d4e..208847b 100644 --- a/doc_source/sample-buildspec-artifact-naming.md +++ b/doc_source/sample-buildspec-artifact-naming.md @@ -2,7 +2,7 @@ This sample contains example buildspec files that demonstrate how to specify an artifact name that is created at build time\. A name specified in a buildspec file can incorporate Shell commands and environment variables to make it unique\. A name you specify in a buildspec file overrides a name you enter in the console when you create your project\. - If you build mulitple times, using an artifact name specified in the buildspec file can ensure your output artifact file names are unique\. For example, you can use a date and timestamp that is inserted into an artifact name at build time\. + If you build multiple times, using an artifact name specified in the buildspec file can ensure your output artifact file names are unique\. For example, you can use a date and timestamp that is inserted into an artifact name at build time\. If you want to override the artifact name you entered in the console with a name in the buildspec file, do the following: @@ -79,4 +79,4 @@ artifacts: name: $Env:TEST_ENV_VARIABLE-$Env:AWS_REGION ``` - For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. \ No newline at end of file + For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. From 34d467a1005dbe53252a06459d517e1210e2df0e Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 24 Jun 2020 13:39:27 -0700 Subject: [PATCH 051/156] General update --- ...ntrol-iam-identity-based-access-control.md | 10 +-- doc_source/index.md | 2 +- doc_source/notification-rule-create.md | 2 +- .../sample-buildspec-artifact-naming.md | 2 +- doc_source/samples.md | 30 +------ doc_source/use-case-based-samples.md | 90 +++++++++++++------ doc_source/working-with-build-projects.md | 2 +- 7 files changed, 77 insertions(+), 61 deletions(-) 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 592054c..83618bd 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 @@ -9,7 +9,7 @@ We recommend that you first review the introductory topics that explain the basi + [Permissions required to use the AWS CodeBuild console](#console-permissions) + [Permissions required for the AWS CodeBuild console to connect to source providers](#console-policies) + [AWS managed \(predefined\) policies for AWS CodeBuild](#managed-policies) -+ [CodeBuild Managed Policies and Notifications](#notifications-permissions) ++ [CodeBuild managed policies and notifications](#notifications-permissions) + [Customer\-managed policy examples](#customer-managed-policies) The following shows an example of a permissions policy that allows a user to get information about build projects only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: @@ -313,11 +313,11 @@ The `AWSCodeBuildReadOnlyAccess` policy contains the following policy statement: } ``` -## CodeBuild Managed Policies and Notifications +## CodeBuild managed policies and notifications CodeBuild supports notifications, which can notify users of important changes to build projects\. Managed policies for CodeBuild include policy statements for notification functionality\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html)\. -### Permissions Related to Notifications in Full Access Managed Policies +### Permissions related to notifications in full access managed policies The `AWSCodeBuildFullAccess` managed policy includes the following statements to allow full access to notifications\. Users with this managed policy applied can also create and manage Amazon SNS topics for notifications, subscribe and unsubscribe users to topics, list topics to choose as targets for notification rules, and list AWS Chatbot clients configured for Slack\. @@ -376,7 +376,7 @@ The `AWSCodeBuildFullAccess` managed policy includes the following statements to } ``` -### Permissions Related to Notifications in Read\-Only Managed Policies +### Permissions related to notifications in read\-only managed policies The `AWSCodeBuildReadOnlyAccess` managed policy includes the following statements to allow read\-only access to notifications\. Users with this managed policy applied can view notifications for resources, but cannot create, manage, or subscribe to them\. @@ -404,7 +404,7 @@ The `AWSCodeBuildReadOnlyAccess` managed policy includes the following statement } ``` -### Permissions Related to Notifications in Other Managed Policies +### Permissions related to notifications in other managed policies The `AWSCodeBuildDeveloperAccess` managed policy includes the following statements to allow users to create, edit, and subscribe to notifications\. Users cannot delete notification rules or manage tags for resources\. diff --git a/doc_source/index.md b/doc_source/index.md index d4bb893..ea57583 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -86,7 +86,7 @@ Amazon's trademarks and trade dress may not be used in + [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) - + [Create a Notification Rule](notification-rule-create.md) + + [Create a notification rule](notification-rule-create.md) + [View a list of build project names in AWS CodeBuild](view-project-list.md) + [View a build project's details in AWS CodeBuild](view-project-details.md) + [Build caching in AWS CodeBuild](build-caching.md) diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md index abd285a..5f100e4 100644 --- a/doc_source/notification-rule-create.md +++ b/doc_source/notification-rule-create.md @@ -1,4 +1,4 @@ -# Create a Notification Rule +# Create a notification rule 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) diff --git a/doc_source/sample-buildspec-artifact-naming.md b/doc_source/sample-buildspec-artifact-naming.md index 208847b..4869ad3 100644 --- a/doc_source/sample-buildspec-artifact-naming.md +++ b/doc_source/sample-buildspec-artifact-naming.md @@ -79,4 +79,4 @@ artifacts: name: $Env:TEST_ENV_VARIABLE-$Env:AWS_REGION ``` - For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. + For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. \ No newline at end of file diff --git a/doc_source/samples.md b/doc_source/samples.md index 0b6de01..d7dd5ec 100644 --- a/doc_source/samples.md +++ b/doc_source/samples.md @@ -1,29 +1,7 @@ # CodeBuild samples - These use case\-based samples can be used to experiment with AWS CodeBuild: +These groups of samples can be used to experiment with AWS CodeBuild: - -**** - -| Name | Description | -| --- | --- | -| [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\. | -| [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\. | -| [Amazon EFS sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | -| [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\. | -| [Build badges sample](sample-build-badges.md) | Shows how to set up CodeBuild with build badges\. | -| [Build notifications sample](sample-build-notifications.md) | Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. | -| [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) | Shows how to use AWS CodePipeline to create a build with multiple input sources and multiple output artifacts\. | -| [ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. | -| [Create a test report in CodeBuild using the AWS CLI sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | -| [Docker in custom image sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | -| [Docker sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | -| [GitHub Enterprise Server sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise Server as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [GitHub pull request and webhook filter sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | -| [Private registry with AWS Secrets Manager sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment\. The private registry credentials are stored in Secrets Manager\. | -| [AWS Config sample](how-to-integrate-config.md) | Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. | -| [ Access token sample ](sample-access-tokens.md) | Shows how to use access tokens in CodeBuild to connect to GitHub and Bitbucket\. | -| [Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) | Shows how to use semantic versioning to create an artifact name at build time\. | \ No newline at end of file +**Topics** ++ [Microsoft Windows samples for CodeBuild](sample-windows.md) ++ [CodeBuild use case\-based samples](use-case-based-samples.md) \ 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 99debb9..c4cd209 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -2,30 +2,68 @@ 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\. -**** - -| Name | Description | -| --- | --- | -| [ 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\. | -| [Amazon EFS sample](sample-efs.md) | Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. | -| [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) | 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) | Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. | -| [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\. | -| [Build badges sample](sample-build-badges.md) | Shows how to set up CodeBuild with build badges\. | -| [Build notifications sample](sample-build-notifications.md) | Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. | -| [Create a test report using the AWS CLI sample](sample-test-report-cli.md) | Uses the AWS CLI to create, run, and view the results of a test report\. | -| [Docker in custom image sample](sample-docker-custom-image.md) | Uses a custom Docker image to produce a Docker image\. | -| [Docker sample](sample-docker.md) | Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. | -| [GitHub Enterprise Server sample](sample-github-enterprise.md) | Uses CodeBuild with GitHub Enterprise Server as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [GitHub pull request and webhook filter sample](sample-github-pull-request.md) | Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. | -| [ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) | Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. | -| [ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) | Shows how to use multiple input sources and multiple output artifacts in a build project\. | -| [Private registry with AWS Secrets Manager sample](sample-private-registry.md) | Shows how to use a Docker image in a private registry as the runtime environment when building with CodeBuild The private registry credentials are stored in AWS Secrets Manager\. | -| [ Runtime versions in buildspec file sample ](sample-runtime-versions.md) | Shows how to specify runtimes and their versions in the buildspec file\. This is a requirement when using the Ubuntu standard image version 2\.0\. | -| [Source version sample](sample-source-version.md) | Shows how to use a specific version of your source in a CodeBuild build project\. | -| [Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) | Shows how to use semantic versioning to create an artifact name at build time\. | \ No newline at end of file +[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\. + +[Amazon EFS sample](sample-efs.md) +Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. + +[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) +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) +Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. + +[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\. + +[Build badges sample](sample-build-badges.md) +Shows how to set up CodeBuild with build badges\. + +[Build notifications sample](sample-build-notifications.md) +Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. + +[Create a test report using the AWS CLI sample](sample-test-report-cli.md) +Uses the AWS CLI to create, run, and view the results of a test report\. + +[Docker in custom image sample](sample-docker-custom-image.md) +Uses a custom Docker image to produce a Docker image\. + +[Docker sample](sample-docker.md) +Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. + +[GitHub Enterprise Server sample](sample-github-enterprise.md) +Uses CodeBuild with GitHub Enterprise Server as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. + +[GitHub pull request and webhook filter sample](sample-github-pull-request.md) +Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. + +[ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) +Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. + +[ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) +Shows how to use multiple input sources and multiple output artifacts in a build project\. + +[Private registry with AWS Secrets Manager sample](sample-private-registry.md) +Shows how to use a Docker image in a private registry as the runtime environment when building with CodeBuild The private registry credentials are stored in AWS Secrets Manager\. + +[ Runtime versions in buildspec file sample ](sample-runtime-versions.md) +Shows how to specify runtimes and their versions in the buildspec file\. This is a requirement when using the Ubuntu standard image version 2\.0\. + +[Source version sample](sample-source-version.md) +Shows how to use a specific version of your source in a CodeBuild build project\. + +[Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) +Shows how to use semantic versioning to create an artifact name at build time\. \ No newline at end of file diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 31a2c4f..48df157 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -6,7 +6,7 @@ You can perform these tasks when working with build projects: **Topics** + [Create a build project in AWS CodeBuild](create-project.md) -+ [Create a Notification Rule](notification-rule-create.md) ++ [Create a notification rule](notification-rule-create.md) + [View a list of build project names in AWS CodeBuild](view-project-list.md) + [View a build project's details in AWS CodeBuild](view-project-details.md) + [Build caching in AWS CodeBuild](build-caching.md) From f787631097afe7faa4066119de49a2a3b886371e Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 29 Jun 2020 09:00:11 -0700 Subject: [PATCH 052/156] General update --- doc_source/build-spec-ref.md | 10 ++++++++++ doc_source/create-project.md | 14 ++++++++++++-- doc_source/history.md | 1 + doc_source/run-build.md | 4 ++-- 4 files changed, 25 insertions(+), 4 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index caa8c1f..5d116cd 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -41,6 +41,7 @@ version: 0.2 run-as: Linux-user-name env: + shell: shell-tag variables: key: "value" key: "value" @@ -152,6 +153,15 @@ Optional sequence\. Represents information for one or more custom environment va 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)\. +env/**shell** +Optional sequence\. Specifies the supported shell for Linux or Windows operating systems\. +For Linux operating systems, supported shell tags are: ++ `bash` ++ `/bin/sh` +For Windows operating systems, supported shell tags are: ++ `powershell.exe` ++ `cmd.exe` + env/**variables** Required if `env` is specified, and you want to define custom environment variables in plain text\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable in plain text\. *key* is the name of the custom environment variable, and *value* is that variable's value\. We strongly discourage the storing of sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. For sensitive values, we recommend that you use `parameter-store` or `secrets-manager` mapping instead, as described later in this section\. diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 869a3ab..34755e4 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -467,9 +467,19 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro + *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`, and `WINDOWS_CONTAINER`\. + + *environment\-type*: Required\. The type of build environment\. Valid values are: + + `ARM_CONTAINER` + + `LINUX_CONTAINER` + + `LINUX_GPU_CONTAINER` + + `WINDOWS_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, and BUILD_GENERAL1_2XLARGE`\. `BUILD_GENERAL1_2XLARGE` is only supported with the `LINUX_CONTAINER` environment type\. + + *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*\. diff --git a/doc_source/history.md b/doc_source/history.md index d808f4d..b35e512 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -6,6 +6,7 @@ The following table describes the important changes to the documentation since t | Change | Description | Date | | --- |--- |--- | +| [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 | | [Support for test reporting](#history) | CodeBuild support for test reporting is now generally available\. | May 21, 2020 | diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 74018df..d372b90 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -21,7 +21,7 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll 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 you 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 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.md#create-project-source-provider)\. @@ -118,7 +118,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 `--project-name` option, replace *project\-name* 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 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\-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: From ebb19f4b87fb606bf2326101e22f8f9e3d943132 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 1 Jul 2020 08:15:33 -0700 Subject: [PATCH 053/156] General update --- doc_source/build-spec-ref.md | 6 +- doc_source/getting-started-cli-output.md | 6 +- doc_source/getting-started-output-console.md | 6 +- doc_source/index.md | 11 +- ...dent-response.md => logging-monitoring.md} | 2 +- doc_source/monitoring-builds.md | 81 ++++++++++++-- doc_source/monitoring-metrics.md | 33 ++++-- doc_source/monitoring-utilization-metrics.md | 102 ++++++++++++++++++ doc_source/run-build.md | 4 +- doc_source/security.md | 1 - doc_source/troubleshooting.md | 2 +- 11 files changed, 221 insertions(+), 33 deletions(-) rename doc_source/{security-incident-response.md => logging-monitoring.md} (86%) create mode 100644 doc_source/monitoring-utilization-metrics.md diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 5d116cd..e4635d0 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -408,7 +408,9 @@ The following files would be included in the build output artifact: ``` 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\. For example, if your project has the following structure: +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\. +For example, if your project has the following structure: ``` { @@ -439,6 +441,8 @@ build: commands: - echo Building... artifacts: + files: + - '**/*' secondary-artifacts: artifact1: files: diff --git a/doc_source/getting-started-cli-output.md b/doc_source/getting-started-cli-output.md index a8ab3c8..ff26f2d 100644 --- a/doc_source/getting-started-cli-output.md +++ b/doc_source/getting-started-cli-output.md @@ -8,9 +8,11 @@ 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, in **Build Status**, choose the **View artifacts** link\. This opens the folder in Amazon S3 for the build output artifact\. \(If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\.\) +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\. +**Note** +If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\. -1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. +1. The link to the Amazon S3 folder is under the **Artifacts upload location**\. This link opens the folder in Amazon S3 where you find the `messageUtil-1.0.jar` build output artifact file\. **To get the build output artifact \(Amazon S3 console\)** diff --git a/doc_source/getting-started-output-console.md b/doc_source/getting-started-output-console.md index e71a306..ceba64d 100644 --- a/doc_source/getting-started-output-console.md +++ b/doc_source/getting-started-output-console.md @@ -8,9 +8,11 @@ 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, in **Build Status**, choose the **View artifacts** link\. This opens the folder in Amazon S3 for the build output artifact\. \(If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\.\) +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\. +**Note** +If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\. -1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. +1. The link to the Amazon S3 folder is under the **Artifacts upload location**\. This link opens the folder in Amazon S3 where you find the `messageUtil-1.0.jar` build output artifact file\. **To get the build output artifact \(Amazon S3 console\)** diff --git a/doc_source/index.md b/doc_source/index.md index ea57583..0721e5a 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -135,6 +135,12 @@ 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) ++ [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) + + [Monitoring CodeBuild metrics](monitoring-metrics.md) + + [Monitoring CodeBuild resource utilization metrics](monitoring-utilization-metrics.md) + + [Monitoring builds with CloudWatch alarms](monitoring-alarms.md) + [Security in AWS CodeBuild](security.md) + [Data protection in AWS CodeBuild](data-protection.md) + [Data encryption](security-encryption.md) @@ -146,11 +152,6 @@ Amazon's trademarks and trade dress may not be used in + [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md) + [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md) + [Viewing resources in the console](console-resources.md) - + [Logging and monitoring in AWS CodeBuild](security-incident-response.md) - + [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md) - + [Monitoring AWS CodeBuild](monitoring-builds.md) - + [Monitoring builds with CloudWatch metrics](monitoring-metrics.md) - + [Monitoring builds with CloudWatch alarms](monitoring-alarms.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) diff --git a/doc_source/security-incident-response.md b/doc_source/logging-monitoring.md similarity index 86% rename from doc_source/security-incident-response.md rename to doc_source/logging-monitoring.md index 70cc362..5991e0b 100644 --- a/doc_source/security-incident-response.md +++ b/doc_source/logging-monitoring.md @@ -1,4 +1,4 @@ -# Logging and monitoring in AWS CodeBuild +# Logging and monitoring in AWS CodeBuild Monitoring is an important part of maintaining the reliability, availability, and performance of AWS CodeBuild and your AWS solutions\. You should collect monitoring data from all of the parts of your AWS solution so that you can more easily debug a multi\-point failure, if one occurs\. AWS provides the following tools for monitoring your CodeBuild resources and builds and for responding to potential incidents\. diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index b2b078d..6b057fd 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.md @@ -1,20 +1,23 @@ # Monitoring AWS CodeBuild - You can use Amazon CloudWatch to watch your builds, report when something is wrong, and take automatic actions when appropriate\. You can monitor your builds at two levels: -+ Project level: These metrics are for all builds in the specified project only\. To see metrics for a project, specify `ProjectName` for the dimension in CloudWatch\. -+ AWS account level: These metrics are for all builds in one account\. To see metrics at the AWS account level, do not enter a dimension in CloudWatch\. +You can use Amazon CloudWatch to watch your builds, report when something is wrong, and take automatic actions when appropriate\. You can monitor your builds at two levels: - CloudWatch metrics show the behavior of your builds over time\. For example, you can monitor: +Project level +These metrics are for all builds in the specified project\. To see metrics for a project, specify `ProjectName` for the dimension in CloudWatch\. + +AWS account level +These metrics are for all builds in an account\. To see metrics at the AWS account level, do not enter a dimension in CloudWatch\. Build resource utilization metrics are not available at the AWS account level\. + +CloudWatch metrics show the behavior of your builds over time\. For example, you can monitor: + 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\. ++ Build resource utilization for a build or an entire build project\. Build resource utilization metrics include metrics such as CPU, memory, and storage utilization\. - Metrics displayed in the CodeBuild console are always from the past three days\. You can use the CloudWatch console to view CodeBuild metrics over different durations\. - - For more information, see [Monitoring builds with CloudWatch metrics](monitoring-metrics.md)\. + For more information, see [Monitoring CodeBuild metrics](monitoring-metrics.md)\. -## CodeBuild CloudWatch Metrics +## CodeBuild CloudWatch metrics The following metrics can be tracked per AWS account or build project\. @@ -88,14 +91,72 @@ Measures the duration of the build's `UPLOAD_ARTIFACTS` phase\. Units: Seconds 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 +Asia Pacific \(Seoul\) Region +Asia Pacific \(Mumbai\) Region +Asia Pacific \(Singapore\) Region +Asia Pacific \(Sydney\) Region +Canada \(Central\) Region +Europe \(Frankfurt\) Region +Europe \(Ireland\) Region +Europe \(London\) Region +Europe \(Paris\) Region +South America \(São Paulo\) Region +US East \(N\. Virginia\) Region +US East \(Ohio\) Region +US West \(N\. California\) Region +US West \(Oregon\) Region + +CPUUtilized +The number of CPU units of allocated processing used by the build container\. +Units: CPU units +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +CPUUtilizedPercent +The percentage of allocated processing used by the build container\. +Units: Percent +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +MemoryUtilized +The number of megabytes of memory used by the build container\. +Units: Megabytes +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +MemoryUtilizedPercent +The percentage of allocated memory used by the build container\. +Units: Percent +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +StorageReadBytes +The storage read speed used by the build container\. +Units: Bytes/second +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + +StorageWriteBytes +The storage write speed used by the build container\. +Units: Bytes/second +Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum + ## CodeBuild CloudWatch dimensions - `ProjectName` is the only AWS CodeBuild metrics dimension\. If it is specified, then the metrics are for that project\. If it is not specified, then the metrics are for the current AWS account\. +CodeBuild provides the following CloudWatch metric dimensions\. If none of these are specified, the metrics are for the current AWS account\. + +BuildId, BuildNumber, ProjectName +Metrics are provided for a build identifier, build number, and project name\. + +ProjectName +Metrics are provided for a project name\. ## CodeBuild CloudWatch alarms You can use the CloudWatch console to create alarms based on CodeBuild metrics so you can react if something goes wrong with your builds\. The two metrics that are most useful with alarms are: -+ `FailedBuild`\. You can create an alarm that is triggered when a certain number of failed builds are detected within a predetermined number of seconds\. In CloudWatch you specify the number of seconds and how many faild builds trigger an alarm\. ++ `FailedBuild`\. You can create an alarm that is triggered when a certain number of failed builds are detected within a predetermined number of seconds\. In CloudWatch, you specify the number of seconds and how many failed builds trigger an alarm\. + `Duration`\. You can create an alarm that is triggered when a build takes longer than expected\. You specify how many seconds must elapse after a build is started and before a build is completed before the alarm is triggered\. For information about how to create alarms for CodeBuild metrics, see [Monitoring builds with CloudWatch alarms](monitoring-alarms.md)\. For more information about alarms, see [Creating Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/monitoring-metrics.md b/doc_source/monitoring-metrics.md index 8f768c2..54c47c0 100644 --- a/doc_source/monitoring-metrics.md +++ b/doc_source/monitoring-metrics.md @@ -1,18 +1,27 @@ -# Monitoring builds with CloudWatch metrics +# Monitoring CodeBuild metrics - CodeBuild monitors functions on your behalf and reports metrics through Amazon CloudWatch\. These metrics include the number of total builds, failed builds, successful builds, and the duration of builds\. + AWS CodeBuild monitors functions on your behalf and reports metrics through Amazon CloudWatch\. These metrics include the number of total builds, failed builds, successful builds, and the duration of builds\. You can use the CodeBuild console or the CloudWatch console to monitor metrics for CodeBuild\. The following procedures show you how to access metrics\. +**Topics** ++ [Access build metrics \(CodeBuild console\)](#metrics-in-codebuild-console) ++ [Access build metrics \(Amazon CloudWatch console\)](#metrics-in-cloudwatch-console) + ## Access build metrics \(CodeBuild console\) -The graphs in the CodeBuild console show three days of metrics\. You cannot customize the metrics or the graphs used to display them\. Use the Amazon CloudWatch console to view your build metrics if you want to edit them\. +**Note** +You can't customize the metrics or the graphs used to display them in the CodeBuild console\. If you want to customize the display, use the Amazon CloudWatch console to view your build metrics\. + +### Account\-level metrics -**To access AWS account level metrics** +**To access AWS account\-level metrics** 1. Sign in to the AWS Management Console and 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 **Account metrics**\. +1. In the navigation pane, choose **Account metrics**\. + +### Project\-level metrics **To access project\-level metrics** @@ -26,9 +35,11 @@ The graphs in the CodeBuild console show three days of metrics\. You cannot cust ## Access build metrics \(Amazon CloudWatch console\) - You can customize the metrics and the graphs used to display them\. +You can customize the metrics and the graphs used to display them with the CloudWatch console\. -**To access account level metrics** +### Account\-level metrics + +**To access account\-level metrics** 1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. @@ -39,7 +50,9 @@ The graphs in the CodeBuild console show three days of metrics\. You cannot cust 1. Choose **Account Metrics**\. -1. Choose one or more projects and metrics\. For each project, you can choose the **SucceededBuilds**, **FailedBuilds**, **Builds**, and **Duration** metrics\. All selected project and metric combinations are displayed in the graph on the page\. +1. Choose one or more projects and metrics\. For each project, you can choose the **SucceededBuilds**, **FailedBuilds**, **Builds**, and **Duration** metrics\. All selected project and metric combinations are displayed in the graph on the page\. + +### Project\-level metrics **To access project\-level metrics** @@ -54,4 +67,6 @@ The graphs in the CodeBuild console show three days of metrics\. You cannot cust 1. Choose one or more project and metric combinations\. For each project, you can choose the **SucceededBuilds**, **FailedBuilds**, **Builds**, and **Duration** metrics\. All selected project and metric combinations are displayed in the graph on the page\. -1. \(Optional\) You can customize your metrics and graphs\. For example, from the drop\-down list in the **Statistic** columm, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. For more information, see [Graph metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [View available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file +1. \(Optional\) You can customize your metrics and graphs\. For example, from the drop\-down list in the **Statistic** column, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. + + For more information, see [Graph metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [View available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/monitoring-utilization-metrics.md b/doc_source/monitoring-utilization-metrics.md new file mode 100644 index 0000000..a5eb08a --- /dev/null +++ b/doc_source/monitoring-utilization-metrics.md @@ -0,0 +1,102 @@ +# Monitoring CodeBuild resource utilization metrics + +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 available in the following regions: +Asia Pacific \(Tokyo\) Region +Asia Pacific \(Seoul\) Region +Asia Pacific \(Mumbai\) Region +Asia Pacific \(Singapore\) Region +Asia Pacific \(Sydney\) Region +Canada \(Central\) Region +Europe \(Frankfurt\) Region +Europe \(Ireland\) Region +Europe \(London\) Region +Europe \(Paris\) Region +South America \(São Paulo\) Region +US East \(N\. Virginia\) Region +US East \(Ohio\) Region +US West \(N\. California\) Region +US West \(Oregon\) Region + +**Topics** ++ [Access resource utilization metrics \(CodeBuild console\)](#utilization-metrics-codebuild-console) ++ [Access resource utilization metrics \(Amazon CloudWatch console\)](#utilization-metrics-cloudwatch-console) + +## Access resource utilization metrics \(CodeBuild console\) + +**Note** +You can't customize the metrics or the graphs used to display them in the CodeBuild console\. If you want to customize the display, use the Amazon CloudWatch console to view your build metrics\. + +### Project\-level resource utilization metrics + +**To access project\-level resource utilization metrics** + +1. Sign in to the AWS Management Console and 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. In the list of build projects, in the **Name** column, choose the project you want to view the utilization metrics for\. + +1. Choose the **Metrics** tab\. The resource utilization metrics are displayed in the **Resource utilization metrics** section\. + +1. To view the project\-level resource utilization metrics in the CloudWatch console, choose **View in CloudWatch** in the **Resource utilization metrics** section\. + +### Build\-level resource utilization metrics + +**To access build\-level resource utilization metrics** + +1. Sign in to the AWS Management Console and 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 history**\. + +1. In the list of builds, in the **Build run** column, choose the build you want to view the utilization metrics for\. + +1. Choose the **Resource utilization** tab\. + +1. To view the build\-level resource utilization metrics in the CloudWatch console, choose **View in CloudWatch** in the **Resource utilization metrics** section\. + +## Access resource utilization metrics \(Amazon CloudWatch console\) + +The Amazon CloudWatch console can be used to access CodeBuild resource utilization metrics\. + +### Project\-level resource utilization metrics + +**To access project\-level resource utilization metrics** + +1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. + +1. In the navigation pane, choose **Metrics**\. + +1. On the **All metrics** tab, choose **CodeBuild**\. +![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +1. Choose **By Project**\. + +1. Choose one or more project and metric combinations to add to the graph\. All selected project and metric combinations are displayed in the graph on the page\. + +1. \(Optional\) You can customize your metrics and graphs from the **Graphed metrics** tab\. For example, from the drop\-down list in the **Statistic** column, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. + + For more information, see [Graphing metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [Viewing available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. + +### Build\-level resource utilization metrics + +**To access build\-level resource utilization metrics** + +1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. + +1. In the navigation pane, choose **Metrics**\. + +1. On the **All metrics** tab, choose **CodeBuild**\. +![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +1. Choose **BuildId, BuildNumber, ProjectName**\. + +1. Choose one or more build and metric combinations to add to the graph\. All selected build and metric combinations are displayed in the graph on the page\. + +1. \(Optional\) You can customize your metrics and graphs from the **Graphed metrics** tab\. For example, from the drop\-down list in the **Statistic** column, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. + + For more information, see [Graphing metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [Viewing available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/run-build.md b/doc_source/run-build.md index d372b90..79916cc 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -76,7 +76,9 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 1. Expand **Environment variables override**\. - If you want to change the environment variables for this build only, change the values for **Name**, **Value**, and **Type**\. Choose **Add environment variable** to add a new environment variable for this build only\. Choose **Remove environment variable** to remove an environment variable you do not want to use in this build\. + 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**\. diff --git a/doc_source/security.md b/doc_source/security.md index 0e15889..6d42c9f 100644 --- a/doc_source/security.md +++ b/doc_source/security.md @@ -9,7 +9,6 @@ To learn how to secure your CodeBuild resources, see the following topics\. **Topics** + [Data protection in AWS CodeBuild](data-protection.md) + [Identity and access management in AWS CodeBuild](auth-and-access-control.md) -+ [Logging and monitoring in AWS CodeBuild](security-incident-response.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 diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 1c22dce..3767a93 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting AWS CodeBuild -Use the information in this topic to help you identify, diagnose, and address issues\. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see [Logging and monitoring](security-incident-response.md)\. +Use the information in this topic to help you identify, diagnose, and address issues\. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see [Logging and monitoring](logging-monitoring.md)\. **Topics** + [Apache Maven builds reference artifacts from the wrong repository](#troubleshooting-maven-repos) From 495568780838328060fc2ae0bf076f0a3f98d370 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 1 Jul 2020 14:01:32 -0700 Subject: [PATCH 054/156] Add configurable build status --- doc_source/create-project.md | 23 ++++++++++++++++++++++- doc_source/vpc-support.md | 4 +++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/doc_source/create-project.md b/doc_source/create-project.md index 34755e4..2deec76 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -49,7 +49,7 @@ CodeBuild does not support Bitbucket Server\. 1. For **Source identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. - 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. For **Source provider**, choose the source cod380e provider type\. Use the table earlier in this step to make selections appropriate for your secondary source provider\. 1. In **Environment**: @@ -216,6 +216,10 @@ For information about using the AWS CLI with CodeBuild, see the [Command line re "buildspec": "buildspec", "InsecureSsl": "InsecureSsl", "reportBuildStatus": reportBuildStatus", + "buildStatusConfig": { + "context": context, + "targetUrl": target-url + }, "gitSubmodulesConfig": { "fetchSubmodules": "fetchSubmodules" }, @@ -373,6 +377,23 @@ For information about using the AWS CLI with CodeBuild, see the [Command line re + *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: diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index 93a8c07..c2fa849 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -65,7 +65,9 @@ Use this checklist when you set up a VPC to work with CodeBuild\. **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\. + Include multiple Availability Zones with your VPC\. -+ Make sure that your security groups have no inbound \(ingress\) traffic allowed to your builds\. For more information, see [Security groups rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*\. ++ 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\. + + For more information, see [Security groups rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*\. + Set up separate subnets for your builds\. + When you set up your CodeBuild projects to access your VPC, choose private subnets only\. From 5d57a45361ef434d4c1960eeb040780d792b49b8 Mon Sep 17 00:00:00 2001 From: Jordi Funollet Date: Mon, 6 Jul 2020 12:07:59 +0200 Subject: [PATCH 055/156] Fix wrong name for parameter git-credential-helper --- doc_source/build-spec-ref.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index e4635d0..9f761ea 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -199,7 +199,7 @@ Optional mapping\. Used to list environment variables you want to export\. Speci + Secrets Manager secrets specified in the build project + Environment variables that start with `AWS_`\. -env/**git\-credential\-help** +env/**git\-credential\-helper** Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. @@ -569,4 +569,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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From 438a8d3ea5decf4a5ebc618547a52c2cfca8f85b Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 13 Jul 2020 13:30:25 -0700 Subject: [PATCH 056/156] General update --- doc_source/build-caching.md | 6 +- doc_source/build-env-ref-available.md | 4 +- doc_source/build-env-ref-cmd.md | 2 +- doc_source/build-env-ref-compute-types.md | 4 +- doc_source/build-spec-ref.md | 4 +- doc_source/change-project.md | 6 +- doc_source/cmd-ref.md | 2 +- doc_source/create-project-cli.md | 427 ++++++++++++ doc_source/create-project-cloud-formation.md | 3 + doc_source/create-project-console.md | 295 +++++++++ doc_source/create-project-sdks.md | 3 + doc_source/create-project.md | 626 +----------------- ...etting-started-cli-create-build-project.md | 2 +- doc_source/how-to-create-pipeline.md | 6 +- doc_source/how-to-run.md | 2 +- doc_source/how-to-tag-project-add.md | 2 +- doc_source/index.md | 4 + doc_source/jenkins-plugin.md | 2 +- doc_source/project-sharing.md | 4 +- doc_source/run-build.md | 6 +- doc_source/sample-access-tokens.md | 4 +- doc_source/sample-bitbucket-pull-request.md | 4 +- doc_source/sample-build-badges.md | 2 +- .../sample-buildspec-artifact-naming.md | 4 +- doc_source/sample-efs.md | 7 +- doc_source/sample-elastic-beanstalk.md | 4 +- doc_source/sample-github-pull-request.md | 2 +- doc_source/sample-multi-in-out.md | 2 +- doc_source/sample-private-registry.md | 2 +- doc_source/sample-runtime-versions.md | 6 +- doc_source/sample-source-version.md | 2 +- doc_source/security-encryption.md | 2 +- doc_source/setting-up.md | 2 +- doc_source/view-project-details.md | 2 +- doc_source/vpc-support.md | 4 +- 35 files changed, 784 insertions(+), 675 deletions(-) create mode 100644 doc_source/create-project-cli.md create mode 100644 doc_source/create-project-cloud-formation.md create mode 100644 doc_source/create-project-console.md create mode 100644 doc_source/create-project-sdks.md diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 39ac4e1..230181e 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -58,7 +58,7 @@ The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_G --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE] ``` -For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. +For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. ### Specify local caching \(console\) @@ -66,7 +66,7 @@ You specify a cache in the **Artifacts** section of the console\. For **Cache ty ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.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 build project \(console\)](create-project.md#create-project-console)\. +For more information, see [Create a build project \(console\)](create-project-console.md)\. ### Specify local caching \(AWS CloudFormation\) @@ -109,4 +109,4 @@ CodeBuildProject: **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\. -For more information, see [Create a build project \(AWS CloudFormation\)](create-project.md#create-project-cloud-formation)\. \ No newline at end of file +For more information, see [Create a build project \(AWS CloudFormation\)](create-project-cloud-formation.md)\. \ No newline at end of file diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 88cf0fa..7898b92 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -3,8 +3,6 @@ AWS CodeBuild manages the following Docker images that are available in the CodeBuild and AWS CodePipeline consoles\. -**** - | 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) | @@ -49,7 +47,7 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the 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)\. 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.md#create-project-console) 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.md#change-project-console)\. + For the AWS CLI, run the `list-curated-environment-images` command: ``` diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index 54a3197..c9ee186 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.md @@ -2,7 +2,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.md#create-project-console)\. ++ 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 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)\. diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index b1bff7f..1dc6e38 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -35,8 +35,8 @@ For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncomp 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.md#create-project-console) 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.md#create-project-cli) or [Change a build project's settings \(AWS CLI\)](change-project.md#change-project-cli)\. ++ 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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index e4635d0..d1dcfb6 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -199,7 +199,7 @@ Optional mapping\. Used to list environment variables you want to export\. Speci + Secrets Manager secrets specified in the build project + Environment variables that start with `AWS_`\. -env/**git\-credential\-help** +env/**git\-credential\-helper** Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. @@ -316,7 +316,7 @@ 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.md#create-project-console)\. ++ 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\. diff --git a/doc_source/change-project.md b/doc_source/change-project.md index 9608ae7..b4352f5 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -23,7 +23,7 @@ If you add test reporting to a build project, make sure your IAM role has the pe Choose **Update configuration**\. - For more information about settings referred to in this procedure, see [Create a build project \(console\)](create-project.md#create-project-console)\. + 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** @@ -131,7 +131,7 @@ For information about using the AWS CLI with AWS CodeBuild, see the [Command lin 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.md#create-project-cli), and save your results\. + 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\. @@ -141,7 +141,7 @@ In the JSON\-formatted data, you must provide the name of the build project\. Al 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.md#create-project-cli) appears in the output\. +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\) diff --git a/doc_source/cmd-ref.md b/doc_source/cmd-ref.md index bc66842..4460126 100644 --- a/doc_source/cmd-ref.md +++ b/doc_source/cmd-ref.md @@ -24,7 +24,7 @@ CodeBuild commands include: + `batch-delete-builds`: Deletes one or more builds in CodeBuild\. For more information, see [Delete builds \(AWS CLI\)](delete-builds.md#delete-builds-cli)\. + `batch-get-builds`: Gets information about multiple builds in CodeBuild\. For more information, see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. + `batch-get-projects`: Gets information about one or more specified build projects\. For more information, see [View a build project's details \(AWS CLI\)](view-project-details.md#view-project-details-cli)\. -+ `create-project`: Creates a build project\. For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. ++ `create-project`: Creates a build project\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. + `delete-project`: Deletes a build project\. For more information, see [Delete a build project \(AWS CLI\)](delete-project.md#delete-project-cli)\. + `list-builds`: Lists Amazon Resource Names \(ARNs\) for builds in CodeBuild\. For more information, see [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-build-list-cli)\. + `list-builds-for-project`: Gets a list of build IDs that are associated with a specified build project\. For more information, see [View a list of build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli)\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md new file mode 100644 index 0000000..f082957 --- /dev/null +++ b/doc_source/create-project-cli.md @@ -0,0 +1,427 @@ +# 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` + + *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** +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 *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** +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** +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)\. + +To start running a build, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. + +If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start running builds automatically \(AWS CLI\)](run-build.md#run-build-cli-auto-start)\. \ No newline at end of file diff --git a/doc_source/create-project-cloud-formation.md b/doc_source/create-project-cloud-formation.md new file mode 100644 index 0000000..44ef2eb --- /dev/null +++ b/doc_source/create-project-cloud-formation.md @@ -0,0 +1,3 @@ +# Create a build project \(AWS CloudFormation\) + +For information about using AWS CodeBuild with AWS CloudFormation, see [the AWS CloudFormation template for CodeBuild](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-project.html) in the *AWS CloudFormation User Guide*\. \ No newline at end of file diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md new file mode 100644 index 0000000..99ade27 --- /dev/null +++ b/doc_source/create-project-console.md @@ -0,0 +1,295 @@ +# 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)\. + +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. In **Project configuration**: + + 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\. + + In **Description**, enter an optional description for your project\. + + 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\. + + Expand **Additional configuration**\. + + \(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. In **Source**: + + For **Source provider**, choose the source code provider type\. Use the following lists to make selections appropriate for your source provider: +**Note** +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**\. + + **Use Git submodules** +Select 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**\. + + **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\. + + 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\. + + 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)\. + +------ +#### [ 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**\. + + **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\. + + 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)\. + +------ +#### [ 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**\. + + **Use Git submodules** +Select 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\. +The status of a build triggered by a webhook is always reported to your source provider\. + + **Insecure SSL** +Choose 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)\. + +------ + + For each secondary source you want: + + 1. Choose **Add source**\. + + 1. For **Source identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. + + 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** +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** +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** +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. 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\. +**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\. 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 diff --git a/doc_source/create-project-sdks.md b/doc_source/create-project-sdks.md new file mode 100644 index 0000000..7154f72 --- /dev/null +++ b/doc_source/create-project-sdks.md @@ -0,0 +1,3 @@ +# Create a build project \(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/create-project.md b/doc_source/create-project.md index 2deec76..946c843 100644 --- a/doc_source/create-project.md +++ b/doc_source/create-project.md @@ -4,627 +4,11 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to create a build pr **Topics** + [Prerequisites](#create-project-prerequisites) -+ [Create a build project \(console\)](#create-project-console) -+ [Create a build project \(AWS CLI\)](#create-project-cli) -+ [Create a build project \(AWS SDKs\)](#create-project-sdks) -+ [Create a build project \(AWS CloudFormation\)](#create-project-cloud-formation) ++ [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)\. - -## 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)\. - -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. In **Project configuration**: - - 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\. - - In **Description**, enter an optional description for your project\. - - 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\. - - Expand **Additional configuration**\. - - \(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. In **Source**: - - For **Source provider**, choose the source code provider type\. Use the following table to make selections appropriate for your source provider: -**Note** -CodeBuild does not support Bitbucket Server\. -**** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html) - - For each secondary source you want: - - 1. Choose **Add source**\. - - 1. For **Source identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. - - 1. For **Source provider**, choose the source cod380e 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** -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 name of a directory in your build container that mounts the file system\. 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** -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** -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. 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\. -**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\. 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**\. - -## 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 artifiact 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 name of a directory in your build container that mounts the file system\. 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` - + *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** -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 *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** -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** -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)\. - -To start running a build, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. - -If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start running builds automatically \(AWS CLI\)](run-build.md#run-build-cli-auto-start)\. - -## Create a build project \(AWS SDKs\) - -For information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. - -## Create a build project \(AWS CloudFormation\) - -For information about using AWS CodeBuild with AWS CloudFormation, see [the AWS CloudFormation template for CodeBuild](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-project.html) in the *AWS CloudFormation User Guide*\. \ No newline at end of file +Answer the questions in [Plan a build](planning.md)\. \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index b0fda7f..b988cd7 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -52,7 +52,7 @@ For this build environment, you instruct CodeBuild to use a Docker image that co 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`\)\. **Note** -Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this tutorial, so they are not shown here\. For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. +Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this tutorial, so they are not shown here\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. 1. Switch to the directory that contains the file you just saved, and then run the create\-project command again\. diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 8498b52..529cfa2 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -127,7 +127,7 @@ This is not the source bucket for your pipeline's source code\. This is the arti 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.md#create-project-console) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. + 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)\. @@ -167,7 +167,7 @@ To use the AWS CLI to create a pipeline that deploys your built source code or t 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.md#create-project-cli)\. +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*\. @@ -371,7 +371,7 @@ This procedure shows you how to add the build action inside of a build stage\. T 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.md#create-project-console) or [Change a build project's settings \(console\)](change-project.md#change-project-console)\. + 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) diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md index 9ed9f28..f393415 100644 --- a/doc_source/how-to-run.md +++ b/doc_source/how-to-run.md @@ -14,7 +14,7 @@ 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.md#create-project-console)\. To use the AWS CLI, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. +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. Run the build\. To use the console, see [Run a build \(console\)](run-build.md#run-build-console)\. To use the AWS CLI, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. diff --git a/doc_source/how-to-tag-project-add.md b/doc_source/how-to-tag-project-add.md index 4a7ba68..cc2c6b5 100644 --- a/doc_source/how-to-tag-project-add.md +++ b/doc_source/how-to-tag-project-add.md @@ -31,7 +31,7 @@ You can use the CodeBuild console to add one or more tags to a CodeBuild project ## Add a tag to a project \(AWS CLI\) -To add a tag to a project when you create it, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. In `create-project.json`, add your tags\. +To add a tag to a project when you create it, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. In `create-project.json`, add your tags\. In these steps, we assume that you have already installed a recent version of the AWS CLI or updated to the current version\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)\. diff --git a/doc_source/index.md b/doc_source/index.md index 0721e5a..89197e3 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -86,6 +86,10 @@ Amazon's trademarks and trade dress may not be used in + [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) + + [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) + [Create a notification rule](notification-rule-create.md) + [View a list of build project names in AWS CodeBuild](view-project-list.md) + [View a build project's details in AWS CodeBuild](view-project-details.md) diff --git a/doc_source/jenkins-plugin.md b/doc_source/jenkins-plugin.md index 4e562e7..5b11bcf 100644 --- a/doc_source/jenkins-plugin.md +++ b/doc_source/jenkins-plugin.md @@ -14,7 +14,7 @@ If you already have a Jenkins server set up and would like to only install the A **To use AWS CodeBuild with sources from outside of a VPC** -1. Create a project in the CodeBuild console\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console)\. +1. Create a project in the CodeBuild console\. For more information, see [Create a build project \(console\)](create-project-console.md)\. + Choose the AWS Region where you want to run the build\. + \(Optional\) Set the Amazon VPC configuration to allow the CodeBuild build container to access resources in your VPC\. + Write down the name of your project\. You need it in step 3\. diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index 6aaaaf3..a74b63d 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -4,7 +4,7 @@ Project sharing allows project owners to share their AWS CodeBuild projects with **Topics** + [Prerequisites for sharing projects](#project-sharing-prereqs) -+ [Prerequisites for accessing shared projects shared with you](#project-sharing-access-prereqs) ++ [Prerequisites for accessing shared projects](#project-sharing-access-prereqs) + [Related services](#project-sharing-related) + [Sharing a project](#project-sharing-share) + [Unsharing a shared project](#project-sharing-unshare) @@ -41,7 +41,7 @@ For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ ## Sharing a project -The consumer can use the AWS CLI but not the AWS CodeBuild console to view the project and builds you've shared\. The consumer cannot edit or run the project\. +The consumer can use both the AWS CLI and AWS CodeBuild console to view the project and builds you've shared\. The consumer cannot edit or run the project\. You can add a project to an existing resource share or you can create one in the [AWS RAM console](https://console.aws.amazon.com/ram)\. diff --git a/doc_source/run-build.md b/doc_source/run-build.md index 79916cc..db3156e 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -24,7 +24,7 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll + 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.md#create-project-source-provider)\. + + 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. Choose **Advanced build overrides**\. @@ -62,7 +62,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + 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.md#create-project-console)\. + + 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**: @@ -210,7 +210,7 @@ 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 file declaration takes lowest precedence\. - For information about valid values for these placeholders, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. For a list of the latest settings for a build project, see [View a build project's details](view-project-details.md)\. + For information about valid values for these placeholders, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. For a list of the latest settings for a build project, see [View a build project's details](view-project-details.md)\. 1. Switch to the directory that contains the file you just saved, and run the `start-build` command again\. diff --git a/doc_source/sample-access-tokens.md b/doc_source/sample-access-tokens.md index 2001b64..6cbfb24 100644 --- a/doc_source/sample-access-tokens.md +++ b/doc_source/sample-access-tokens.md @@ -22,7 +22,7 @@ For more information, see [Scopes for Bitbucket Cloud REST API](https://develope ## 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.md#create-project-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: @@ -95,7 +95,7 @@ Follow these steps to use the AWS CLI to connect your project to GitHub or Bitbu **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.md#create-project-cli)\. + 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\. diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index a1b5218..15f946c 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -40,7 +40,7 @@ CodeBuild does not support Bitbucket Server\. 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.md#create-project-source-provider)\. +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\. @@ -105,7 +105,7 @@ You must enable the `merged` event in your Bitbucket webhook setting if you crea 1. Choose **Add filter group** to add another filter group\. - For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. + 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: diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 51aa962..33d0546 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -51,7 +51,7 @@ When you use the console to create or update a build project, you can create a C ## Create a build project with build badges enabled \(CLI\) -For information about creating a build project, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. To include build badges with your AWS CodeBuild project, you must specify *badgeEnabled* with a value of `true`\. +For information about creating a build project, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. To include build badges with your AWS CodeBuild project, you must specify *badgeEnabled* with a value of `true`\. ## Access your AWS CodeBuild build badges diff --git a/doc_source/sample-buildspec-artifact-naming.md b/doc_source/sample-buildspec-artifact-naming.md index 4869ad3..a8a2bd7 100644 --- a/doc_source/sample-buildspec-artifact-naming.md +++ b/doc_source/sample-buildspec-artifact-naming.md @@ -7,8 +7,8 @@ If you want to override the artifact name you entered in the console with a name in the buildspec file, do the following: 1. Set your build project to override the artifact name with a name in the buildspec file\. - + If you use the console to create your build project, select **Enable semantic versioning**\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console)\. - + If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON\-formatted file passed to `create-project`\. For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. + + If you use the console to create your build project, select **Enable semantic versioning**\. For more information, see [Create a build project \(console\)](create-project-console.md)\. + + If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON\-formatted file passed to `create-project`\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. + If you use the AWS CodeBuild API, set the `overrideArtifactName` flag on the `ProjectArtifacts` object when a project is created or updated or a build is started\. 1. Specify a name in the buildspec file\. Use the following sample buildspec files as a guide\. diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 603748a..4cdf1ad 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -71,7 +71,7 @@ Data in transit for your file system is encrypted\. To encrypt data in transit u 1. From **Source provider**, choose the repository that contains the Java application you want to build\. -1. Enter information, such as a repository URL, that CodeBuild uses to locate your application\. The options are different for each source provider\. For more information, see [Choose source provider](create-project.md#create-project-source-provider)\. +1. Enter information, such as a repository URL, that CodeBuild uses to locate your application\. The options are different for each source provider\. For more information, see [Choose source provider](create-project-console.md#create-project-source-provider)\. 1. From **Environment image**, choose **Managed image**\. @@ -98,11 +98,6 @@ 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 name of a directory in your build container that mounts the file system\. 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**\. diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 202fd71..05672dc 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -105,7 +105,7 @@ In this step, you use the AWS CodeBuild console to create a build project and th Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. This must be the same Region where your S3 output bucket is stored\. -1. Create a build project and then run a build\. For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project and then run a build\. For more information, see [Create a build project \(console\)](create-project-console.md) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -190,7 +190,7 @@ In this step, you create an AWS CodeBuild build project to use with your pipelin 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.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index e9f3e16..3109040 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -112,7 +112,7 @@ When you use the console to create or update a build project, you can create a C 1. Choose **Add filter group** to add another filter group\. - For more information, see [Create a build project \(console\)](create-project.md#create-project-console) and [WebhookFilter](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_WebhookFilter.html) in the *AWS CodeBuild API Reference*\. + 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: diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index 455d322..c39dfaf 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -135,6 +135,6 @@ artifacts: } ``` -For more information, see [Create a build project \(AWS CLI\)](create-project.md#create-project-cli)\. +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 diff --git a/doc_source/sample-private-registry.md b/doc_source/sample-private-registry.md index e27aa47..57b73d8 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -45,7 +45,7 @@ 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/) -1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project.md#create-project-console)\. +1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. **Note** If your private registry is in your VPC, it must have public internet access\. CodeBuild cannot pull an image from a private IP address in a VPC\. diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 38d04ca..5a482c9 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -109,7 +109,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 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.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -175,7 +175,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h 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.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Source provider**, choose **GitHub**\. + For **Repository**, choose **Public repository**\. @@ -328,7 +328,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h 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.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. + For **Environment**: + For **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index ed66719..a9bc1b9 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -26,7 +26,7 @@ To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git 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 information, see [Create a build project \(console\)](create-project.md#create-project-console) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings: +1. Create a build project\. For information, see [Create a build project \(console\)](create-project-console.md) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings: + In **Source**: + For **Source provider**, choose **GitHub**\. If you are not connected to GitHub, follow the instructions to connect\. + For **Repository**, choose **Public repository**\. diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index af5ab1f..0857140 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -3,7 +3,7 @@ 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.md#encryptionkey-console) and [Set the Encryption Key Using the CLI](create-project.md#encryptionkey-cli)\. + + 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)\. 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/)\. diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index d9820ea..493b9c1 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -218,7 +218,7 @@ This policy allows access to all CodeBuild actions and to a potentially large nu ## Create a CodeBuild service role 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.md#create-project-console) ++ [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) diff --git a/doc_source/view-project-details.md b/doc_source/view-project-details.md index fbe1f81..4738c9f 100644 --- a/doc_source/view-project-details.md +++ b/doc_source/view-project-details.md @@ -58,7 +58,7 @@ 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.md#create-project-cli)\. +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)\. For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index c2fa849..7f49830 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -33,9 +33,9 @@ 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.md#create-project-console)\. When you create or change your CodeBuild project, in **VPC**, choose your VPC ID, subnets, and security groups\. +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.md#create-project-cli)\. 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)\. +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*\. + *vpcId*: Required\. The VPC ID that CodeBuild uses\. Run this command to get a list of all Amazon VPC IDs in your Region: From 4538af3efba7a50439ed322506c8c6aa15fb3299 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 17 Jul 2020 07:57:58 -0700 Subject: [PATCH 057/156] General update --- doc_source/build-spec-ref.md | 8 ++-- doc_source/jenkins-plugin.md | 66 +++++++++++++++---------------- doc_source/project-sharing.md | 66 +++++++++++++++++-------------- doc_source/sample-efs.md | 5 +++ doc_source/use-codebuild-agent.md | 2 +- 5 files changed, 79 insertions(+), 68 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 01cffab..862197b 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -446,7 +446,7 @@ artifacts: secondary-artifacts: artifact1: files: - - directory/file + - directory/file1 name: secondary-artifact-name-1 artifact2: files: @@ -529,11 +529,11 @@ artifacts: secondary-artifacts: artifact1: files: - - target/messageUtil-1.0.jar + - target/artifact-1.0.jar discard-paths: yes artifact2: files: - - target/messageUtil-1.0.jar + - target/artifact-2.0.jar discard-paths: yes cache: paths: @@ -569,4 +569,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/jenkins-plugin.md b/doc_source/jenkins-plugin.md index 5b11bcf..d6d1413 100644 --- a/doc_source/jenkins-plugin.md +++ b/doc_source/jenkins-plugin.md @@ -4,7 +4,7 @@ You can use the Jenkins plugin for AWS CodeBuild to integrate CodeBuild with you ## Setting up Jenkins -For information about setting up Jenkins with the AWS CodeBuild plugin, see the [ Simplify your Jenkins builds with CodeBuild](https://aws.amazon.com/blogs/devops/simplify-your-jenkins-builds-with-aws-codebuild/) blog post on the AWS DevOps Blog\. You can download the CodeBuild Jenkins plugin from [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. +For information about setting up Jenkins with the AWS CodeBuild plugin, and to download the plugin source code, see [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. ## Installing the plugin @@ -25,38 +25,38 @@ If you already have a Jenkins server set up and would like to only install the A + Create a policy similar to the following and then attach the policy to your user\. ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Resource": ["arn:aws:logs:{{region}}:{{awsAccountId}}:log-group:/aws/codebuild/{{projectName}}:*"], - "Action": ["logs:GetLogEvents"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:s3:::{{inputBucket}}"], - "Action": ["s3:GetBucketVersioning"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:s3:::{{inputBucket}}/{{inputObject}}"], - "Action": ["s3:PutObject"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:s3:::{{outputBucket}}/*"], - "Action": ["s3:GetObject"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:codebuild:{{region}}:{{awsAccountId}}:project/{{projectName}}"], - "Action": ["codebuild:StartBuild", - "codebuild:BatchGetBuilds", - "codebuild:BatchGetProjects"] - } - ] - } + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Resource": ["arn:aws:logs:{{region}}:{{awsAccountId}}:log-group:/aws/codebuild/{{projectName}}:*"], + "Action": ["logs:GetLogEvents"] + }, + { + "Effect": "Allow", + "Resource": ["arn:aws:s3:::{{inputBucket}}"], + "Action": ["s3:GetBucketVersioning"] + }, + { + "Effect": "Allow", + "Resource": ["arn:aws:s3:::{{inputBucket}}/{{inputObject}}"], + "Action": ["s3:PutObject"] + }, + { + "Effect": "Allow", + "Resource": ["arn:aws:s3:::{{outputBucket}}/*"], + "Action": ["s3:GetObject"] + }, + { + "Effect": "Allow", + "Resource": ["arn:aws:codebuild:{{region}}:{{awsAccountId}}:project/{{projectName}}"], + "Action": ["codebuild:StartBuild", + "codebuild:BatchGetBuilds", + "codebuild:BatchGetProjects"] + } + ] + } ``` 1. Create a freestyle project in Jenkins\. diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index a74b63d..a5ae9dd 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -68,7 +68,7 @@ See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide **To share a project that you own \(AWS RAM command\)** Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. - **To share a project that you own \(CodeBuild command\)** + **To share a project that you own \(CodeBuild command\)** Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/put-resource-policy.html) command: @@ -76,48 +76,54 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference ``` { - "Version":"2012-10-17", - "Statement":[{ - "Effect":"Allow", - "Principal":{ - "AWS":"consumer-aws-account-id-or-user" - }, - "Action":[ - "codebuild:BatchGetProjects", - "codebuild:BatchGetBuilds", - "codebuild:ListBuildsForProject"], - "Resource":"arn-of-project-to-share" - }] - } + "Version":"2012-10-17", + "Statement":[{ + "Effect":"Allow", + "Principal":{ + "AWS":"consumer-aws-account-id-or-user" + }, + "Action":[ + "codebuild:BatchGetProjects", + "codebuild:BatchGetBuilds", + "codebuild:ListBuildsForProject"], + "Resource":"arn-of-project-to-share" + }] + } ``` 1. Update `policy.json` with the project ARN and identifiers to share it with\. The following example grants read\-only access to the root user for the AWS account identified by 123456789012\. ``` { - "Version":"2012-10-17", - "Statement":[{ - "Effect":"Allow", - "Principal":{ - "AWS": [ - "123456789012" - ] - }, - "Action":[ - "codebuild:BatchGetProjects", - "codebuild:BatchGetBuilds", - "codebuild:ListBuildsForProject"], - "Resource":"arn:aws:codebuild:us-west-2:123456789012:project/my-project" - }] - } + "Version":"2012-10-17", + "Statement":[{ + "Effect":"Allow", + "Principal":{ + "AWS": [ + "123456789012" + ] + }, + "Action":[ + "codebuild:BatchGetProjects", + "codebuild:BatchGetBuilds", + "codebuild:ListBuildsForProject"], + "Resource":"arn:aws:codebuild:us-west-2:123456789012:project/my-project" + }] + } ``` -1. Run the following command\. +1. Run the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/put-resource-policy.html) command\. ``` aws codebuild put-resource-policy --resource-arn project-arn --policy file://policy.json ``` +1. Run the AWS RAM [promote\-resource\-share\-created\-from\-policy](https://docs.aws.amazon.com/cli/latest/reference/ram/promote-resource-share-created-from-policy.html) command\. + + ``` + aws ram promote-resource-share-created-from-policy --resource-share-arn resourcearn: project-arn + ``` + ## Unsharing a shared project An unshared project, including its builds, can be accessed only by its owner\. If you unshare a project, any AWS account or user you previously shared it with cannot access the project or its builds\. diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 4cdf1ad..1ba07a4 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -98,6 +98,11 @@ 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*\. 1. For **Build specification**, choose **Insert build commands**, and then choose **Switch to editor**\. diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index d8177fc..9ac2176 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -16,7 +16,7 @@ codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] ``` - 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 `bd69dbcdc9b3da66fd93de0b6d45534086367d6b48d3536d0248a01a459fb7e4`\. You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + 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: ``` docker inspect amazon/aws-codebuild-local From 859e76533c7e63353001e674dc7f4fc0340a11f3 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 21 Jul 2020 08:51:31 -0700 Subject: [PATCH 058/156] Add new default branch information. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 32fd39f..e633d77 100644 --- a/README.md +++ b/README.md @@ -7,3 +7,10 @@ The open source version of the AWS CodeBuild docs. You can submit feedback & req The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file. 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 From 5ed62cb2833c538c07d9c7b24924f528ae1dcbe3 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 21 Jul 2020 08:51:59 -0700 Subject: [PATCH 059/156] Session manager update --- doc_source/build-env-ref-available.md | 21 ++++- doc_source/build-env-ref-cmd.md | 2 +- doc_source/build-env-ref-compute-types.md | 10 +-- doc_source/builds-working.md | 1 + doc_source/create-project-cli.md | 1 + doc_source/history.md | 6 +- doc_source/index.md | 1 + doc_source/run-build.md | 8 +- doc_source/sample-windows.md | 24 ++--- doc_source/session-manager.md | 104 ++++++++++++++++++++++ 10 files changed, 151 insertions(+), 27 deletions(-) create mode 100644 doc_source/session-manager.md diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 7898b92..09566ef 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -12,8 +12,9 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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 | +| Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | -¹ No longer maintained after June, 2020\. +¹ 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`\. @@ -28,7 +29,7 @@ AWS CodeBuild manages the following Docker images that are available in the Code **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\. +The base image of the Windows Server Core 2016 contains the following runtimes\. | Runtime name | Version in `windows-base:2.0` | @@ -41,8 +42,22 @@ The `aws/codebuild/amazonlinux2-aarch64-standard:1.0` image does not support the | 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\.3, 7\.4 | +| powershell | 7\.0\.2 | +| python | 3\.7, 3\.8 | +| ruby | 2\.7 | + **Note** - The base image of the Windows Server Core 2016 platform is available in the US East \(N\. Virginia\), US East \(Ohio\), US West \(Oregon\), and Europe \(Ireland\) regions only\. + 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)\. diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index c9ee186..93a3e4d 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.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 2016 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 1dc6e38..eba2a82 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -18,9 +18,9 @@ The disk space listed for each build environment is available only in the direct **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\)\. +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\. @@ -28,8 +28,8 @@ For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncomp | Compute type | computeType value | Memory | vCPUs | Disk space | Environment type | | --- | --- | --- | --- | --- | --- | -| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | WINDOWS\_CONTAINER | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | WINDOWS\_CONTAINER | +| 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 | **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\. diff --git a/doc_source/builds-working.md b/doc_source/builds-working.md index e3c4a1a..9a5102b 100644 --- a/doc_source/builds-working.md +++ b/doc_source/builds-working.md @@ -19,4 +19,5 @@ 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) ++ [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/create-project-cli.md b/doc_source/create-project-cli.md index f082957..e465baf 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -298,6 +298,7 @@ Docker layer cache mode is available for Linux only\. If you choose it, your pro + `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` diff --git a/doc_source/history.md b/doc_source/history.md index b35e512..9d1db50 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,11 +2,13 @@ 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: **May 29, 2020 ++ **Latest documentation update: **July 20, 2020 | Change | Description | Date | | --- |--- |--- | -| [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 | +| [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 | +| [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 | | [Support for test reporting](#history) | CodeBuild support for test reporting is now generally available\. | May 21, 2020 | diff --git a/doc_source/index.md b/doc_source/index.md index 89197e3..fe7466e 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -110,6 +110,7 @@ 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) + + [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) + [Create a test report](report-create.md) diff --git a/doc_source/run-build.md b/doc_source/run-build.md index db3156e..5b1eb2a 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -229,9 +229,9 @@ If your source code is stored in a GitHub or a GitHub Enterprise Server reposito Run the create\-webhookcommand as follows: ``` -aws codebuild create-webhook --project-name +aws codebuild create-webhook --project-name ``` -+ where *project\-name* is the name of the build project that contains the source code to be rebuilt\. ++ where ** is the name of the build project that contains the source code to be rebuilt\. For GitHub, information similar to the following appears in the output: @@ -261,9 +261,9 @@ If your source code is stored in a GitHub or a GitHub Enterprise Server reposito If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: ``` -aws codebuild delete-webhook --project-name +aws codebuild delete-webhook --project-name ``` -+ where *project\-name* is the name of the build project that contains the source code to be rebuilt\. ++ where ** is the name of the build project that contains the source code to be rebuilt\. If this command is successful, no information and no errors appear in the output\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index eeb1941..e35b951 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 2016, 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 executables file out of code written in C\#, 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)\. @@ -32,8 +32,8 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains "name": "windows-build-output-artifact.zip" }, "environment": { - "type": "WINDOWS_CONTAINER", - "image": "aws/codebuild/windows-base:1.0", + "type": "WINDOWS_SERVER_2019_CONTAINER", + "image": "aws/codebuild/windows-base:2019-1.0", "computeType": "BUILD_GENERAL1_MEDIUM" }, "serviceRole": "arn:aws:iam::account-ID:role/role-name", @@ -122,7 +122,7 @@ env: variables: SOLUTION: .\CSharpHelloWorld.sln PACKAGE_DIRECTORY: .\packages - DOTNET_FRAMEWORK: 4.6.2 + DOTNET_FRAMEWORK: 4.8 phases: build: @@ -166,7 +166,7 @@ EndGlobal - + ``` @@ -185,7 +185,7 @@ EndGlobal Properties CSharpHelloWorld CSharpHelloWorld - v4.6.2 + v4.8 512 true @@ -310,7 +310,7 @@ env: variables: SOLUTION: .\FSharpHelloWorld.sln PACKAGE_DIRECTORY: .\packages - DOTNET_FRAMEWORK: 4.6.2 + DOTNET_FRAMEWORK: 4.8 phases: build: @@ -354,7 +354,7 @@ EndGlobal - + ``` @@ -419,7 +419,7 @@ do Exe FSharpHelloWorld FSharpHelloWorld - v4.6.2 + v4.8 true 4.4.0.0 FSharpHelloWorld @@ -510,7 +510,7 @@ env: variables: SOLUTION: .\VBHelloWorld.sln PACKAGE_DIRECTORY: .\packages - DOTNET_FRAMEWORK: 4.6.2 + DOTNET_FRAMEWORK: 4.8 phases: build: @@ -554,7 +554,7 @@ EndGlobal - + ``` @@ -587,7 +587,7 @@ End Module VBHelloWorld 512 Console - v4.6.2 + v4.8 true diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md new file mode 100644 index 0000000..1e2928c --- /dev/null +++ b/doc_source/session-manager.md @@ -0,0 +1,104 @@ +# View a running build in Session Manager + +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\. + +**Topics** ++ [Prerequisites](#ssm.prerequisites) ++ [Pause the build](#ssm-pause-build) ++ [Start the build](#ssm-start-build) ++ [Connect to the build container](#ssm-connect) ++ [Resume the build](#ssm-resume-build) + +## Prerequisites + +To allow Session Manager to be used with the build session, you must enable session connection for the build\. There are two prerequisites: ++ CodeBuild Linux standard curated images already have the SSM agent installed and the SSM agent ContainerMode enabled\. + + 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. 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: + + ``` + { + "Effect": "Allow", + "Action": [ + "ssmmessages:CreateControlChannel", + "ssmmessages:CreateDataChannel", + "ssmmessages:OpenControlChannel", + "ssmmessages:OpenDataChannel" + ], + "Resource": "*" + } + ``` + + 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\. + +## Pause the build + +To pause the build, insert the codebuild\-breakpoint command in any of the build phases in your buildspec file\. The build will be paused at this point, which allows you to connect to the build container and view the container in its current state\. + +For example, add the following to the build phases in your buildspec file\. + +``` +phases: + pre_build: + commands: + - echo Entered the pre_build phase... + - echo "Hello World" > /tmp/hello-world + - codebuild-breakpoint +``` + +This code creates the `/tmp/hello-world` file and then pauses the build at this point\. + +## Start the build + +To allow Session Manager to be used with the build session, you must enable session connections for the build\. To do this, when starting the build, follow these steps: + +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**\. Choose the build project, and then choose **Start build**\. + +1. Choose **Advanced build overrides**\. + +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. 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\. + +## Connect to the build container + +You can connect to the build container in one of two ways: + +CodeBuild console +In a web browser, open the **AWS Session Manager** link to connect to the build container\. A terminal session opens that allows you to browse and control the build container\. + +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\. + + ``` + aws codebuild batch-get-builds --ids --region + ``` + +1. Copy the `sessionTarget` property value\. + +1. Use the following command to connect to the build container\. + + ``` + aws ssm start-session --target --region + ``` + +For this example, verify that the `/tmp/hello-world` file exists and contains the text `Hello World`\. + +## Resume the build + +After you finish examining the build container, issue the codebuild\-resume command from the container shell\. + +``` +$ codebuild-resume +``` \ No newline at end of file From 955109fbfca646e7d4a06888ee65549a8e298aac Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 21 Jul 2020 15:10:16 -0700 Subject: [PATCH 060/156] Update run build layout. --- doc_source/build-env-ref-available.md | 4 +- doc_source/cmd-ref.md | 2 +- doc_source/create-project-cli.md | 4 +- doc_source/history.md | 4 +- doc_source/how-to-run.md | 2 +- doc_source/index.md | 5 + doc_source/project-sharing.md | 42 +++- doc_source/run-build-cli-auto-start.md | 33 +++ doc_source/run-build-cli-auto-stop.md | 15 ++ doc_source/run-build-cli.md | 127 ++++++++++++ doc_source/run-build-console.md | 93 +++++++++ doc_source/run-build-sdks.md | 5 + doc_source/run-build.md | 277 +------------------------ doc_source/sample-elastic-beanstalk.md | 4 +- doc_source/sample-runtime-versions.md | 6 +- doc_source/sample-source-version.md | 2 +- doc_source/sample-windows.md | 6 +- 17 files changed, 333 insertions(+), 298 deletions(-) create mode 100644 doc_source/run-build-cli-auto-start.md create mode 100644 doc_source/run-build-cli-auto-stop.md create mode 100644 doc_source/run-build-cli.md create mode 100644 doc_source/run-build-console.md create mode 100644 doc_source/run-build-sdks.md diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 09566ef..ab8344c 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -51,9 +51,9 @@ The base image of the Windows Server Core 2019 contains the following runtimes\. | golang | 1\.14 | | nodejs | 12\.18 | | java | corretto11 | -| php | 7\.3, 7\.4 | +| php | 7\.4\.7 | | powershell | 7\.0\.2 | -| python | 3\.7, 3\.8 | +| python | 3\.8\.3 | | ruby | 2\.7 | **Note** diff --git a/doc_source/cmd-ref.md b/doc_source/cmd-ref.md index 4460126..3980b4a 100644 --- a/doc_source/cmd-ref.md +++ b/doc_source/cmd-ref.md @@ -30,6 +30,6 @@ CodeBuild commands include: + `list-builds-for-project`: Gets a list of build IDs that are associated with a specified build project\. For more information, see [View a list of build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli)\. + `list-curated-environment-images`: Gets a list of Docker images managed by CodeBuild that you can use for your builds\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. + `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.md#run-build-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 diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index e465baf..50c2853 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -423,6 +423,6 @@ By default, Docker containers do not allow access to any devices\. Privileged mo **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)\. -To start running a build, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. +To start running a build, see [Run a build \(AWS CLI\)](run-build-cli.md)\. -If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start running builds automatically \(AWS CLI\)](run-build.md#run-build-cli-auto-start)\. \ No newline at end of file +If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start running builds automatically \(AWS CLI\)](run-build-cli-auto-start.md)\. \ No newline at end of file diff --git a/doc_source/history.md b/doc_source/history.md index 9d1db50..e0706e2 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -52,7 +52,7 @@ 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.md#run-build-cli)\. | May 15, 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 | @@ -73,7 +73,7 @@ The following table describes important changes in each release of the *AWS Code | 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.md#run-build-console) or the `sourceVersion` value in [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. | June 6, 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 | diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md index f393415..49223b8 100644 --- a/doc_source/how-to-run.md +++ b/doc_source/how-to-run.md @@ -16,6 +16,6 @@ Answer the questions in [Plan a build](planning.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)\. -1. Run the build\. To use the console, see [Run a build \(console\)](run-build.md#run-build-console)\. To use the AWS CLI, see [Run a build \(AWS CLI\)](run-build.md#run-build-cli)\. +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. 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 diff --git a/doc_source/index.md b/doc_source/index.md index fe7466e..57f5042 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -106,6 +106,11 @@ Amazon's trademarks and trade dress may not be used in + [Remove a tag from a project](how-to-tag-project-delete.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) + + [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) + [View build details in AWS CodeBuild](view-build-details.md) + [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) diff --git a/doc_source/project-sharing.md b/doc_source/project-sharing.md index a5ae9dd..3fbf3a9 100644 --- a/doc_source/project-sharing.md +++ b/doc_source/project-sharing.md @@ -13,7 +13,7 @@ Project sharing allows project owners to share their AWS CodeBuild projects with ## Prerequisites for sharing projects - To share a project, your AWS account must own it\. You cannot share a project that has been shared with you\. +To share a project, your AWS account must own it\. You cannot share a project that has been shared with you\. ## Prerequisites for accessing shared projects shared with you @@ -46,7 +46,7 @@ The consumer can use both the AWS CLI and AWS CodeBuild console to view the proj You can add a project to an existing resource share or you can create one in the [AWS RAM console](https://console.aws.amazon.com/ram)\. **Note** - You cannot delete a project with builds that has been added to a resource share\. +You cannot delete a project with builds that has been added to a resource share\. To share a project with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. @@ -60,7 +60,7 @@ You can use the AWS CodeBuild console, AWS RAM console, or the AWS CLI to share **Note** By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. -1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a resource share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. +1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a resource share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. **To share a project that you own \(AWS RAM console\)** See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. @@ -68,11 +68,11 @@ See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide **To share a project that you own \(AWS RAM command\)** Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. - **To share a project that you own \(CodeBuild command\)** +**To share a project that you own \(CodeBuild command\)** 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\. ``` { @@ -80,13 +80,13 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference "Statement":[{ "Effect":"Allow", "Principal":{ - "AWS":"consumer-aws-account-id-or-user" + "AWS":"" }, "Action":[ "codebuild:BatchGetProjects", "codebuild:BatchGetBuilds", "codebuild:ListBuildsForProject"], - "Resource":"arn-of-project-to-share" + "Resource":"" }] } ``` @@ -115,13 +115,37 @@ Use the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference 1. Run the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/put-resource-policy.html) command\. ``` - aws codebuild put-resource-policy --resource-arn project-arn --policy file://policy.json + aws codebuild put-resource-policy --resource-arn --policy file://policy.json ``` +1. Get the AWS RAM resource share ARN\. + + ``` + aws ram list-resources --resource-owner SELF --resource-arns + ``` + + This will return a response similar to this: + + ``` + { + "resources": [ + { + "arn": "", + "type": "", + "resourceShareArn": "", + "creationTime": "", + "lastUpdatedTime": "" + } + ] + } + ``` + + From the response, copy the ** value to use in the next step\. + 1. Run the AWS RAM [promote\-resource\-share\-created\-from\-policy](https://docs.aws.amazon.com/cli/latest/reference/ram/promote-resource-share-created-from-policy.html) command\. ``` - aws ram promote-resource-share-created-from-policy --resource-share-arn resourcearn: project-arn + aws ram promote-resource-share-created-from-policy --resource-share-arn ``` ## Unsharing a shared project diff --git a/doc_source/run-build-cli-auto-start.md b/doc_source/run-build-cli-auto-start.md new file mode 100644 index 0000000..223a094 --- /dev/null +++ b/doc_source/run-build-cli-auto-start.md @@ -0,0 +1,33 @@ +# Start running builds automatically \(AWS CLI\) + +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: + +``` +aws codebuild create-webhook --project-name +``` + +** is the name of the build project that contains the source code to be rebuilt\. + +For GitHub, information similar to the following appears in the output: + +``` +{ + "webhook": { + "url": "" + } +} +``` + +** is the URL to the GitHub webhook\. + +For GitHub Enterprise Server, information similar to the following appears in the output: + +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) + +1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise Server\. + +1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored\. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. + +1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. \ No newline at end of file diff --git a/doc_source/run-build-cli-auto-stop.md b/doc_source/run-build-cli-auto-stop.md new file mode 100644 index 0000000..34433db --- /dev/null +++ b/doc_source/run-build-cli-auto-stop.md @@ -0,0 +1,15 @@ +# Stop running builds automatically \(AWS CLI\) + +If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start running builds automatically \(AWS CLI\)](run-build-cli-auto-start.md)\. + +If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: + +``` +aws codebuild delete-webhook --project-name +``` ++ where ** is the name of the build project that contains the source code to be rebuilt\. + +If this command is successful, no information and no errors appear in the output\. + +**Note** +This deletes the webhook from your CodeBuild project only\. You should also delete the webhook from your GitHub or GitHub Enterprise Server repository\. \ No newline at end of file diff --git a/doc_source/run-build-cli.md b/doc_source/run-build-cli.md new file mode 100644 index 0000000..33fb710 --- /dev/null +++ b/doc_source/run-build-cli.md @@ -0,0 +1,127 @@ +# 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)\. +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: + + ``` + aws codebuild start-build --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 --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 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 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: + + ``` + { + "projectName": "projectName", + "sourceVersion": "sourceVersion", + "artifactsOverride": { + "type": "type", + "location": "location", + "path": "path", + "namespaceType": "namespaceType", + "name": "artifactsOverride-name", + "packaging": "packaging" + }, + "buildspecOverride": "buildspecOverride", + "cacheOverride": { + "location": "cacheOverride-location", + "type": "cacheOverride-type" + }, + "certificateOverride": "certificateOverride", + "computeTypeOverride": "computeTypeOverride", + "environmentTypeOverride": "environmentTypeOverride", + "environmentVariablesOverride": { + "name": "environmentVariablesOverride-name", + "value": "environmentVariablesValue", + "type": "environmentVariablesOverride-type" + }, + "gitCloneDepthOverride": "gitCloneDepthOverride", + "imageOverride": "imageOverride", + "idempotencyToken": "idempotencyToken", + "insecureSslOverride": "insecureSslOverride", + "privilegedModeOverride": "privilegedModeOverride", + "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride", + "reportBuildStatusOverride": "reportBuildStatusOverride", + "timeoutInMinutesOverride": "timeoutInMinutesOverride", + "sourceAuthOverride": "sourceAuthOverride", + "sourceLocationOverride": "sourceLocationOverride", + "serviceRoleOverride": "serviceRoleOverride", + "sourceTypeOverride": "sourceTypeOverride" + } + ``` + + Replace the following placeholders: + + *projectName*: Required string\. The name of the build project to use for this build\. + + *sourceVersion*: Optional string\. A version of the source code to be built, as follows: + + For Amazon S3, the version ID that corresponds to the version of the input ZIP file you want to build\. If *sourceVersion* is not specified, then the latest version is used\. + + For CodeCommit, the commit ID that corresponds to the version of the source code you want to build\. If *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. \(You cannot specify a tag name for *sourceVersion*, but you can specify the tag's commit ID\.\) + + 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 *sourceVersion* is 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 *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. + + The following placeholders are for `artifactsOveride`\. + + *type*: Optional\. The build output artifact type that overrides for this build the one defined in the build project\. + + *location*: Optional\. The build output artifact location that overrides for this build the one defined in the build project\. + + *path*: Optional\. The build output artifact path that overrides for this build the one defined in the build project\. + + *namespaceType*: Optional\. The build output artifact path type that overrides for this build the one defined in the build project\. + + *name*: Optional\. The build output artifact name that overrides for this build the one defined in the build project\. + + *packaging*: Optional\. The build output artifact packaging type that overrides for this build the one defined in the build project\. + + *buildspecOverride*: Optional\. A buildspec declaration that overrides for this build the one defined in the build project\. 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 S3 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)\. + + The following placeholders are for `cacheOveride`\. + + *cacheOverride\-location*: Optional\. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `location` is required in a `ProjectCache` object\. + + *cacheOverride\-type*: Optional\. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `type` is required in a `ProjectCache` object\. + + *certificateOverride*: Optional\. The name of a certificate for this build that overrides the one specified in the build project\. + + *environmentTypeOverride*: Optional\. A container type for this build that overrides the one specified in the build project\. The current valid string is `LINUX_CONTAINER`\. + + The following placeholders are for `environmentVariablesOveride`\. + + *environmentVariablesOverride\-name*: Optional\. The name of an environment variable in the build project whose value you want to override for this build\. + + *environmentVariablesOverride\-type*: Optional\. The type of environment variable in the build project whose value you want to override for this build\. + + *environmentVariablesValue*: Optional\. The value of the environment variable defined in the build project that you want to override for this build\. + + *gitCloneDepthOverride*: Optional\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. + + *imageOverride*: Optional\. The name of an image for this build that overrides the one specified in the build project\. + + *idempotencyToken*: Optional\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 5 minutes after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. + + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project\. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise Server\. + + *privilegedModeOverride*: Optional boolean\. If set to true, the build overrides privileged mode in the build project\. + + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out\. Its minimum value is five minutes and its maximum value is 480 minutes \(eight hours\)\. + + *reportBuildStatusOverride*: Optional boolean that 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\. + + *sourceAuthOverride*: Optional string\. An authorization type for this build that overrides the one defined in the build project\. This override applies only if the build project's source is Bitbucket or GitHub\. + + *sourceLocationOverride*: Optional string\. A location that overrides for this build the source location for the one defined in the build project\. + + *serviceRoleOverride*: Optional string\. The name of a service role for this build that overrides the one specified in the build project\. + + *sourceTypeOverride*: Optional string\. A source input type for this build that overrides the source input defined in the build project\. Valid strings are `NO_SOURCE`, `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `S3`, `BITBUCKET`, and `GITHUB_ENTERPRISE`\. + + *timeoutInMinutesOverride*: Optional number\. The number of build timeout minutes that overrides for this build the one defined in the build project\. + + 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\. CodeBuild can use a parameter stored in Amazon EC2 Systems Manager Parameter Store only if that parameter's name starts 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\. However, if you use the Amazon EC2 Systems Manager Parameter Store console to create a parameter, you must start the parameter's name with `/CodeBuild/`, and you must set **Type** to **Secure String**\. For more information, see [AWS Systems Manager parameter store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.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 new 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\. + + 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 environment variable's 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 file declaration takes lowest precedence\. + + For information about valid values for these placeholders, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. For a list of the latest settings for a build project, see [View a build project's details](view-project-details.md)\. + +1. Switch to the directory that contains the file you just saved, and run the `start-build` command again\. + + ``` + aws codebuild start-build --cli-input-json file://start-build.json + ``` + +1. If successful, data similar to that described in the [To run the build](getting-started-cli-run-build.md#getting-started-run-build-cli) procedure appears in the output\. + +To work with detailed information about this build, make a note of the `id` value in the output, and then see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. \ No newline at end of file diff --git a/doc_source/run-build-console.md b/doc_source/run-build-console.md new file mode 100644 index 0000000..a4ff816 --- /dev/null +++ b/doc_source/run-build-console.md @@ -0,0 +1,93 @@ +# 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)\. + +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. 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. Choose **Advanced build overrides**\. + + Here you can change settings for this build only\. The settings in this section are optional\. + + 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\. + + 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\. + + 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\. + + 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 diff --git a/doc_source/run-build-sdks.md b/doc_source/run-build-sdks.md new file mode 100644 index 0000000..9a83f16 --- /dev/null +++ b/doc_source/run-build-sdks.md @@ -0,0 +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\. + +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 5b1eb2a..2f52ee8 100644 --- a/doc_source/run-build.md +++ b/doc_source/run-build.md @@ -3,275 +3,8 @@ You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to run a build in CodeBuild\. **Topics** -+ [Run a build \(console\)](#run-build-console) -+ [Run a build \(AWS CLI\)](#run-build-cli) -+ [Start running builds automatically \(AWS CLI\)](#run-build-cli-auto-start) -+ [Stop running builds automatically \(AWS CLI\)](#run-build-cli-auto-stop) -+ [Run a build \(AWS SDKs\)](#run-build-sdks) - -## 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)\. - -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. 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. Choose **Advanced build overrides**\. - - Here you can change settings for this build only\. The settings in this section are optional\. - - 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\. - - 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\. - - 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\. - - 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`\. -**Important** -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)\. - -## 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)\. -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: - - ``` - aws codebuild start-build --project-name 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 --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 command with the `--project-name` option, replace *project\-name* 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 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: - - ``` - { - "projectName": "projectName", - "sourceVersion": "sourceVersion", - "artifactsOverride": { - "type": "type", - "location": "location", - "path": "path", - "namespaceType": "namespaceType", - "name": "artifactsOverride-name", - "packaging": "packaging" - }, - "buildspecOverride": "buildspecOverride", - "cacheOverride": { - "location": "cacheOverride-location", - "type": "cacheOverride-type" - }, - "certificateOverride": "certificateOverride", - "computeTypeOverride": "computeTypeOverride", - "environmentTypeOverride": "environmentTypeOverride", - "environmentVariablesOverride": { - "name": "environmentVariablesOverride-name", - "value": "environmentVariablesValue", - "type": "environmentVariablesOverride-type" - }, - "gitCloneDepthOverride": "gitCloneDepthOverride", - "imageOverride": "imageOverride", - "idempotencyToken": "idempotencyToken", - "insecureSslOverride": "insecureSslOverride", - "privilegedModeOverride": "privilegedModeOverride", - "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride", - "reportBuildStatusOverride": "reportBuildStatusOverride", - "timeoutInMinutesOverride": "timeoutInMinutesOverride", - "sourceAuthOverride": "sourceAuthOverride", - "sourceLocationOverride": "sourceLocationOverride", - "serviceRoleOverride": "serviceRoleOverride", - "sourceTypeOverride": "sourceTypeOverride" - } - ``` - - Replace the following placeholders: - + *projectName*: Required string\. The name of the build project to use for this build\. - + *sourceVersion*: Optional string\. A version of the source code to be built, as follows: - + For Amazon S3, the version ID that corresponds to the version of the input ZIP file you want to build\. If *sourceVersion* is not specified, then the latest version is used\. - + For CodeCommit, the commit ID that corresponds to the version of the source code you want to build\. If *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. \(You cannot specify a tag name for *sourceVersion*, but you can specify the tag's commit ID\.\) - + 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 *sourceVersion* is 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 *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. - + The following placeholders are for `artifactsOveride`\. - + *type*: Optional\. The build output artifact type that overrides for this build the one defined in the build project\. - + *location*: Optional\. The build output artifact location that overrides for this build the one defined in the build project\. - + *path*: Optional\. The build output artifact path that overrides for this build the one defined in the build project\. - + *namespaceType*: Optional\. The build output artifact path type that overrides for this build the one defined in the build project\. - + *name*: Optional\. The build output artifact name that overrides for this build the one defined in the build project\. - + *packaging*: Optional\. The build output artifact packaging type that overrides for this build the one defined in the build project\. - + *buildspecOverride*: Optional\. A buildspec declaration that overrides for this build the one defined in the build project\. 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 S3 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)\. - + The following placeholders are for `cacheOveride`\. - + *cacheOverride\-location*: Optional\. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `location` is required in a `ProjectCache` object\. - + *cacheOverride\-type*: Optional\. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `type` is required in a `ProjectCache` object\. - + *certificateOverride*: Optional\. The name of a certificate for this build that overrides the one specified in the build project\. - + *environmentTypeOverride*: Optional\. A container type for this build that overrides the one specified in the build project\. The current valid string is `LINUX_CONTAINER`\. - + The following placeholders are for `environmentVariablesOveride`\. - + *environmentVariablesOverride\-name*: Optional\. The name of an environment variable in the build project whose value you want to override for this build\. - + *environmentVariablesOverride\-type*: Optional\. The type of environment variable in the build project whose value you want to override for this build\. - + *environmentVariablesValue*: Optional\. The value of the environment variable defined in the build project that you want to override for this build\. - + *gitCloneDepthOverride*: Optional\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. - + *imageOverride*: Optional\. The name of an image for this build that overrides the one specified in the build project\. - + *idempotencyToken*: Optional\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 5 minutes after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. - + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project\. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise Server\. - + *privilegedModeOverride*: Optional boolean\. If set to true, the build overrides privileged mode in the build project\. - + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out\. Its minimum value is five minutes and its maximum value is 480 minutes \(eight hours\)\. - + *reportBuildStatusOverride*: Optional boolean that 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\. - + *sourceAuthOverride*: Optional string\. An authorization type for this build that overrides the one defined in the build project\. This override applies only if the build project's source is Bitbucket or GitHub\. - + *sourceLocationOverride*: Optional string\. A location that overrides for this build the source location for the one defined in the build project\. - + *serviceRoleOverride*: Optional string\. The name of a service role for this build that overrides the one specified in the build project\. - + *sourceTypeOverride*: Optional string\. A source input type for this build that overrides the source input defined in the build project\. Valid strings are `NO_SOURCE`, `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `S3`, `BITBUCKET`, and `GITHUB_ENTERPRISE`\. - + *timeoutInMinutesOverride*: Optional number\. The number of build timeout minutes that overrides for this build the one defined in the build project\. -**Important** -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\. CodeBuild can use a parameter stored in Amazon EC2 Systems Manager Parameter Store only if that parameter's name starts 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\. However, if you use the Amazon EC2 Systems Manager Parameter Store console to create a parameter, you must start the parameter's name with `/CodeBuild/`, and you must set **Type** to **Secure String**\. For more information, see [AWS Systems Manager parameter store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.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 new 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\. -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 environment variable's 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 file declaration takes lowest precedence\. - - For information about valid values for these placeholders, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. For a list of the latest settings for a build project, see [View a build project's details](view-project-details.md)\. - -1. Switch to the directory that contains the file you just saved, and run the `start-build` command again\. - - ``` - aws codebuild start-build --cli-input-json file://start-build.json - ``` - -1. If successful, data similar to that described in the [To run the build](getting-started-cli-run-build.md#getting-started-run-build-cli) procedure appears in the output\. - -To work with detailed information about this build, make a note of the `id` value in the output, and then see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. - -## Start running builds automatically \(AWS CLI\) - -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: - -``` -aws codebuild create-webhook --project-name -``` -+ where ** is the name of the build project that contains the source code to be rebuilt\. - -For GitHub, information similar to the following appears in the output: - -``` -{ - "webhook": { - "url": "url" - } -} -``` -+ where *url* is the URL to the GitHub webhook\. - -For GitHub Enterprise Server, information similar to the following appears in the output: - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise Server\. - -1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored\. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. - -1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. - -## Stop running builds automatically \(AWS CLI\) - -If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start running builds automatically \(AWS CLI\)](#run-build-cli-auto-start)\. - -If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: - -``` -aws codebuild delete-webhook --project-name -``` -+ where ** is the name of the build project that contains the source code to be rebuilt\. - -If this command is successful, no information and no errors appear in the output\. - -**Note** -This deletes the webhook from your CodeBuild project only\. You should also delete the webhook from your GitHub or GitHub Enterprise Server repository\. - -## 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\. - -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 ++ [Run a build \(console\)](run-build-console.md) ++ [Run a build \(AWS CLI\)](run-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/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 05672dc..49e8aff 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -105,7 +105,7 @@ In this step, you use the AWS CodeBuild console to create a build project and th Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. This must be the same Region where your S3 output bucket is stored\. -1. Create a build project and then run a build\. For more information, see [Create a build project \(console\)](create-project-console.md) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +1. Create a build project and then run a build\. 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 **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -190,7 +190,7 @@ In this step, you create an AWS CodeBuild build project to use with your pipelin 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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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 **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 5a482c9..536f666 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -109,7 +109,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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 **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. @@ -175,7 +175,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h 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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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 provider**, choose **GitHub**\. + For **Repository**, choose **Public repository**\. @@ -328,7 +328,7 @@ The build project in this example uses source code in the GitHub [AWS samples](h 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.md#run-build-console)\. Leave all settings at their default values, except for these settings\. +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 **Environment image**, choose **Managed image**\. + For **Operating system**, choose **Amazon Linux 2**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index a9bc1b9..6bcbf87 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -26,7 +26,7 @@ To speed up the `DOWNLOAD_SOURCE` phase of your build, you can also to set **Git 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 information, see [Create a build project \(console\)](create-project-console.md) and [Run a build \(console\)](run-build.md#run-build-console)\. Leave all settings at their default values, except for these settings: +1. Create a build project\. For 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: + In **Source**: + For **Source provider**, choose **GitHub**\. If you are not connected to GitHub, follow the instructions to connect\. + For **Repository**, choose **Public repository**\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index e35b951..74c867a 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -45,7 +45,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains + 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\netcoreapp1.0` directory\. + + The executable file for the C\# sample using \.NET Core, `HelloWorldSample.dll`, can be found in the `bin\Debug\netcoreapp3.1` directory\. ## Directory structure @@ -1055,7 +1055,7 @@ phases: - dotnet build artifacts: files: - - .\bin\Debug\netcoreapp1.0\* + - .\bin\Debug\netcoreapp3.1\* ``` `HelloWorldSample.csproj` \(in `(root directory name)` @@ -1064,7 +1064,7 @@ artifacts: Exe - netcoreapp1.0 + netcoreapp3.1 ``` From 6d060b9ed39c74d799064ceece5d51baef8ba00f Mon Sep 17 00:00:00 2001 From: et304383 <2693414+et304383@users.noreply.github.com> Date: Tue, 28 Jul 2020 08:15:58 -0300 Subject: [PATCH 061/156] Fix indentation in example --- doc_source/build-spec-ref.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 862197b..f4997e6 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -233,10 +233,10 @@ phases/install/**runtime\-versions** ``` phases: install: - runtime-versions: - java: corretto8 - python: 3.x - ruby: "$MY_RUBY_VAR" + runtime-versions: + java: corretto8 + 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\. If two specified runtimes conflict, the build fails\. For example, `android: 29` and `java: openjdk11` conflict, so if both are specified, the build fails\. @@ -569,4 +569,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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From 81cb27acbdb0845a6da60f32b6ba55fddab71fe6 Mon Sep 17 00:00:00 2001 From: "shay.elmualem" Date: Mon, 3 Aug 2020 15:35:34 +0300 Subject: [PATCH 062/156] add missing RetryBuild action --- doc_source/auth-and-access-control-permissions-reference.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index dce479b..a0ff0f6 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -148,6 +148,11 @@ StopBuild Required to attempt to stop running builds\. **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name ` +RetryBuild + **Action:** `codebuild:RetryBuild` +Required to attempt to retry execution of a build\. + **Resource:** `arn:aws:codebuild:region-ID: account-ID:project/ project-name` + UpdateProject **Actions:** `codebuild:UpdateProject`, `iam:PassRole` Required to change information about builds\. From d1f32ce9ca556f2913d538ad3b5ef69a5b85af77 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 3 Aug 2020 14:06:20 -0700 Subject: [PATCH 063/156] General update --- README.md | 6 +- ...nd-access-control-permissions-reference.md | 64 +- doc_source/batch-build-buildspec.md | 142 ++++ doc_source/batch-build.md | 11 + doc_source/build-env-ref-env-vars.md | 110 ++- doc_source/build-spec-ref.md | 18 +- doc_source/builds-working.md | 2 + doc_source/change-project.md | 153 +++- doc_source/code-coverage-report.md | 49 ++ doc_source/create-project-cli.md | 786 +++++++++--------- doc_source/create-project-console.md | 308 +++---- doc_source/history.md | 4 +- doc_source/index.md | 7 + doc_source/report-create.md | 2 +- doc_source/retry-build.md | 39 + doc_source/run-batch-build-cli.md | 57 ++ doc_source/run-build-cli.md | 4 +- doc_source/run-build-console.md | 27 + doc_source/run-build.md | 1 + doc_source/sample-build-badges.md | 2 +- .../sample-disable-artifact-encryption.md | 2 +- doc_source/sample-github-enterprise.md | 2 +- doc_source/sample-github-pull-request.md | 2 +- doc_source/sample-pipeline-batch.md | 277 ++++++ doc_source/session-manager.md | 51 +- doc_source/stop-batch-build.md | 41 + doc_source/test-permissions.md | 29 +- doc_source/test-reporting.md | 3 +- doc_source/troubleshooting.md | 13 +- doc_source/use-case-based-samples.md | 2 +- doc_source/view-build-list.md | 55 +- doc_source/view-builds-for-project.md | 55 ++ doc_source/working-with-build-projects.md | 3 +- 33 files changed, 1676 insertions(+), 651 deletions(-) create mode 100644 doc_source/batch-build-buildspec.md create mode 100644 doc_source/batch-build.md create mode 100644 doc_source/code-coverage-report.md create mode 100644 doc_source/retry-build.md create mode 100644 doc_source/run-batch-build-cli.md create mode 100644 doc_source/sample-pipeline-batch.md create mode 100644 doc_source/stop-batch-build.md diff --git a/README.md b/README.md index e633d77..1989489 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,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/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index a0ff0f6..8e7687e 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -12,71 +12,69 @@ 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 ` 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 +84,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 +99,7 @@ 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 ` ListBuilds **Action:** `codebuild:ListBuilds` @@ -111,7 +109,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,43 +134,43 @@ 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 ` - -RetryBuild - **Action:** `codebuild:RetryBuild` -Required to attempt to retry execution of a build\. - **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 ` 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/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md new file mode 100644 index 0000000..3dd6bc9 --- /dev/null +++ b/doc_source/batch-build-buildspec.md @@ -0,0 +1,142 @@ +# Batch build buildspec reference + +## batch + +Optional mapping\. Represents the batch build settings for the project\. + +By default, all of the batch build tasks are run with the build settings, such as `env` and `phases`, specified in this buildspec\. You can override the default build settings by specifying different `env` values, or an entirely different buildspec file in the `batch//buildspec` parameter\. + +The contents of the `batch` property varies based on the type of batch being specified\. The possible batch types are: + +**Topics** ++ [`batch-graph`](#build-spec.batch.build-graph) ++ [`batch-list`](#build-spec.batch.build-list) ++ [`batch-matrix`](#build-spec.batch.build-matrix) + +### `batch-graph` + +Defines a *build graph*\. A build graph is used to define a set of tasks that have dependencies on other tasks in the batch\. + +batch/ **fast\-fail** +Optional\. + `false` +The default value\. All running builds will complete\. + `true` +All running builds will be stopped when one of the builds fail\. + +batch/batch\-graph/**buildspec** +Optional\. Specifies the path and file name of the buildspec file to use for this task\. + +batch/batch\-graph/**depend\-on** +An array of task identifiers that this task depends on\. This task will not be run until these tasks are completed\. + +batch/batch\-graph/**env** +Optional\. Defines the build environment overrides for the task\. +batch/batch\-graph/env/**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\. +batch/batch\-graph/env/**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\. +batch/batch\-graph/env/**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\. +batch/batch\-graph/env/**variables** +Defines 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, \. + +batch/batch\-graph/**identifier** +Required\. The identifier of the task\. + +The following is an example of a build graph buildspec entry: + +``` +batch: + fast-fail: false + build-graph: + - identifier: linux_small + env: + compute-type: BUILD_GENERAL1_SMALL + - identifier: linux_medium + env: + compute-type: BUILD_GENERAL1_MEDIUM + depend-on: + - linux_small + - identifier: linux_large + env: + compute-type: BUILD_GENERAL1_LARGE + depend-on: + - linux_medium +``` + +### `batch-list` + +Defines a *build list*\. A build list is used to define a number of tasks that run in parallel\. + +batch/ **fast\-fail** +Optional\. + `false` +The default value\. All running builds will complete\. + `true` +All running builds will be stopped when one of the builds fail\. + +batch/batch\-list/**env** +Optional\. Defines the build environment overrides for the task\. +batch/batch\-graph/env/**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\. +batch/batch\-graph/env/**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\. +batch/batch\-graph/env/**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\. +batch/batch\-graph/env/**variables** +Defines 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, \. + +batch/batch\-list/**identifier** +Optional\. The identifier of the task\. + +The following is an example of a build list buildspec entry: + +``` +batch: + fast-fail: false + build-list: + - identifier: linux_small + env: + compute-type: BUILD_GENERAL1_SMALL + - identifier: windows_medium + env: + type: WINDOWS_CONTAINER + image: aws/codebuild/windows-base:2.0 + compute-type: BUILD_GENERAL1_MEDIUM +``` + +### `batch-matrix` + +Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. For example, if your build matrix has two images and three values for an environment variable, such as this: + +``` +batch: + build-matrix: + env: + image: + - aws/codebuild/amazonlinux2-x86_64-standard:3.0 + - aws/codebuild/windows-base:2.0 + variables: + MY_VAR: + - VALUE1 + - VALUE2 + - VALUE3 +``` + +CodeBuild will create six builds: ++ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE1` ++ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE2` ++ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE3` ++ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE1` ++ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE2` ++ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE3` + +batch/batch\-matrix/**env** +Optional\. Defines the build environment overrides for the task\. +batch/batch\-matrix/env/**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\. +batch/batch\-matrix/env/**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\. +batch/batch\-matrix/env/**variables** +Defines 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, \. \ 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..fc263ae --- /dev/null +++ b/doc_source/batch-build.md @@ -0,0 +1,11 @@ +# Batch builds in AWS CodeBuild + +AWS CodeBuild supports the execution of concurrent and coordinated builds of a project with *batch builds*\. 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) + +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\. \ No newline at end of file diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 5525e31..cbbbff5 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -1,41 +1,87 @@ # 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\_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\. **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** + +CODEBUILD\_SRC\_DIR +The directory path that CodeBuild uses for the build \(for example, `/tmp/src123456789/src`\)\. 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`\. + +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`\. 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) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index f4997e6..5816ec3 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 @@ -59,6 +60,12 @@ proxy: 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 @@ -102,7 +109,7 @@ reports: - location base-directory: location discard-paths: no | yes - file-format: JunitXml | NunitXml | CucumberJson | VisualStudioTrx | TestNGXml + file-format: report-format artifacts: files: - location @@ -287,12 +294,17 @@ 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: +Optional mapping\. Represents the test report file format\. If not specified, `JunitXml` is used\. The following test report file formats are supported: + `CucumberJson` + `JunitXml` + `NunitXml` + `TestNGXml` + `VisualStudioTrx` +The following code coverage report formats are supported: ++ `JaCoCoXml` ++ `SimpleCov` ++ `CloverXml` ++ `CoberturaXml` 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\. @@ -569,4 +581,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-working.md b/doc_source/builds-working.md index 9a5102b..f9d150d 100644 --- a/doc_source/builds-working.md +++ b/doc_source/builds-working.md @@ -19,5 +19,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.md b/doc_source/change-project.md index b4352f5..64e842b 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -25,11 +25,127 @@ If you add test reporting to a build project, make sure your IAM role has the pe 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**\. +1. To change information about the source code location, in **Source**, choose **Edit**\. Use the following lists 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) +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**\. + + **Use Git submodules** +Select 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**\. + + **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\. + + 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\. + + 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)\. + +------ +#### [ 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**\. + + **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\. + + 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)\. + +------ +#### [ 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**\. + + **Use Git submodules** +Select 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\. +The status of a build triggered by a webhook is always reported to your source provider\. + + **Insecure SSL** +Choose 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)\. + +------ 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)\. @@ -90,6 +206,25 @@ If you choose **New service role**, the service role includes permission to decr 1. Choose **Update buildspec**\. +1. To change information about the batch build configuration, in **Batch configuration**, choose **Edit** and update the folowing values as needed\. +**Batch service role** +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\. + +1. Choose **Update batch configuration**\. + 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**\. @@ -125,17 +260,15 @@ Do not append a forward slash \(/\) to the end of **Path prefix**\. 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: +1. Create a skeleton JSON file with 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, using the `--generate-cli-skeleton` option: ``` - aws codebuild update-project --generate-cli-skeleton + 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\. + This creates a JSON file with the path and file name specified by **\. Modify the JSON data as described in [Create a build project \(AWS CLI\)](create-project-cli.md), and save your results\. -1. Switch to the directory that contains the file you just saved, and run the update\-project command again\. +1. Switch to the directory that contains the file you just saved, and 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 again\. ``` aws codebuild update-project --cli-input-json file://update-project.json diff --git a/doc_source/code-coverage-report.md b/doc_source/code-coverage-report.md new file mode 100644 index 0000000..327924a --- /dev/null +++ b/doc_source/code-coverage-report.md @@ -0,0 +1,49 @@ +# 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 + +## 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\. AWS 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\. AWS 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, AWS 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/create-project-cli.md b/doc_source/create-project-cli.md index 50c2853..fb9b9fa 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -1,320 +1,328 @@ # 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`\. +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": "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`\. ++ 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** 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\. @@ -327,100 +335,82 @@ 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`\. + 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** 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\. + + 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** 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\. + ``` + - 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*\. + +### Configure batch builds + +To configure batch builds for the project, insert the following JSON object at the root of your JSON file \(if not already present\): + +``` + "buildBatchConfig": { + "combineArtifacts": combineArtifacts, + "restrictions": { + "computeTypesAllowed": [ + allowedComputeTypes + ], + "maximumBuildsAllowed": maximumBuildsAllowed + }, + "serviceRole": "batchServiceRole", + "timeoutInMins": batchTimeout + } +``` + +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\. + +*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\. + +## 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\. -**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)\. 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..63ef1d1 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -1,29 +1,41 @@ # 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** +Select 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**: +**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\. - For **Source provider**, choose the source code provider type\. Use the following lists to make selections appropriate for your source provider: -**Note** +## 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\. ------ @@ -69,18 +81,18 @@ Choose **Git clone depth** to create a shallow clone with a history truncated to **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\. +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\. +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 `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 **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\. +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\. - 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)\. +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)\. ------ #### [ GitHub ] @@ -98,18 +110,18 @@ Choose **Git clone depth** to create a shallow clone with a history truncated to **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\. +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\. +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 **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\. +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)\. +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)\. ------ #### [ GitHub Enterprise Server ] @@ -134,79 +146,59 @@ The status of a build triggered by a webhook is always reported to your source p **Insecure SSL** Choose 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\. +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 **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\. +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)\. +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)\. ------ - For each secondary source you want: - - 1. Choose **Add source**\. - - 1. For **Source identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. +## Environment - 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\. +**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*\. -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=overlay& +- timeout -t 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 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\. +**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 +206,110 @@ 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**: +## 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**\. +**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)\. - For more information, see the [Buildspec reference](build-spec-ref.md)\. +## Batch configuration -1. In **Artifacts**: +You can run a group of builds as a single execution\. For more information, see [Batch builds in AWS CodeBuild](batch-build.md)\. - 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**\. +**Define batch configuration** +Select to allow batch builds in this project\. - For each secondary set of artifacts you want: +**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\. - 1. For **Artifact identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. +**Allowed compute type\(s\) for batch** +Select the compute types allowed for the batch\. Select all that apply\. - 1. Choose **Add artifact**\. +**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\. - 1. Follow the previous steps to configure your secondary artifacts\. +**Batch timeout** +Enter the maximum amount of time for the batch build to complete\. - 1. Choose **Save artifact**\. +**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\. - Expand **Additional configuration**\. +## Artifacts - \(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`\. +**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: - 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\. 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\. +1. For **Artifact identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. - 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\. +1. Choose **Add artifact**\. - \(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. Follow the previous steps to configure your secondary artifacts\. -1. Choose **Create build project**\. +1. Choose **Save artifact**\. -1. On the **Review** page, choose **Start build**\. \ No newline at end of file +**Additional configuration** +**Encryption key** +\(Optional\) 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`\. +**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\. 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)\. + +## 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/history.md b/doc_source/history.md index e0706e2..6c83795 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,12 @@ 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 documentation update: **July 30, 2020 | Change | Description | Date | | --- |--- |--- | +| [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 the execution of 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 | | [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 | diff --git a/doc_source/index.md b/doc_source/index.md index 57f5042..fa39816 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -48,6 +48,7 @@ Amazon's trademarks and trade dress may not be used in + [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) @@ -68,6 +69,7 @@ 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) + [Build environment compute types](build-env-ref-compute-types.md) @@ -104,10 +106,12 @@ 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) + [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 +119,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) @@ -145,6 +151,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) diff --git a/doc_source/report-create.md b/doc_source/report-create.md index eee2c43..eac2846 100644 --- a/doc_source/report-create.md +++ b/doc_source/report-create.md @@ -16,4 +16,4 @@ 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/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..76ac1a7 --- /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` 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.md b/doc_source/run-build-cli.md index 33fb710..b2c9d6b 100644 --- a/doc_source/run-build-cli.md +++ b/doc_source/run-build-cli.md @@ -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: ``` { @@ -54,7 +54,7 @@ For more information about using the AWS CLI with CodeBuild, see the [Command li "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..cb2dc95 100644 --- a/doc_source/run-build-console.md +++ b/doc_source/run-build-console.md @@ -19,6 +19,33 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll Here you can change settings for this build only\. The settings in this section are optional\. + Under **Build configuration**, you can select to run this build as a single build, or a batch build\. +**Single build** +Choose this to perform a single build\. +**Batch build** +Choose this to perform a batch build\. + + Under **Batch configuration**, you set the batch build configuration overrides for this build\. +**Note** +This section is only displayed when **Batch build** is selected in **Build configuration**\. +**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\. +To change whether CodeBuild can modify the batch service role you use for this build, 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)\. +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\. + Under **Source**, you can: + Choose **Add source** to add a secondary source\. + Choose **Remove source** to remove a secondary source\. 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/sample-build-badges.md b/doc_source/sample-build-badges.md index 33d0546..c9e4d14 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -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\. diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index f2ba604..c0ad8ed 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -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\. diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 84abb3e..3cf44b7 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -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\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 3109040..47b0bfa 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -32,7 +32,7 @@ AWS CodeBuild supports webhooks when the source repository is GitHub\. This mean 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\. 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/session-manager.md b/doc_source/session-manager.md index 1e2928c..682029b 100644 --- a/doc_source/session-manager.md +++ b/doc_source/session-manager.md @@ -34,7 +34,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 +112,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\. 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-reporting.md b/doc_source/test-reporting.md index b3ab5ca..045b3c1 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -26,4 +26,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/troubleshooting.md b/doc_source/troubleshooting.md index 3767a93..632204b 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -31,6 +31,7 @@ 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: BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE](#troubleshooting-windows-version-mismatch) ## Apache Maven builds reference artifacts from the wrong repository @@ -494,4 +495,14 @@ 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: BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE + +**Issue:** When building, you receive an error similar to the following: + +BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE: Unable to pull customer's container image\. CannotPullContainerError: a Windows version 10\.0\.17763\-based image is incompatible with a 10\.0\.14393 host + +**Possible causes:** You have selected a Windows Server 2016 environment type \(`WINDOWS_CONTAINER`\), but selected a Windows Server 2019 image\. + +**Recommended solutions:** Change the environment type to `WINDOWS_SERVER_2019_CONTAINER`\. \ 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..7396cd5 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -14,7 +14,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) 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/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 48df157..4f7c219 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -15,4 +15,5 @@ You can perform these tasks when working with build projects: + [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) \ No newline at end of file From eb45717b943f32c71c858284a570ab58dacb90d3 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 6 Aug 2020 07:42:06 -0700 Subject: [PATCH 064/156] General update --- doc_source/advanced-topics.md | 7 +- doc_source/batch-build-buildspec.md | 152 +++++++++++------- doc_source/build-env-ref-env-vars.md | 2 +- doc_source/cloudformation-vpc-template.md | 2 +- doc_source/create-project-cli.md | 7 +- doc_source/getting-started-cli.md | 2 +- doc_source/getting-started.md | 2 +- doc_source/history.md | 1 - doc_source/how-to-create-pipeline.md | 2 +- doc_source/how-to-run.md | 2 +- doc_source/index.md | 10 +- doc_source/planning.md | 4 +- doc_source/report-groups-sharing.md | 8 +- doc_source/run-build-console.md | 2 +- doc_source/run-build-sdks.md | 2 +- doc_source/sample-bitbucket-pull-request.md | 10 +- doc_source/sample-build-badges.md | 4 +- doc_source/sample-build-notifications.md | 2 +- doc_source/sample-codedeploy.md | 2 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 2 +- doc_source/sample-github-pull-request.md | 10 +- doc_source/sample-source-version.md | 4 +- doc_source/sample-windows.md | 2 +- ...e-lambda.md => serverless-applications.md} | 4 +- doc_source/use-case-based-samples.md | 3 - doc_source/welcome.md | 2 +- 27 files changed, 149 insertions(+), 105 deletions(-) rename doc_source/{sample-lambda.md => serverless-applications.md} (64%) 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/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 3dd6bc9..eea291f 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -4,46 +4,53 @@ Optional mapping\. Represents the batch build settings for the project\. -By default, all of the batch build tasks are run with the build settings, such as `env` and `phases`, specified in this buildspec\. You can override the default build settings by specifying different `env` values, or an entirely different buildspec file in the `batch//buildspec` parameter\. +batch/**fast\-fail** +Optional\. +`false` +The default value\. All running builds will complete\. +`true` +All running builds will be stopped when one of the builds fail\. -The contents of the `batch` property varies based on the type of batch being specified\. The possible batch types are: +By default, all of the batch build tasks are run with the build settings, such as `env` and `phases`, specified in this buildspec\. You can override the default build settings by specifying different `env` values, or an entirely different buildspec file in the `batch//buildspec` parameter\. -**Topics** -+ [`batch-graph`](#build-spec.batch.build-graph) -+ [`batch-list`](#build-spec.batch.build-list) -+ [`batch-matrix`](#build-spec.batch.build-matrix) +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-graph` +## `batch/build-graph` Defines a *build graph*\. A build graph is used to define a set of tasks that have dependencies on other tasks in the batch\. -batch/ **fast\-fail** -Optional\. - `false` -The default value\. All running builds will complete\. - `true` -All running builds will be stopped when one of the builds fail\. - -batch/batch\-graph/**buildspec** +batch/build\-graph/**buildspec** Optional\. Specifies the path and file name of the buildspec file to use for this task\. -batch/batch\-graph/**depend\-on** +batch/build\-graph/**depend\-on** An array of task identifiers that this task depends on\. This task will not be run until these tasks are completed\. -batch/batch\-graph/**env** +batch/build\-graph/**env** Optional\. Defines the build environment overrides for the task\. -batch/batch\-graph/env/**compute\-type** +batch/build\-graph/env/**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\. -batch/batch\-graph/env/**image** +batch/build\-graph/env/**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\. -batch/batch\-graph/env/**type** +batch/build\-graph/env/**privileged\-mode** +Optional\. Enables running 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`\. +batch/build\-graph/env/**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\. -batch/batch\-graph/env/**variables** +batch/build\-graph/env/**variables** Defines 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, \. -batch/batch\-graph/**identifier** +batch/build\-graph/**identifier** Required\. The identifier of the task\. +batch/build\-graph/**ignore\-failure** +Optional\. Specifies if failures in the batch can be ignored\. +`false` +The default value\. If one build task fails, the batch build will fail immediately\. +`true` +If one build task fails, the remaining build tasks will still be run\. + The following is an example of a build graph buildspec entry: ``` @@ -65,31 +72,36 @@ batch: - linux_medium ``` -### `batch-list` +## `batch/build-list` Defines a *build list*\. A build list is used to define a number of tasks that run in parallel\. -batch/ **fast\-fail** -Optional\. - `false` -The default value\. All running builds will complete\. - `true` -All running builds will be stopped when one of the builds fail\. +batch/build\-list/**buildspec** +Optional\. Specifies the path and file name of the buildspec file to use for this task\. -batch/batch\-list/**env** +batch/build\-list/**env** Optional\. Defines the build environment overrides for the task\. -batch/batch\-graph/env/**compute\-type** +batch/build\-list/env/**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\. -batch/batch\-graph/env/**image** +batch/build\-list/env/**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\. -batch/batch\-graph/env/**type** +batch/build\-list/env/**privileged\-mode** +Optional\. Enables running 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`\. +batch/build\-list/env/**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\. -batch/batch\-graph/env/**variables** +batch/build\-list/env/**variables** Defines 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, \. -batch/batch\-list/**identifier** +batch/build\-list/**identifier** Optional\. The identifier of the task\. +batch/build\-list/**ignore\-failure** +Optional\. Specifies if failures in the batch can be ignored\. +`false` +The default value\. If one build task fails, the batch build will fail immediately\. +`true` +If one build task fails, the remaining build tasks will still be run\. + The following is an example of a build list buildspec entry: ``` @@ -106,22 +118,58 @@ batch: compute-type: BUILD_GENERAL1_MEDIUM ``` -### `batch-matrix` +## `batch/build-matrix` + +Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. + +batch/build\-matrix/**static** +The static properties apply to all build tasks\. +batch/build\-matrix/static/**ignore\-failure** +Optional\. Specifies if failures in the batch can be ignored\. +`false` +The default value\. If one build task fails, the batch build will fail immediately\. +`true` +If one build task fails, the remaining build tasks will still be run\. +batch/build\-matrix/static/**env** +Optional\. Defines the build environment overrides for the task\. +batch/build\-matrix/static/env/**privileged\-mode** +Optional\. Enables running 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`\. +batch/build\-matrix/static/env/**type** +Optional\. 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\. + +batch/build\-matrix/**dynamic** +The dynamic properties define the build matrix\. +batch/build\-matrix/dynamic/**buildspec** +Optional\. Specifies the path and file name of the buildspec file to use for this task\. +batch/build\-matrix/dynamic/**env** +Optional\. Defines the build environment overrides for the task\. +batch/build\-matrix/dynamic/env/**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\. +batch/build\-matrix/dynamic/env/**image** +Optional\. 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\. +batch/build\-matrix/dynamic/env/**variables** +Defines 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, \. -Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. For example, if your build matrix has two images and three values for an environment variable, such as this: +For example, if your build matrix has two images and three values for an environment variable, such as this: ``` batch: build-matrix: - env: - image: - - aws/codebuild/amazonlinux2-x86_64-standard:3.0 - - aws/codebuild/windows-base:2.0 - variables: - MY_VAR: - - VALUE1 - - VALUE2 - - VALUE3 + static: + ignore-failure: false + env: + type: LINUX_CONTAINER + privileged-mode: true + dynamic: + env: + image: + - aws/codebuild/amazonlinux2-x86_64-standard:3.0 + - aws/codebuild/windows-base:2.0 + variables: + MY_VAR: + - VALUE1 + - VALUE2 + - VALUE3 ``` CodeBuild will create six builds: @@ -132,11 +180,7 @@ CodeBuild will create six builds: + `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE2` + `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE3` -batch/batch\-matrix/**env** -Optional\. Defines the build environment overrides for the task\. -batch/batch\-matrix/env/**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\. -batch/batch\-matrix/env/**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\. -batch/batch\-matrix/env/**variables** -Defines 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, \. \ No newline at end of file +Each build will have the following settings: ++ `ignore-failure` set to `false` ++ `env/type` set to `LINUX_CONTAINER` ++ `env/privileged`\-mode set to `true` \ No newline at end of file diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index cbbbff5..c21bf91 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -84,7 +84,7 @@ 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/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/create-project-cli.md b/doc_source/create-project-cli.md index fb9b9fa..1b4e28d 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -67,13 +67,13 @@ Modify the JSON data as follows and save your results\. "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", @@ -84,8 +84,7 @@ Modify the JSON data as follows and save your results\. "packaging": "packaging", "artifactIdentifier": "artifact-identifier" } - ] - , + ], "secondarySources": [ { "type": "source-type", diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md index c54b118..9ab0cbc 100644 --- a/doc_source/getting-started-cli.md +++ b/doc_source/getting-started-cli.md @@ -2,7 +2,7 @@ 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)\. diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md index e87fe5c..95a68af 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -2,7 +2,7 @@ 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)\. diff --git a/doc_source/history.md b/doc_source/history.md index 6c83795..2c7d8da 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -83,7 +83,6 @@ The following table describes important changes in each release of the *AWS Code | 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 | diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 529cfa2..5d03365 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\. diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md index 49223b8..0887716 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) diff --git a/doc_source/index.md b/doc_source/index.md index fa39816..79d6d99 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -52,7 +52,6 @@ Amazon's trademarks and trade dress may not be used in + [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) @@ -77,14 +76,10 @@ Amazon's trademarks and trade dress may not be used in + [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) + [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) @@ -177,6 +172,11 @@ Amazon's trademarks and trade dress may not be used in + [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) + + [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/planning.md b/doc_source/planning.md index 20361d3..cf4f02a 100644 --- a/doc_source/planning.md +++ b/doc_source/planning.md @@ -17,5 +17,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/report-groups-sharing.md b/doc_source/report-groups-sharing.md index 78d7b32..ffd1275 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" }] @@ -106,14 +106,14 @@ 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: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/run-build-console.md b/doc_source/run-build-console.md index cb2dc95..a3b553b 100644 --- a/doc_source/run-build-console.md +++ b/doc_source/run-build-console.md @@ -1,6 +1,6 @@ # 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)\. 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/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 15f946c..7bbc5d1 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -112,7 +112,7 @@ 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/master$` and head references that match `^refs/heads/branch1!`\. ++ 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/) @@ -154,7 +154,7 @@ In this example, a webhook filter group triggers a build for a push event when t ``` 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 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$`\. ``` @@ -170,7 +170,7 @@ In this example, a webhook filter group triggers a build for a push event when t }, { "type": "BASE_REF", - "pattern": "^refs/heads/master$" + "pattern": "^refs/heads/main$" } ], [ @@ -261,7 +261,7 @@ You can create a filter that triggers a build only when the head commit message ### 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 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\]`\. @@ -286,7 +286,7 @@ CodeBuildProject: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF - Pattern: ^refs/heads/master$ + Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index c9e4d14..d610329 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -60,7 +60,7 @@ You can use AWS CodeBuild console or the AWS CLI to access build badges\. + 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 for the default branch, but you can specify any branch in your source repository that you have used to run a build\. ## Publish your CodeBuild build badges @@ -69,7 +69,7 @@ You can include your build badge request URL in a markdown file in your preferre Sample markdown code: ``` -![Build Status](https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch=master) +![Build Status](https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch=main) ``` ## CodeBuild badge statuses diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index e891fed..9674f7d 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -252,7 +252,7 @@ If you want to trigger events for both build state changes and build phase chang 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..0703291 100644 --- a/doc_source/sample-codedeploy.md +++ b/doc_source/sample-codedeploy.md @@ -162,7 +162,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-docker.md b/doc_source/sample-docker.md index 3884774..edb7c4a 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: @@ -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..d42f267 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -111,7 +111,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\.\) diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 47b0bfa..dc48481 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -119,7 +119,7 @@ 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 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/) @@ -161,7 +161,7 @@ To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` fi ``` 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 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$`\. ``` @@ -177,7 +177,7 @@ To use the AWS CodeBuild SDK to filter webhook events, use the `filterGroups` fi }, { "type": "BASE_REF", - "pattern": "^refs/heads/master$" + "pattern": "^refs/heads/main$" } ], [ @@ -268,7 +268,7 @@ You can create a filter that triggers a build only when the head commit message ### 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 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\]`\. @@ -293,7 +293,7 @@ CodeBuildProject: - - Type: EVENT Pattern: PULL_REQUEST_CREATED,PULL_REQUEST_UPDATED - Type: BASE_REF - Pattern: ^refs/heads/master$ + Pattern: ^refs/heads/main$ ExcludeMatchedPattern: false - Type: ACTOR_ACCOUNT_ID Pattern: 12345 diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index 6bcbf87..2de7eae 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\. @@ -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-windows.md b/doc_source/sample-windows.md index 74c867a..dc87e64 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -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, run the build, and follow 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\.\) 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/use-case-based-samples.md b/doc_source/use-case-based-samples.md index 7396cd5..b651482 100644 --- a/doc_source/use-case-based-samples.md +++ b/doc_source/use-case-based-samples.md @@ -23,9 +23,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/welcome.md b/doc_source/welcome.md index 552b8a1..2bde9c8 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -27,7 +27,7 @@ As the following diagram shows, you can add CodeBuild as a build or test action ![\[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)\. From dc8a513acebc5f4efda9734edfe4163dcec548a6 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 12 Aug 2020 18:28:30 +0000 Subject: [PATCH 065/156] General updates --- doc_source/batch-build-buildspec.md | 50 +++++++++++++++-------------- doc_source/run-build-console.md | 7 ++-- doc_source/security-encryption.md | 4 +-- 3 files changed, 31 insertions(+), 30 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index eea291f..0ccf68d 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -1,17 +1,19 @@ # Batch build buildspec reference +This topic contains the buildspec reference for batch build properties\. + ## batch -Optional mapping\. Represents the batch build settings for the project\. +Optional mapping\. The batch build settings for the project\. batch/**fast\-fail** Optional\. `false` The default value\. All running builds will complete\. `true` -All running builds will be stopped when one of the builds fail\. +All running builds will be stopped if one of the builds fails\. -By default, all of the batch build tasks are run with the build settings, such as `env` and `phases`, specified in this buildspec\. You can override the default build settings by specifying different `env` values, or an entirely different buildspec file in the `batch//buildspec` parameter\. +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) @@ -20,36 +22,36 @@ The contents of the `batch` property varies based on the type of batch build bei ## `batch/build-graph` -Defines a *build graph*\. A build graph is used to define a set of tasks that have dependencies on other tasks in the batch\. +Defines a *build graph*\. A build graph defines a set of tasks that have dependencies on other tasks in the batch\. batch/build\-graph/**buildspec** -Optional\. Specifies the path and file name of the buildspec file to use for this task\. +Optional\. The path and file name of the buildspec file to use for this task\. batch/build\-graph/**depend\-on** -An array of task identifiers that this task depends on\. This task will not be run until these tasks are completed\. +An array of task identifiers that this task depends on\. This task will not run until these tasks are completed\. batch/build\-graph/**env** -Optional\. Defines the build environment overrides for the task\. +Optional\. The build environment overrides for the task\. batch/build\-graph/env/**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\. batch/build\-graph/env/**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\. batch/build\-graph/env/**privileged\-mode** -Optional\. Enables running 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`\. +Optional\. 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`\. batch/build\-graph/env/**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\. batch/build\-graph/env/**variables** -Defines 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, \. +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, \. batch/build\-graph/**identifier** Required\. The identifier of the task\. batch/build\-graph/**ignore\-failure** -Optional\. Specifies if failures in the batch can be ignored\. +Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` The default value\. If one build task fails, the batch build will fail immediately\. `true` -If one build task fails, the remaining build tasks will still be run\. +If one build task fails, the remaining build tasks will still run\. The following is an example of a build graph buildspec entry: @@ -77,30 +79,30 @@ batch: Defines a *build list*\. A build list is used to define a number of tasks that run in parallel\. batch/build\-list/**buildspec** -Optional\. Specifies the path and file name of the buildspec file to use for this task\. +Optional\. The path and file name of the buildspec file to use for this task\. batch/build\-list/**env** -Optional\. Defines the build environment overrides for the task\. +Optional\. The build environment overrides for the task\. batch/build\-list/env/**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\. batch/build\-list/env/**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\. batch/build\-list/env/**privileged\-mode** -Optional\. Enables running 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`\. +Optional\. 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`\. batch/build\-list/env/**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\. batch/build\-list/env/**variables** -Defines 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, \. +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, \. batch/build\-list/**identifier** Optional\. The identifier of the task\. batch/build\-list/**ignore\-failure** -Optional\. Specifies if failures in the batch can be ignored\. +Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` The default value\. If one build task fails, the batch build will fail immediately\. `true` -If one build task fails, the remaining build tasks will still be run\. +If one build task fails, the remaining build tasks will still run\. The following is an example of a build list buildspec entry: @@ -125,30 +127,30 @@ Defines a *build matrix*\. A build matrix is used to define tasks that will run batch/build\-matrix/**static** The static properties apply to all build tasks\. batch/build\-matrix/static/**ignore\-failure** -Optional\. Specifies if failures in the batch can be ignored\. +Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` The default value\. If one build task fails, the batch build will fail immediately\. `true` -If one build task fails, the remaining build tasks will still be run\. +If one build task fails, the remaining build tasks will still run\. batch/build\-matrix/static/**env** -Optional\. Defines the build environment overrides for the task\. +Optional\. The build environment overrides for the task\. batch/build\-matrix/static/env/**privileged\-mode** -Optional\. Enables running 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`\. +Optional\. 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`\. batch/build\-matrix/static/env/**type** Optional\. 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\. batch/build\-matrix/**dynamic** The dynamic properties define the build matrix\. batch/build\-matrix/dynamic/**buildspec** -Optional\. Specifies the path and file name of the buildspec file to use for this task\. +Optional\. The path and file name of the buildspec file to use for this task\. batch/build\-matrix/dynamic/**env** -Optional\. Defines the build environment overrides for the task\. +Optional\. The build environment overrides for the task\. batch/build\-matrix/dynamic/env/**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\. batch/build\-matrix/dynamic/env/**image** Optional\. 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\. batch/build\-matrix/dynamic/env/**variables** -Defines 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, \. +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, \. For example, if your build matrix has two images and three values for an environment variable, such as this: diff --git a/doc_source/run-build-console.md b/doc_source/run-build-console.md index a3b553b..2547711 100644 --- a/doc_source/run-build-console.md +++ b/doc_source/run-build-console.md @@ -19,18 +19,17 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll Here you can change settings for this build only\. The settings in this section are optional\. - Under **Build configuration**, you can select to run this build as a single build, or a batch build\. + Under **Build configuration**, choose from the following:\. **Single build** Choose this to perform a single build\. **Batch build** Choose this to perform a batch build\. - Under **Batch configuration**, you set the batch build configuration overrides for this build\. + Under **Batch configuration**, set the batch build configuration overrides for this build\. **Note** This section is only displayed when **Batch build** is selected in **Build configuration**\. **Service role** -Provides the service role for batch builds\. -Choose one of the following: +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\. To change whether CodeBuild can modify the batch service role you use for this build, 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)\. diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 0857140..ab8d189 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -2,8 +2,8 @@ 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)\. + + 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#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/)\. From 9c896a6270990324c1fb433654457799f328736e Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 20 Aug 2020 21:23:42 +0000 Subject: [PATCH 066/156] General updates --- doc_source/batch-build-buildspec.md | 10 +- doc_source/build-env-ref-available.md | 2 +- doc_source/build-env-ref-cmd.md | 2 +- doc_source/build-env-ref-compute-types.md | 4 +- doc_source/change-project-cli.md | 41 ++ doc_source/change-project-console.md | 246 ++++++++ doc_source/change-project-sdks.md | 3 + doc_source/change-project.md | 277 +-------- doc_source/cmd-ref.md | 2 +- doc_source/codecov-integration.md | 2 +- doc_source/create-project-cli.md | 712 ++++++++++++---------- doc_source/how-to-create-pipeline.md | 10 +- doc_source/how-to-tag-project-delete.md | 2 +- doc_source/how-to-tag-project-update.md | 2 +- doc_source/index.md | 3 + doc_source/sample-efs.md | 27 +- doc_source/setting-up.md | 2 +- 17 files changed, 727 insertions(+), 620 deletions(-) create mode 100644 doc_source/change-project-cli.md create mode 100644 doc_source/change-project-console.md create mode 100644 doc_source/change-project-sdks.md diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 0ccf68d..7b03e20 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -7,7 +7,7 @@ This topic contains the buildspec reference for batch build properties\. Optional mapping\. The batch build settings for the project\. batch/**fast\-fail** -Optional\. +Optional\. For build graphs, this property is not used and is always `true`\. `false` The default value\. All running builds will complete\. `true` @@ -46,18 +46,10 @@ The environment variables that will be present in the build environment\. See [e batch/build\-graph/**identifier** Required\. The identifier of the task\. -batch/build\-graph/**ignore\-failure** -Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. -`false` -The default value\. If one build task fails, the batch build will fail immediately\. -`true` -If one build task fails, the remaining build tasks will still run\. - The following is an example of a build graph buildspec entry: ``` batch: - fast-fail: false build-graph: - identifier: linux_small env: diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index ab8344c..b9f95da 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -62,7 +62,7 @@ The base image of the Windows Server Core 2019 contains the following runtimes\. 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)\. 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: ``` diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index 93a3e4d..203beeb 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)\. diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index eba2a82..ff90481 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -35,8 +35,8 @@ For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncomp 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)\. ++ 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)\. 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\. 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..ba873f1 --- /dev/null +++ b/doc_source/change-project-console.md @@ -0,0 +1,246 @@ +# 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 lists to make selections appropriate for your source provider, and then choose **Update source**\. +**Note** +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**\. + + **Use Git submodules** +Select 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**\. + + **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\. + + 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\. + + 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)\. + +------ +#### [ 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**\. + + **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\. + + 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)\. + +------ +#### [ 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**\. + + **Use Git submodules** +Select 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\. +The status of a build triggered by a webhook is always reported to your source provider\. + + **Insecure SSL** +Choose 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)\. + +------ + + 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 batch build configuration, in **Batch configuration**, choose **Edit** and update the folowing values as needed\. +**Batch service role** +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\. + +1. Choose **Update batch configuration**\. + +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**\. \ 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 64e842b..a9fb3ec 100644 --- a/doc_source/change-project.md +++ b/doc_source/change-project.md @@ -5,277 +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 lists to make selections appropriate for your source provider, and then choose **Update source**\. -**Note** -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**\. - - **Use Git submodules** -Select 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**\. - - **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\. - - 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\. - - 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)\. - ------- -#### [ 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**\. - - **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\. - - 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)\. - ------- -#### [ 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**\. - - **Use Git submodules** -Select 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\. -The status of a build triggered by a webhook is always reported to your source provider\. - - **Insecure SSL** -Choose 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)\. - ------- - - 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 batch build configuration, in **Batch configuration**, choose **Edit** and update the folowing values as needed\. -**Batch service role** -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\. - -1. Choose **Update batch configuration**\. - -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. Create a skeleton JSON file with 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, using the `--generate-cli-skeleton` option: - - ``` - aws codebuild update-project --generate-cli-skeleton > - ``` - - This creates a JSON file with the path and file name specified by **\. Modify the JSON data as described in [Create a build project \(AWS CLI\)](create-project-cli.md), and save your results\. - -1. Switch to the directory that contains the file you just saved, and 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 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/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/codecov-integration.md b/doc_source/codecov-integration.md index de4e9f1..d75d801 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: diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 1b4e28d..9db375a 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -20,309 +20,329 @@ Modify the JSON data as follows and save your results\. ``` { - "name": "project-name", - "description": "description", + "name": "", + "description": "", "source": { - "type": "source-type", - "location": "source-location", - "gitCloneDepth": "gitCloneDepth", - "buildspec": "buildspec", - "InsecureSsl": "InsecureSsl", - "reportBuildStatus": "reportBuildStatus", + "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "BITBUCKET" | "S3" | "NO_SOURCE", + "location": "", + "gitCloneDepth": "", + "buildspec": "", + "InsecureSsl": "", + "reportBuildStatus": "", "buildStatusConfig": { - "context": context, - "targetUrl": target-url + "context": "", + "targetUrl": "" }, "gitSubmodulesConfig": { - "fetchSubmodules": "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" + "type": "", + "resource": "" }, - "s3Logs": { - "status": "s3-logs-status", - "location": "s3-logs-location", - "encryptionDisabled": "s3-logs-encryptionDisabled" - } + "sourceIdentifier": "" }, - "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", + "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "BITBUCKET" | "S3" | "NO_SOURCE", + "location": "", + "gitCloneDepth": "", + "buildspec": "", + "InsecureSsl": "", + "reportBuildStatus": "", "auth": { - "type": "auth-type", - "resource": "resource" + "type": "", + "resource": "" }, - "sourceIdentifier": "source-identifier" + "sourceIdentifier": "" } ], - "serviceRole": "serviceRole", - "vpcConfig": { - "securityGroupIds": [ - "security-group-id" - ], - "subnets": [ - "subnet-id" - ], - "vpcId": "vpc-id" - }, - "fileSystemLocations": [ + "secondarySourceVersions": [ { - "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" + "sourceIdentifier": "", + "sourceVersion": "" } ], - "timeoutInMinutes": timeoutInMinutes, - "encryptionKey": "encryptionKey", - "tags": [ + "sourceVersion": "", + "artifacts": { + "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS", + "location": "", + "path": "", + "namespaceType": "", + "name": "", + "overrideArtifactName": "", + "packaging": "" + }, + "secondaryArtifacts": [ { - "key": "tag-key", - "value": "tag-value" + "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS", + "location": "", + "path": "", + "namespaceType": "", + "name": "", + "packaging": "", + "artifactIdentifier": "" } ], + "cache": { + "type": "", + "location": "", + "mode": [ + "" + ] + }, "environment": { - "type": "environment-type", - "image": "image", - "computeType": "computeType", - "certificate": "certificate", + "type": "WINDOWS_CONTAINER" | "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": "environmentVariable-name", - "value": "environmentVariable-value", - "type": "environmentVariable-type" + "name": "", + "value": "", + "type": "" } ], "registryCredential": [ { - "credential": "credential-arn-or-name", - "credentialProvider": "credential-provider" + "credential": "", + "credentialProvider": "" } ], - "imagePullCredentialsType": "imagePullCredentialsType-value", - "privilegedMode": "privilegedMode" + "imagePullCredentialsType": "CODEBUILD" | "SERVICE_ROLE", + "privilegedMode": "" }, - "badgeEnabled": "badgeEnabled" + "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": + } } ``` 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** + +### **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\. + +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\. + +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 [ProjectArtifiacts](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 [ProjectArtifiacts](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/`\. @@ -330,75 +350,123 @@ 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*\. +``` +- 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" +``` + +### 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 -### Configure batch builds +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\. -To configure batch builds for the project, insert the following JSON object at the root of your JSON file \(if not already present\): +### 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 you rproject\. 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: ``` - "buildBatchConfig": { - "combineArtifacts": combineArtifacts, - "restrictions": { - "computeTypesAllowed": [ - allowedComputeTypes - ], - "maximumBuildsAllowed": maximumBuildsAllowed - }, - "serviceRole": "batchServiceRole", - "timeoutInMins": batchTimeout - } +aws ec2 describe-vpcs --region ``` -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\. +subnets +Required\. An array of subnet IDs that include resources used by CodeBuild\. Run this command to get these IDs: -*combineArtifacts* -A boolean that specifies if the build artifacts for the batch build should be combined into a single artifact location\. +``` +aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region +``` -*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\. +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 whener to include build badges with your CodeBuild project\. Set to `true` to enable build baddes, or `false` otehrwise\. 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\. -*maximumBuildsAllowed* -Specifies the maximum number of builds allowed\. +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\. -*batchServiceRole* -Specifies the service role ARN for the batch build project\. +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\. -*batchTimeout* -Specifies the maximum amount of time, in minutes, that the batch build must be completed in\. +buildBatchConfig/**timeoutInMinutes** +The maximum amount of time, in minutes, that the batch build must be completed in\. ## Create the project @@ -410,7 +478,7 @@ 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.md#change-project-cli)\. +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/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 5d03365..16091b7 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -127,9 +127,9 @@ This is not the source bucket for your pipeline's source code\. This is the arti 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)\. + 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-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.md#change-project-console)\. +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\. @@ -371,9 +371,9 @@ This procedure shows you how to add the build action inside of a build stage\. T 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)\. + 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.md#change-project-console) +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. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. @@ -511,7 +511,7 @@ This procedure shows you how to add the test action in a test stage\. To add the 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) +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. 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/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 79d6d99..af877c2 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -94,6 +94,9 @@ Amazon's trademarks and trade dress may not be used in + [Create AWS CodeBuild triggers](trigger-create.md) + [Edit AWS CodeBuild triggers](triggers-edit.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) diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 1ba07a4..d4d5c87 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -129,4 +129,29 @@ By default, Docker containers do not allow access to any devices\. Privileged mo + 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 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 + +When using a custom EFS file system policy, you must first establish a trust relationship between EFS and CodeBuild by doing one of the following: ++ Add `codebuild.amazonaws.com` as a trusted service in the Principal in the EFS file system policy, ++ Add the `elasticfilesystem:ClientMount` action to the CodeBuild project service role policy\. + +### 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 EFS mount target\. You can resolve this by adding a VPC subnet in the same availability zone as the EFS mount target\. ++ The security group does not have permissions to communicate with 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/setting-up.md b/doc_source/setting-up.md index 493b9c1..83e68f8 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -221,7 +221,7 @@ You need an AWS CodeBuild service role so that CodeBuild can interact with depen + [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) ++ [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\. From 527a41f0faf79289ff59cfc15dac719c19ec36d7 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 24 Aug 2020 15:56:11 +0000 Subject: [PATCH 067/156] General updates --- doc_source/bitbucket-webhook.md | 241 +++++++++++++++++++ doc_source/change-project-console.md | 6 +- doc_source/create-project-console.md | 6 +- doc_source/github-webhook.md | 244 ++++++++++++++++++++ doc_source/history.md | 2 +- doc_source/index.md | 2 + doc_source/sample-bitbucket-pull-request.md | 239 +------------------ doc_source/sample-github-pull-request.md | 241 +------------------ doc_source/troubleshooting.md | 11 +- doc_source/working-with-build-projects.md | 2 + 10 files changed, 502 insertions(+), 492 deletions(-) create mode 100644 doc_source/bitbucket-webhook.md create mode 100644 doc_source/github-webhook.md diff --git a/doc_source/bitbucket-webhook.md b/doc_source/bitbucket-webhook.md new file mode 100644 index 0000000..40433b4 --- /dev/null +++ b/doc_source/bitbucket-webhook.md @@ -0,0 +1,241 @@ +# 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 triggered for specified branches only\. + + 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\. +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) + +**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/change-project-console.md b/doc_source/change-project-console.md index ba873f1..aeb1127 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -72,7 +72,7 @@ The status of a build triggered by a webhook is always reported to your source p 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\. - 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)\. + 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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub ] @@ -101,7 +101,7 @@ The status of a build triggered by a webhook is always reported to your source p 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)\. + 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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub Enterprise Server ] @@ -132,7 +132,7 @@ Choose to ignore SSL warnings while connecting to your GitHub Enterprise project 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)\. + 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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 63ef1d1..5ddde50 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -92,7 +92,7 @@ For **Status context**, enter the value to be used for the `name` parameter in t 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\. -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)\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub ] @@ -121,7 +121,7 @@ For **Status context**, enter the value to be used for the `context` parameter i 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)\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub Enterprise Server ] @@ -152,7 +152,7 @@ For **Status context**, enter the value to be used for the `context` parameter i 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)\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md new file mode 100644 index 0000000..6f0458d --- /dev/null +++ b/doc_source/github-webhook.md @@ -0,0 +1,244 @@ +# 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/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\) + + 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/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 2c7d8da..19c0d0c 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -24,7 +24,7 @@ The following table describes the important changes to the documentation since t | [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 | diff --git a/doc_source/index.md b/doc_source/index.md index af877c2..fdd1947 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -93,6 +93,8 @@ 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) + + [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) diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 7bbc5d1..bceb099 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -1,12 +1,13 @@ # 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 events](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\. **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 @@ -65,238 +66,4 @@ CodeBuild does not support Bitbucket Server\. "statusCode":200 ``` -1. Navigate to the Bitbucket pull request page to see the status of the build\. - -## Filter 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 triggered for specified branches only\. - - 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\. - -**Note** - You can find the webhook payload in the webhook settings of your Bitbucket repository\. - -**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: - -![\[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 +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-github-pull-request.md b/doc_source/sample-github-pull-request.md index dc48481..811ffe3 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)\. +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 [GitHub webhook events](github-webhook.md)\. ## Create a build project with GitHub as the source repository and enable webhooks \(console\) @@ -72,241 +72,4 @@ When you use the console to create or update a build project, you can create a C 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/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 +![\[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/) \ No newline at end of file diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 632204b..0cdd4b0 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -9,7 +9,6 @@ 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) + [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) @@ -163,15 +162,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)\. - -## Cannot view build success or failure - -**Issue:** You cannot see the success or failure of a retried 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 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 diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 4f7c219..2179c8f 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -12,6 +12,8 @@ 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) ++ [Bitbucket webhook events](bitbucket-webhook.md) ++ [GitHub webhook events](github-webhook.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) From 86195c49f69a9e5103ab8a2422ebd61a79f780a8 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 14 Sep 2020 17:15:32 +0000 Subject: [PATCH 068/156] General updates --- .../auth-and-access-control-using-tags.md | 8 +-- doc_source/build-env-ref-cmd.md | 2 +- doc_source/build-env-ref-env-vars.md | 6 +- doc_source/build-spec-ref.md | 39 +++++++---- doc_source/change-project-console.md | 4 +- doc_source/code-coverage-report.md | 6 +- doc_source/create-project-cli.md | 2 +- doc_source/create-project-console.md | 2 +- doc_source/create-project.md | 10 +-- doc_source/history.md | 2 +- doc_source/notice.md | 2 +- doc_source/report-group-test-cases.md | 2 +- doc_source/sample-bitbucket-pull-request.md | 2 +- doc_source/sample-build-badges.md | 4 +- .../sample-disable-artifact-encryption.md | 4 +- doc_source/sample-docker-custom-image.md | 2 +- doc_source/sample-github-enterprise.md | 4 +- doc_source/sample-github-pull-request.md | 68 ++++++++++--------- doc_source/sample-test-report-cli.md | 1 + doc_source/test-report-jasmine.md | 4 +- doc_source/test-report-jest.md | 2 +- doc_source/test-report-pytest.md | 2 +- doc_source/test-report-rspec.md | 2 +- doc_source/test-reporting.md | 1 + doc_source/troubleshooting.md | 11 ++- 25 files changed, 112 insertions(+), 80 deletions(-) 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/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md index 203beeb..e9119d3 100644 --- a/doc_source/build-env-ref-cmd.md +++ b/doc_source/build-env-ref-cmd.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-env-vars.md b/doc_source/build-env-ref-env-vars.md index c21bf91..a563bc7 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -42,7 +42,8 @@ An identifier for the version of a build's source code\. Its format depends on t + 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\. +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\. @@ -51,10 +52,11 @@ The value's format depends on the source repository\. + 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`\. +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`\)\. -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)\. +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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 5816ec3..c6d9861 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -294,17 +294,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 report file format\. If not specified, `JunitXml` is used\. The following test report file formats are supported: -+ `CucumberJson` -+ `JunitXml` -+ `NunitXml` -+ `TestNGXml` -+ `VisualStudioTrx` -The following code coverage report formats are supported: -+ `JaCoCoXml` -+ `SimpleCov` -+ `CloverXml` -+ `CoberturaXml` +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\. @@ -533,7 +546,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 @@ -555,7 +568,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\. diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index aeb1127..60ceda7 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -145,8 +145,8 @@ Choose to ignore SSL warnings while connecting to your GitHub Enterprise project 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" + - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 + - 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**\. diff --git a/doc_source/code-coverage-report.md b/doc_source/code-coverage-report.md index 327924a..b7d6988 100644 --- a/doc_source/code-coverage-report.md +++ b/doc_source/code-coverage-report.md @@ -14,10 +14,12 @@ Branch coverage measures how many branches your tests cover out of every possibl The following code coverage report file formats are supported: + JaCoCo XML -+ SimpleCov JSON ++ 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\. AWS 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\. @@ -39,7 +41,7 @@ To create a code coverage report, you run a build project that is configured wit jacoco-report: files: - 'test-results/jacoco-coverage-report.xml' - file-format: 'JaCoCoXml' + 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)\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 9db375a..0f82819 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -382,7 +382,7 @@ Set to `true` only if you plan to use this build project to build Docker images, 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& +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 5ddde50..6946c5d 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -169,7 +169,7 @@ Do one of the following: 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& +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` 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/history.md b/doc_source/history.md index 19c0d0c..645fde6 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -7,7 +7,7 @@ The following table describes the important changes to the documentation since t | Change | Description | Date | | --- |--- |--- | | [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 the execution of 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 | +| [Batch builds](#history) | CodeBuild now supports the execution of 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 | | [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 | diff --git a/doc_source/notice.md b/doc_source/notice.md index fa6b90b..59eb089 100644 --- a/doc_source/notice.md +++ b/doc_source/notice.md @@ -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\. 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/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index bceb099..2e0da95 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -24,7 +24,7 @@ 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. 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 **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/) diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index d610329..201eaee 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** @@ -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\. diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index c0ad8ed..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**\. @@ -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..3d68fc7 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -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-github-enterprise.md b/doc_source/sample-github-enterprise.md index 3cf44b7..e5f046d 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\. @@ -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\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 811ffe3..27ddc9b 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -11,49 +11,53 @@ We recommend that you use a filter group to specify which GitHub users can trigg 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. In **Project configuration**: - - 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**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub and then choose **Authorize**\. - - Choose **Repository in my GitHub account**\. - - 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. 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. 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 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: +1. Choose **Create build project**\. + +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. 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 **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** in the previous step\. + +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,9 +69,9 @@ 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\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 95ff6a1..0c34f41 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -17,6 +17,7 @@ You can use the CodeBuild API or the AWS CodeBuild console to access the test re + Cucumber JSON + JUnit XML + NUnit XML + + NUnit3 XML + TestNG XML + Visual Studio TRX diff --git a/doc_source/test-report-jasmine.md b/doc_source/test-report-jasmine.md index dfbd92a..96184d5 100644 --- a/doc_source/test-report-jasmine.md +++ b/doc_source/test-report-jasmine.md @@ -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..16c96b3 100644 --- a/doc_source/test-report-jest.md +++ b/doc_source/test-report-jest.md @@ -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..76c90c1 100644 --- a/doc_source/test-report-pytest.md +++ b/doc_source/test-report-pytest.md @@ -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..3b94737 100644 --- a/doc_source/test-report-rspec.md +++ b/doc_source/test-report-rspec.md @@ -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 045b3c1..5b8c084 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -6,6 +6,7 @@ The following test report file formats are supported: + Cucumber JSON + JUnit XML + NUnit XML ++ NUnit3 XML + TestNG XML + Visual Studio TRX diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 0cdd4b0..37ec0e0 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -31,6 +31,7 @@ Use the information in this topic to help you identify, diagnose, and address is + [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: BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE](#troubleshooting-windows-version-mismatch) ++ [Error: "Unable to verify JobWorker identity" when opening the CodeBuild console](#troubleshooting-unable-to-verify-jobworker) ## Apache Maven builds reference artifacts from the wrong repository @@ -496,4 +497,12 @@ BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE: Unable to pull customer's container i **Possible causes:** You have selected a Windows Server 2016 environment type \(`WINDOWS_CONTAINER`\), but selected a Windows Server 2019 image\. -**Recommended solutions:** Change the environment type to `WINDOWS_SERVER_2019_CONTAINER`\. \ No newline at end of file +**Recommended solutions:** Change the environment type to `WINDOWS_SERVER_2019_CONTAINER`\. + +## 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`\. \ No newline at end of file From bf67d7b8457be2ecbb0630b7f66e41cff57feace Mon Sep 17 00:00:00 2001 From: Steven Demurjian Jr Date: Thu, 24 Sep 2020 17:38:38 -0400 Subject: [PATCH 069/156] Fix typo in sample-runtime-versions.md --- doc_source/sample-runtime-versions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 536f666..a96adc7 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -7,7 +7,7 @@ ## 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\. + 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 if you use the Amazon Linux 2 standard image: ``` @@ -387,4 +387,4 @@ The build project in this example uses source code in the GitHub [AWS samples](h > echo "run some tests here" run some tests here - ``` \ No newline at end of file + ``` From 4dac1ba5d49ee4e18fcdfafd9c982ad520ddacbe Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 28 Sep 2020 18:19:45 +0000 Subject: [PATCH 070/156] General updates --- doc_source/batch-build-buildspec.md | 12 +++++++++++- doc_source/data-protection.md | 3 ++- doc_source/github-webhook.md | 12 ++++++------ doc_source/sample-github-pull-request.md | 12 +++++++++++- doc_source/sample-runtime-versions.md | 2 +- 5 files changed, 31 insertions(+), 10 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 7b03e20..42392d5 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -7,7 +7,7 @@ This topic contains the buildspec reference for batch build properties\. Optional mapping\. The batch build settings for the project\. batch/**fast\-fail** -Optional\. For build graphs, this property is not used and is always `true`\. +Optional\. `false` The default value\. All running builds will complete\. `true` @@ -46,11 +46,20 @@ The environment variables that will be present in the build environment\. See [e batch/build\-graph/**identifier** Required\. The identifier of the task\. +batch/build\-graph/**ignore\-failure** +Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. +`false` +The default value\. If one build task fails, the batch build will fail immediately\. +`true` +If one build task fails, the remaining build tasks will still run\. + The following is an example of a build graph buildspec entry: ``` batch: + fast-fail: false build-graph: + ignore-failure: true - identifier: linux_small env: compute-type: BUILD_GENERAL1_SMALL @@ -102,6 +111,7 @@ The following is an example of a build list buildspec entry: batch: fast-fail: false build-list: + ignore-failure: true - identifier: linux_small env: compute-type: BUILD_GENERAL1_SMALL diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 6d58469..76cbf4b 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -4,10 +4,11 @@ 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: + Use multi\-factor authentication \(MFA\) with each account\. -+ Use TLS to communicate with AWS resources\. ++ Use 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 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\. diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md index 6f0458d..73f8864 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -32,17 +32,17 @@ You can find the webhook payload in the webhook settings of your GitHub reposito ## Filter GitHub webhook events \(console\) - To use the AWS Management Console to filter webhook events: +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. 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. 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 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. 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\. +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*\. diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 27ddc9b..5e2299a 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -25,7 +25,17 @@ Choose **Repository in my GitHub account**\. **GitHub repository** Enter the URL for your GitHub 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 GitHub account** in the previous step\. +1. In **Primary source webhook events**, select the following\. This section is only available when 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\. + + 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\. 1. In **Environment**: **Environment image** diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index a96adc7..82812e4 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -387,4 +387,4 @@ The build project in this example uses source code in the GitHub [AWS samples](h > echo "run some tests here" run some tests here - ``` + ``` \ No newline at end of file From 2c2c4cc296f0b8d36a739945878819b69469bfd2 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 1 Oct 2020 22:07:04 +0000 Subject: [PATCH 071/156] General updates --- ...ntrol-iam-identity-based-access-control.md | 20 ++-- doc_source/batch-build-buildspec.md | 6 +- doc_source/report-create.md | 30 ++++-- doc_source/sample-bitbucket-pull-request.md | 92 ++++++++++++++----- doc_source/sample-efs.md | 10 +- 5 files changed, 114 insertions(+), 44 deletions(-) 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..e2d6f82 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,7 +81,7 @@ 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: @@ -180,7 +186,7 @@ The `AWSCodeBuildAdminAccess` policy contains the following policy statement: ### 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: @@ -261,7 +267,7 @@ The `AWSCodeBuildDeveloperAccess` policy contains the following policy statement ### 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: diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 42392d5..bfbbba8 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -49,7 +49,7 @@ Required\. The identifier of the task\. batch/build\-graph/**ignore\-failure** Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` -The default value\. If one build task fails, the batch build will fail immediately\. +The default value\. If one build task fails, the batch build will fail\. `true` If one build task fails, the remaining build tasks will still run\. @@ -101,7 +101,7 @@ Optional\. The identifier of the task\. batch/build\-list/**ignore\-failure** Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` -The default value\. If one build task fails, the batch build will fail immediately\. +The default value\. If one build task fails, the batch build will fail\. `true` If one build task fails, the remaining build tasks will still run\. @@ -131,7 +131,7 @@ The static properties apply to all build tasks\. batch/build\-matrix/static/**ignore\-failure** Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` -The default value\. If one build task fails, the batch build will fail immediately\. +The default value\. If one build task fails, the batch build will fail\. `true` If one build task fails, the remaining build tasks will still run\. batch/build\-matrix/static/**env** diff --git a/doc_source/report-create.md b/doc_source/report-create.md index eac2846..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/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 2e0da95..51709c4 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -24,46 +24,88 @@ 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. 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 **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. Choose **Use a repository in my account**\. You cannot use a webhook if you use a public 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**\. -**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**\. + +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. In **Source**: +**Source provider** +Choose **Bitbucket**\. Follow the instructions to connect \(or reconnect\) with Bitbucket and then choose **Authorize**\. +**Repository** +Choose **Repository in my GitHub 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\. +**Bitbucket repository** +Enter the URL for your Bitbucket repository\. + +1. In **Primary source webhook events**, select the following\. This section is only available when you chose **Repository in my Bitbucket account** in the previous step\. + + 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\. + +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\. + +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**: +**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\. 1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. ## Trigger a build with a Bitbucket webhook - For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code\. +For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code\. 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. 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. 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. On the Bitbucket webhooks page, choose **View request** to see a list of recent events\. +1. On the Bitbucket webhooks page, choose **View request** to see a list of recent events\. -1. Choose **View details** to see details about the response returned by CodeBuild\. It might look something like this: +1. Choose **View details** to see details about the response returned by CodeBuild\. It might look something like this: ``` - "response":"Webhook received and buld started: https://us-east-1.console.aws.amazon.com/codebuild/home..." + "response":"Webhook received and build started: https://us-east-1.console.aws.amazon.com/codebuild/home..." "statusCode":200 ``` -1. Navigate to the Bitbucket pull request page to see the status of the build\. \ 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-efs.md b/doc_source/sample-efs.md index d4d5c87..8555744 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -142,9 +142,13 @@ The following are errors you might encounter when setting up EFS with CodeBuild\ ### CLIENT\_ERROR: mounting '127\.0\.0\.1:/' failed\. permission denied -When using a custom EFS file system policy, you must first establish a trust relationship between EFS and CodeBuild by doing one of the following: -+ Add `codebuild.amazonaws.com` as a trusted service in the Principal in the EFS file system policy, -+ Add the `elasticfilesystem:ClientMount` action to the CodeBuild project service role policy\. +IAM authorization is not supported for mounting EFS with CodeBuild\. If you are using a custom 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 From 72ec00beda68dac6b6536ed6623ca438d84c6b8b Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 12 Oct 2020 15:52:23 +0000 Subject: [PATCH 072/156] General updates --- doc_source/batch-build-buildspec.md | 46 ++++---- doc_source/batch-build.md | 130 +++++++++++++++++++++-- doc_source/bitbucket-webhook.md | 8 +- doc_source/build-env-ref-env-vars.md | 3 + doc_source/build-spec-ref.md | 46 ++++---- doc_source/sample-build-notifications.md | 4 + doc_source/sample-docker.md | 5 +- 7 files changed, 181 insertions(+), 61 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index bfbbba8..42d1d82 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -59,22 +59,23 @@ The following is an example of a build graph buildspec entry: batch: fast-fail: false build-graph: - ignore-failure: true - - identifier: linux_small + - identifier: build1 env: compute-type: BUILD_GENERAL1_SMALL - - identifier: linux_medium + - identifier: build2 env: compute-type: BUILD_GENERAL1_MEDIUM depend-on: - - linux_small - - identifier: linux_large + - build1 + - identifier: build3 env: compute-type: BUILD_GENERAL1_LARGE depend-on: - - linux_medium + - build2 ``` +For more information, see [Build graph](batch-build.md#batch_build_graph)\. + ## `batch/build-list` Defines a *build list*\. A build list is used to define a number of tasks that run in parallel\. @@ -112,16 +113,18 @@ batch: fast-fail: false build-list: ignore-failure: true - - identifier: linux_small - env: - compute-type: BUILD_GENERAL1_SMALL - - identifier: windows_medium - env: - type: WINDOWS_CONTAINER - image: aws/codebuild/windows-base:2.0 - compute-type: BUILD_GENERAL1_MEDIUM + - identifier: linux_small + env: + compute-type: BUILD_GENERAL1_SMALL + - identifier: windows_medium + env: + type: WINDOWS_CONTAINER + image: aws/codebuild/windows-base:2.0 + compute-type: BUILD_GENERAL1_MEDIUM ``` +For more information, see [Build list](batch-build.md#batch_build_list)\. + ## `batch/build-matrix` Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. @@ -154,7 +157,7 @@ Optional\. The identifier of the image to use for the task\. See **Image identif batch/build\-matrix/dynamic/env/**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, \. -For example, if your build matrix has two images and three values for an environment variable, such as this: +The following is an example of a build matrix buildspec entry: ``` batch: @@ -176,15 +179,4 @@ batch: - VALUE3 ``` -CodeBuild will create six builds: -+ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE1` -+ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE2` -+ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE3` -+ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE1` -+ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE2` -+ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE3` - -Each build will have the following settings: -+ `ignore-failure` set to `false` -+ `env/type` set to `LINUX_CONTAINER` -+ `env/privileged`\-mode set to `true` \ No newline at end of file +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 index fc263ae..3e412fe 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -1,11 +1,129 @@ # Batch builds in AWS CodeBuild -AWS CodeBuild supports the execution of concurrent and coordinated builds of a project with *batch builds*\. 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) +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) ++ [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\. \ No newline at end of file ++ 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: + compute-type: BUILD_GENERAL1_SMALL + - identifier: build2 + env: + compute-type: BUILD_GENERAL1_MEDIUM + depend-on: + - build1 + - identifier: build3 + env: + compute-type: BUILD_GENERAL1_LARGE + 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 `linux_small` and `windows_medium` builds will be run in parallel\. + +``` +batch: + fast-fail: false + build-list: + ignore-failure: true + - identifier: linux_small + env: + compute-type: BUILD_GENERAL1_SMALL + - identifier: windows_medium + env: + type: WINDOWS_CONTAINER + image: aws/codebuild/windows-base:2.0 + compute-type: BUILD_GENERAL1_MEDIUM +``` + +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 that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. + +The following example shows a build matrix with two images and three values for an environment variable\. + +``` +batch: + build-matrix: + static: + ignore-failure: false + env: + type: LINUX_CONTAINER + privileged-mode: true + dynamic: + env: + image: + - aws/codebuild/amazonlinux2-x86_64-standard:3.0 + - aws/codebuild/windows-base:2.0 + variables: + MY_VAR: + - VALUE1 + - VALUE2 + - VALUE3 +``` + +In this example, CodeBuild creates six builds: ++ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE1` ++ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE2` ++ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE3` ++ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE1` ++ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE2` ++ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE3` + +Each build will have the following settings: ++ `ignore-failure` set to `false` ++ `env/type` set to `LINUX_CONTAINER` ++ `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)\. + +## 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 index 40433b4..42082f1 100644 --- a/doc_source/bitbucket-webhook.md +++ b/doc_source/bitbucket-webhook.md @@ -5,9 +5,15 @@ 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\. +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\. diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index a563bc7..e0f1ba5 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -70,6 +70,9 @@ The base reference name of the webhook event that triggers the current build\. F 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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index c6d9861..ceeb988 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -39,25 +39,25 @@ 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: @@ -68,8 +68,8 @@ batch: phases: install: - run-as: Linux-user-name - runtime-versions: + run\-as: Linux-user-name + runtime\-versions: runtime: version runtime: version commands: @@ -78,8 +78,8 @@ phases: finally: - command - command - pre_build: - run-as: Linux-user-name + pre\_build: + run\-as: Linux-user-name commands: - command - command @@ -87,15 +87,15 @@ phases: - command - command build: - run-as: Linux-user-name + run\-as: Linux-user-name commands: - command - command finally: - command - command - post_build: - run-as: Linux-user-name + post\_build: + run\-as: Linux-user-name commands: - command - command @@ -107,30 +107,30 @@ reports: files: - location - location - base-directory: location - discard-paths: no | yes - file-format: report-format + 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 + 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 diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 9674f7d..d811dfd 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -197,6 +197,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\. diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index edb7c4a..032255e 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -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) + - docker login -u AWS -p $(aws ecr get-login-password --region $AWS_DEFAULT_REGION) build: commands: - echo Build started on `date` From 9236e06fff6961c92d8de9e6631c2be6159d976c Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 15 Oct 2020 15:41:29 +0000 Subject: [PATCH 073/156] General updates --- doc_source/build-env-ref-env-vars.md | 15 ++++++++++----- doc_source/build-spec-ref.md | 27 ++++++++++++++++++++------- 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index e0f1ba5..10734c9 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -35,11 +35,16 @@ The identifier of the AWS KMS key that CodeBuild is using to encrypt the build o 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\_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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index ceeb988..e8f4527 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -190,13 +190,26 @@ If an environment variable with the same name is defined in multiple places, the + 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\. From b1321ea71ddd2724dbaf378385b346b75b3a4890 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 19 Oct 2020 23:36:49 +0000 Subject: [PATCH 074/156] General updates --- doc_source/sample-docker.md | 4 ++-- doc_source/sample-ecr.md | 2 +- doc_source/sample-private-registry.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 032255e..205f544 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -168,7 +168,7 @@ phases: pre_build: commands: - echo Logging in to Amazon ECR... - - docker login -u AWS -p $(aws ecr get-login-password --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` @@ -213,7 +213,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` diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index d42f267..3cd5ccf 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -130,7 +130,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", diff --git a/doc_source/sample-private-registry.md b/doc_source/sample-private-registry.md index 57b73d8..8e3ad43 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -18,7 +18,7 @@ ``` 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 ``` From 6c570f99215c72e798ad65fc800553f7256c0f8a Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 22 Oct 2020 19:59:58 +0000 Subject: [PATCH 075/156] General update --- doc_source/create-project-cli.md | 4 ++-- doc_source/project-sharing.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 0f82819..a1d9351 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -278,7 +278,7 @@ If `sourceVersion` is specified at the build level, then that version takes prec ### **artifacts** -Required\. A [ProjectArtifiacts](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: +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: @@ -316,7 +316,7 @@ Create a ZIP file that contains the build artifacts\. ### secondaryArtifacts -Optional\. An array of [ProjectArtifiacts](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\. +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 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: ``` { From 25103fe53b5fb96bb4deb442b92576736ada3f1f Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 23 Oct 2020 20:37:01 +0000 Subject: [PATCH 076/156] General updates --- doc_source/build-spec-ref.md | 10 +++++----- doc_source/create-project-console.md | 2 +- doc_source/history.md | 4 ++-- doc_source/monitoring-builds.md | 2 +- doc_source/sample-multi-in-out.md | 2 +- doc_source/sample-windows.md | 12 ++++++------ doc_source/test-report-jasmine.md | 2 +- doc_source/test-report-jest.md | 2 +- doc_source/use-proxy-server.md | 20 ++++++++++---------- doc_source/vpc-support.md | 2 +- 10 files changed, 29 insertions(+), 29 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index e8f4527..98e3a29 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -148,7 +148,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 @@ -267,28 +267,28 @@ If two specified runtimes conflict, the build fails\. For example, `android: 29` 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 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\. 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\. +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\. 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\. +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\. 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\. +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\. **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)\. diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 6946c5d..3e28490 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -225,7 +225,7 @@ For more information, see the [Buildspec reference](build-spec-ref.md)\. ## Batch configuration -You can run a group of builds as a single execution\. For more information, see [Batch builds in AWS CodeBuild](batch-build.md)\. +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\. diff --git a/doc_source/history.md b/doc_source/history.md index 645fde6..f8bb8a8 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -7,7 +7,7 @@ The following table describes the important changes to the documentation since t | Change | Description | Date | | --- |--- |--- | | [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 the execution of 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 | +| [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 | | [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 | @@ -43,7 +43,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 diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index 6b057fd..5506dc2 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)\. diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index c39dfaf..4e9dcf7 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)\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index dc87e64..33f8412 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 C\#, 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)\. @@ -41,11 +41,11 @@ 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. 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 C\# sample using the \.NET Framework, `CSharpHelloWorld.exe`, can be found in the `CSharpHelloWorld\bin\Debug` directory\. + + 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\. + + The runtime file for the C\# sample using \.NET Core, `HelloWorldSample.dll`, can be found in the `bin\Debug\netcoreapp3.1` directory\. ## Directory structure diff --git a/doc_source/test-report-jasmine.md b/doc_source/test-report-jasmine.md index 96184d5..5c55771 100644 --- a/doc_source/test-report-jasmine.md +++ b/doc_source/test-report-jasmine.md @@ -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\. ``` { diff --git a/doc_source/test-report-jest.md b/doc_source/test-report-jest.md index 16c96b3..dca5ecd 100644 --- a/doc_source/test-report-jest.md +++ b/doc_source/test-report-jest.md @@ -12,7 +12,7 @@ Add the [https://www.npmjs.com/package/jest-junit](https://www.npmjs.com/package 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\. ``` { diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index da4f2ae..8c31e53 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -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 @@ -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,7 @@ 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 +316,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 +337,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 +354,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/vpc-support.md b/doc_source/vpc-support.md index 7f49830..1eb59d9 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -63,7 +63,7 @@ Replace `us-east-1` with your Region\. 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*\. **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\. From c0d380613a1ff665fd68c0bbe25d9a2f6e50906d Mon Sep 17 00:00:00 2001 From: Alan <16951492+neurostream@users.noreply.github.com> Date: Sat, 24 Oct 2020 00:53:21 -0600 Subject: [PATCH 077/156] Update sample-bitbucket-pull-request.md the replaced bytes appear when these news ones were expected. --- doc_source/sample-bitbucket-pull-request.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 51709c4..5adfaca 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -34,7 +34,7 @@ Enter a name for this build project\. Build project names must be unique across **Source provider** Choose **Bitbucket**\. Follow the instructions to connect \(or reconnect\) with Bitbucket and then choose **Authorize**\. **Repository** -Choose **Repository in my GitHub account**\. +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\. @@ -108,4 +108,4 @@ For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when t "statusCode":200 ``` -1. Navigate to the Bitbucket pull request page to see the status of the build\. \ No newline at end of file +1. Navigate to the Bitbucket pull request page to see the status of the build\. From 68ede40684129e24d2d644abdd5473c1f7e61ec9 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 28 Oct 2020 22:28:32 +0000 Subject: [PATCH 078/156] General update --- doc_source/batch-build-buildspec.md | 6 +++--- doc_source/batch-build.md | 12 ++++++------ doc_source/build-env-ref-available.md | 21 ++------------------- doc_source/build-env-ref-compute-types.md | 4 ++-- doc_source/create-project-cli.md | 14 ++++++++++++-- doc_source/data-protection.md | 10 +++++----- doc_source/sample-bitbucket-pull-request.md | 2 +- doc_source/sample-windows.md | 10 ++++++---- doc_source/troubleshooting.md | 11 ----------- 9 files changed, 37 insertions(+), 53 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 42d1d82..b977c67 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -118,8 +118,8 @@ batch: compute-type: BUILD_GENERAL1_SMALL - identifier: windows_medium env: - type: WINDOWS_CONTAINER - image: aws/codebuild/windows-base:2.0 + type: WINDOWS_SERVER_2019_CONTAINER + image: aws/codebuild/windows-base:2019-1.0 compute-type: BUILD_GENERAL1_MEDIUM ``` @@ -171,7 +171,7 @@ batch: env: image: - aws/codebuild/amazonlinux2-x86_64-standard:3.0 - - aws/codebuild/windows-base:2.0 + - aws/codebuild/windows-base:2019-1.0 variables: MY_VAR: - VALUE1 diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index 3e412fe..6737a43 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -70,8 +70,8 @@ batch: compute-type: BUILD_GENERAL1_SMALL - identifier: windows_medium env: - type: WINDOWS_CONTAINER - image: aws/codebuild/windows-base:2.0 + type: WINDOWS_SERVER_2019_CONTAINER + image: aws/codebuild/windows-base:2019-1.0 compute-type: BUILD_GENERAL1_MEDIUM ``` @@ -95,7 +95,7 @@ batch: env: image: - aws/codebuild/amazonlinux2-x86_64-standard:3.0 - - aws/codebuild/windows-base:2.0 + - aws/codebuild/windows-base:2019-1.0 variables: MY_VAR: - VALUE1 @@ -107,9 +107,9 @@ In this example, CodeBuild creates six builds: + `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE1` + `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE2` + `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE3` -+ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE1` -+ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE2` -+ `aws/codebuild/windows-base:2.0` / `MY_VAR=VALUE3` ++ `aws/codebuild/windows-base:2019-1.0` / `MY_VAR=VALUE1` ++ `aws/codebuild/windows-base:2019-1.0` / `MY_VAR=VALUE2` ++ `aws/codebuild/windows-base:2019-1.0` / `MY_VAR=VALUE3` Each build will have the following settings: + `ignore-failure` set to `false` diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index b9f95da..070e228 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -10,13 +10,9 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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) | | 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 | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.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`\. +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)\. @@ -29,19 +25,6 @@ AWS CodeBuild manages the following Docker images that are available in the Code **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\. @@ -57,7 +40,7 @@ The base image of the Windows Server Core 2019 contains the following runtimes\. | 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\. +The base image of the Windows Server Core 2019 platform is 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)\. diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index ff90481..9416682 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -28,8 +28,8 @@ For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncomp | 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 | +| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | WINDOWS\_SERVER\_2019\_CONTAINER | +| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | WINDOWS\_SERVER\_2019\_CONTAINER | **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\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index a1d9351..13711a8 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -92,7 +92,7 @@ Modify the JSON data as follows and save your results\. ] }, "environment": { - "type": "WINDOWS_CONTAINER" | "LINUX_CONTAINER" | "LINUX_GPU_CONTAINER" | "ARM_CONTAINER" | "WINDOWS_SERVER_2019_CONTAINER", + "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": "", @@ -245,7 +245,17 @@ 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\. +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\. diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 76cbf4b..1105ae7 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -1,16 +1,16 @@ # 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\. We recommend TLS 1\.2 or later\. ++ 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 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\. 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*\. diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 5adfaca..55b187e 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -108,4 +108,4 @@ For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when t "statusCode":200 ``` -1. Navigate to the Bitbucket pull request page to see the status of the build\. +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-windows.md b/doc_source/sample-windows.md index 33f8412..d17bf4e 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -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 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,6 +41,8 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains } ``` +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 C\# sample using the \.NET Framework, `CSharpHelloWorld.exe`, can be found in the `CSharpHelloWorld\bin\Debug` directory\. + The runtime file for the F\# sample using the \.NET Framework, `FSharpHelloWorld.exe`, can be found in the `FSharpHelloWorld\bin\Debug` directory\. @@ -315,8 +317,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\* diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 37ec0e0..0003a48 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -30,7 +30,6 @@ 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: BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE](#troubleshooting-windows-version-mismatch) + [Error: "Unable to verify JobWorker identity" when opening the CodeBuild console](#troubleshooting-unable-to-verify-jobworker) ## Apache Maven builds reference artifacts from the wrong repository @@ -489,16 +488,6 @@ artifacts: **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: BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE - -**Issue:** When building, you receive an error similar to the following: - -BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE: Unable to pull customer's container image\. CannotPullContainerError: a Windows version 10\.0\.17763\-based image is incompatible with a 10\.0\.14393 host - -**Possible causes:** You have selected a Windows Server 2016 environment type \(`WINDOWS_CONTAINER`\), but selected a Windows Server 2019 image\. - -**Recommended solutions:** Change the environment type to `WINDOWS_SERVER_2019_CONTAINER`\. - ## 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\. From 80e9fcd4a24c55abeed21c537fd75cef862553cd Mon Sep 17 00:00:00 2001 From: Matt Date: Thu, 5 Nov 2020 10:58:44 -0500 Subject: [PATCH 079/156] Remove duplicate line --- doc_source/troubleshooting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 0003a48..37041d3 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -181,7 +181,6 @@ pre_build: **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\) ## Earlier commands in buildspec files are not recognized by later commands @@ -494,4 +493,4 @@ artifacts: **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`\. \ No newline at end of file +**Recommended solution:** Change any custom IAM role tags that have the key `jobId` to have a different key, such as `jobIdentifier`\. From 632d569e2819bbdb92bf56b71a504e6da5762dc9 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 5 Nov 2020 16:57:58 +0000 Subject: [PATCH 080/156] General update --- doc_source/build-env-ref-available.md | 7 +++++-- doc_source/troubleshooting.md | 19 ++++++++++--------- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 070e228..095124a 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -39,8 +39,11 @@ The base image of the Windows Server Core 2019 contains the following runtimes\. | python | 3\.8\.3 | | ruby | 2\.7 | -**Note** -The base image of the Windows Server Core 2019 platform is available in the US East \(N\. Virginia\), US East \(Ohio\), US West \(Oregon\), and Europe \(Ireland\) Regions only\. +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\) 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)\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 37041d3..93d90cf 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -9,7 +9,7 @@ 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 find and select the base image of the Windows Server Core 2016 platform](#windows-image-not-available) ++ [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) @@ -172,16 +172,17 @@ pre_build: **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 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 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 @@ -493,4 +494,4 @@ artifacts: **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`\. +**Recommended solution:** Change any custom IAM role tags that have the key `jobId` to have a different key, such as `jobIdentifier`\. \ No newline at end of file From 1c831e10b4a02f01e5dd4e1ebd36924035af2082 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 5 Nov 2020 23:58:19 +0000 Subject: [PATCH 081/156] General update --- doc_source/troubleshooting.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 93d90cf..59b1615 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -212,12 +212,14 @@ pre_build: + 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)\. ++ 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 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\. ++ 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" From 40fab9ab26e16408e43b1e626799e7ec89dffc8a Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 12 Nov 2020 23:12:46 +0000 Subject: [PATCH 082/156] General update --- doc_source/change-project-console.md | 2 +- doc_source/create-project-cli.md | 2 +- doc_source/create-project-console.md | 2 +- doc_source/how-to-create-pipeline.md | 4 +- doc_source/index.md | 2 +- doc_source/sample-docker-custom-image.md | 4 +- doc_source/troubleshooting.md | 25 +++--- doc_source/use-codebuild-agent.md | 104 ++++++++++++++++------- 8 files changed, 95 insertions(+), 50 deletions(-) diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 60ceda7..a44189e 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -145,7 +145,7 @@ Choose to ignore SSL warnings while connecting to your GitHub Enterprise project 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 + - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 13711a8..14b70f6 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -392,7 +392,7 @@ Set to `true` only if you plan to use this build project to build Docker images, 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 +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 3e28490..ff1f3fd 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -169,7 +169,7 @@ Do one of the following: 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 +- nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 16091b7..9df1641 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -391,7 +391,7 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui 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& + - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` @@ -529,7 +529,7 @@ If you enable webhooks for a CodeBuild project, and the project is used as a bui 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& + - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" ``` diff --git a/doc_source/index.md b/doc_source/index.md index fdd1947..a2a749d 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -75,7 +75,7 @@ Amazon's trademarks and trade dress may not be used in + [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 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) diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index 3d68fc7..be05657 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\.\) ``` { @@ -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/troubleshooting.md b/doc_source/troubleshooting.md index 59b1615..50ce621 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -207,19 +207,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)\. -+ 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\. +***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\. -+ 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)\. +***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" diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 9ac2176..6887ecf 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -1,63 +1,107 @@ -# 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\. You can also subscribe to notifications about new versions of the agent\. -## Test and debug on a local machine with the CodeBuild agent +## Prerequisites - You can use the AWS CodeBuild agent to test and debug builds on a local machine\. +Before you begin, you need to do the following: ++ Install Git on your local machine\. ++ Install and setup [Docker](https://www.docker.com/) on your local machine\. -**To use the agent** +## Setup the build image -1. Download the [codebuild\.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) script\. +You only need to set up the build image the first time you run the agent, or when the image has changed\. -1. Run the script and specify your container images and output directory: +**To set up the build image** + +1. Clone the CodeBuild image repo: ``` - codebuild_build.sh [-i image_name] [-a artifact_output_directory] [options] + $ git clone https://github.com/aws/aws-codebuild-docker-images.git ``` - 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: +1. Build the image\. For this example, use the `aws/codebuild/standard:4.0` image\. This will take several minutes\. -``` -docker inspect amazon/aws-codebuild-local -``` + ``` + $ cd aws-codebuild-docker-images/ubuntu/standard/4.0 + $ docker build -t aws/codebuild/standard:4.0 . + ``` -## Receive notifications for new CodeBuild agent versions +1. Run the following Docker command to download the local CodeBuild agent\.: + + ``` + $ docker pull amazon/aws-codebuild-local:latest --disable-content-trust=false + ``` - 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\. +1. 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: -**To subscribe to the CodeBuild agent notifications** + ``` + 78f5c1a205604c39cd8c797fd8447f590428c0908ba1fbdbd3dcf8712af5e325 + ``` -1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home)\. + You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: -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\. + ``` + $ docker inspect amazon/aws-codebuild-local + ``` -1. In the navigation pane, choose **Subscriptions**\. +## Run the CodeBuild agent -1. Choose **Create subscription**\. +**To run the CodeBuild agent** -1. In **Create subscription**: +1. Change to the directory that contains your build project source\. - For **Topic ARN**, use the following Amazon Resource Name \(ARN\): +1. Download the [codebuild\_build\.sh](https://github.com/aws/aws-codebuild-docker-images/blob/master/local_builds/codebuild_build.sh) script: ``` - arn:aws:sns:us-east-1:850632864840:AWS-CodeBuild-Local-Agent-Updates + $ 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: + ``` + $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a + ``` + + 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 know 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 From bf9a40dd9b00246c7c5030d724a61bcb9da9eb29 Mon Sep 17 00:00:00 2001 From: Mike Dalrymple Date: Tue, 17 Nov 2020 07:16:10 -0800 Subject: [PATCH 083/156] fix artifacts example The example as written does not work. The [AWS CodeBuild specification](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) provides a better example and this is a partial copy of that. --- doc_source/sample-pipeline-multi-input-output.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc_source/sample-pipeline-multi-input-output.md b/doc_source/sample-pipeline-multi-input-output.md index cfbab88..96bc530 100644 --- a/doc_source/sample-pipeline-multi-input-output.md +++ b/doc_source/sample-pipeline-multi-input-output.md @@ -117,6 +117,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 @@ -128,4 +130,4 @@ An AWS CodeBuild project can take more than one input source\. It can also creat - source2_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 + 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*\. From 4846a326fd9167f5461b653f3b56c04cce9b30fd Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 17 Nov 2020 18:10:26 +0000 Subject: [PATCH 084/156] General update --- doc_source/sample-pipeline-multi-input-output.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc_source/sample-pipeline-multi-input-output.md b/doc_source/sample-pipeline-multi-input-output.md index 96bc530..e8401be 100644 --- a/doc_source/sample-pipeline-multi-input-output.md +++ b/doc_source/sample-pipeline-multi-input-output.md @@ -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 @@ -118,7 +117,7 @@ An AWS CodeBuild project can take more than one input source\. It can also creat artifacts: files: - - **/* + - '**/*' secondary-artifacts: artifact1: base-directory: $CODEBUILD_SRC_DIR @@ -130,4 +129,4 @@ An AWS CodeBuild project can take more than one input source\. It can also creat - source2_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*\. + 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 From 3f57275d3415b91d22dac2df079c68f23a108b5c Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 18 Nov 2020 16:24:10 +0000 Subject: [PATCH 085/156] General updates --- doc_source/vpc-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index 1eb59d9..962b300 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -61,7 +61,7 @@ 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 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\. From 637ee1f360c778104e7b4c1aff0910f729513738 Mon Sep 17 00:00:00 2001 From: Gert Leenders Date: Sun, 22 Nov 2020 11:48:16 +0100 Subject: [PATCH 086/156] Update session-manager.md The extra note will be a timesaver for some and will prevent unnecessary support cases. as well. --- doc_source/session-manager.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md index 682029b..989a3e6 100644 --- a/doc_source/session-manager.md +++ b/doc_source/session-manager.md @@ -134,7 +134,8 @@ Your local machine must have the Session Manager plugin installed for this proce aws codebuild batch-get-builds --ids --region ``` -1. Copy the `sessionTarget` property value\. +1. Copy the `sessionTarget` property value\. Note: `sessionTarget` is only availabe if output is `json` or `table`. If output is set to `text` look for `DEBUGSESSION` instead. If the proprty is missing from the output then update your CLI to a more recent version. + 1. Use the following command to connect to the build container\. @@ -150,4 +151,4 @@ After you finish examining the build container, issue the codebuild\-resume comm ``` $ codebuild-resume -``` \ No newline at end of file +``` From 808e8becbe96dee89f318cba7d7f17287882ebd2 Mon Sep 17 00:00:00 2001 From: Gert Leenders Date: Sun, 22 Nov 2020 14:11:31 +0100 Subject: [PATCH 087/156] Update session-manager.md Fixed two typo's --- doc_source/session-manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md index 989a3e6..b43dd14 100644 --- a/doc_source/session-manager.md +++ b/doc_source/session-manager.md @@ -134,7 +134,7 @@ Your local machine must have the Session Manager plugin installed for this proce aws codebuild batch-get-builds --ids --region ``` -1. Copy the `sessionTarget` property value\. Note: `sessionTarget` is only availabe if output is `json` or `table`. If output is set to `text` look for `DEBUGSESSION` instead. If the proprty is missing from the output then update your CLI to a more recent version. +1. Copy the `sessionTarget` property value\. Note: `sessionTarget` is only available if output is `json` or `table`. If output is set to `text` look for `DEBUGSESSION` instead. If the property is missing from the output then update your CLI to a more recent version. 1. Use the following command to connect to the build container\. From 2b685fb686901de6134869f86599f1b11c3d3e59 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 4 Dec 2020 17:47:37 +0000 Subject: [PATCH 088/156] General update --- doc_source/build-env-ref-available.md | 2 +- doc_source/sample-windows.md | 6 +++--- doc_source/session-manager.md | 9 ++++----- doc_source/use-codebuild-agent.md | 2 +- 4 files changed, 9 insertions(+), 10 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 095124a..f40020a 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -30,7 +30,7 @@ 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 | +| dotnet | 3\.1\.4045\.0 | | golang | 1\.14 | | nodejs | 12\.18 | | java | corretto11 | diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index d17bf4e..d30d115 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -47,7 +47,7 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains + The runtime file for the C\# sample using the \.NET Framework, `CSharpHelloWorld.exe`, can be found in the `CSharpHelloWorld\bin\Debug` directory\. + 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\. - + The runtime file for the C\# sample using \.NET Core, `HelloWorldSample.dll`, can be found in the `bin\Debug\netcoreapp3.1` directory\. + + The runtime file for the C\# sample using \.NET Core, `HelloWorldSample.dll`, can be found in the `bin\Debug\net5.0` directory\. ## Directory structure @@ -1057,7 +1057,7 @@ phases: - dotnet build artifacts: files: - - .\bin\Debug\netcoreapp3.1\* + - .\bin\Debug\net5.0\* ``` `HelloWorldSample.csproj` \(in `(root directory name)` @@ -1066,7 +1066,7 @@ artifacts: Exe - netcoreapp3.1 + net5.0 ``` diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md index b43dd14..a1f36b6 100644 --- a/doc_source/session-manager.md +++ b/doc_source/session-manager.md @@ -128,14 +128,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\. Note: `sessionTarget` is only available if output is `json` or `table`. If output is set to `text` look for `DEBUGSESSION` instead. If the property is missing from the output then update your CLI to a more recent version. - +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\. @@ -151,4 +150,4 @@ After you finish examining the build container, issue the codebuild\-resume comm ``` $ codebuild-resume -``` +``` \ No newline at end of file diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 6887ecf..213492c 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -36,7 +36,7 @@ You only need to set up the build image the first time you run the agent, or whe 1. 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 + 948390fe21cd700f7c8b8c64ee89faf7aeca8ab87cd9dac4ba6c853a35817ae3 ``` You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: From 8271b66eea5f77940f58c616d2d7ce78037cef27 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 11 Dec 2020 18:20:23 +0000 Subject: [PATCH 089/156] General updates --- ...nd-access-control-permissions-reference.md | 5 + doc_source/build-spec-ref.md | 25 ++-- doc_source/change-project-console.md | 2 + doc_source/concepts.md | 4 + doc_source/getting-started-cli-next-steps.md | 2 + doc_source/getting-started-cli-output.md | 2 + .../getting-started-next-steps-console.md | 2 + doc_source/getting-started-output-console.md | 2 + doc_source/github-webhook.md | 2 + doc_source/how-to-create-pipeline.md | 10 +- doc_source/how-to-integrate-config.md | 6 +- doc_source/notification-rule-create.md | 2 + doc_source/planning.md | 4 +- doc_source/sample-build-notifications.md | 30 ++++- doc_source/sample-codedeploy.md | 113 ++++++++--------- doc_source/sample-docker-custom-image.md | 4 +- doc_source/sample-docker.md | 4 +- doc_source/sample-ecr.md | 4 +- doc_source/sample-efs.md | 4 + doc_source/sample-elastic-beanstalk.md | 114 +++++++++--------- doc_source/sample-runtime-versions.md | 34 +++--- doc_source/sample-windows.md | 66 +++++----- .../test-report-group-create-buildspec.md | 3 +- doc_source/test-view-reports.md | 2 + doc_source/troubleshooting.md | 2 + doc_source/update-report-group-cli.md | 2 +- doc_source/use-codebuild-agent.md | 4 +- doc_source/use-proxy-server.md | 2 + doc_source/view-build-details.md | 4 + doc_source/view-project-details.md | 2 + doc_source/vpc-support.md | 4 + doc_source/welcome.md | 8 ++ 32 files changed, 285 insertions(+), 189 deletions(-) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 8e7687e..057ac08 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -66,6 +66,11 @@ CreateWebhook Required to create a webhook\. **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\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 98e3a29..7df245d 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -407,12 +407,13 @@ 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-build1 +│ └── my-file1.txt +└── my-build2 + ├── my-file2.txt + └── my-subdirectory + └── my-file3.txt ``` And for the following `artifacts` sequence: @@ -425,8 +426,9 @@ artifacts: The following subdirectory and file would be included in the build output artifact: ``` -my-subdirectory - `-- my-file3.txt +. +└── my-subdirectory + └── my-file3.txt ``` While for the following `artifacts` sequence: @@ -440,9 +442,10 @@ artifacts: The following files would be included in the build output artifact: ``` -|-- my-file1.txt -|-- my-file2.txt -`-- my-file3.txt +. +├── my-file1.txt +├── my-file2.txt +└── my-file3.txt ``` artifacts/**secondary\-artifacts** diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index a44189e..99777f6 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -228,6 +228,8 @@ If you leave **Encryption key** blank, CodeBuild uses the AWS\-managed CMK for A **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**: 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/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..f7b581e 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\. 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..d9f0c7a 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\. diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md index 73f8864..ca85456 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -32,6 +32,8 @@ You can find the webhook payload in the webhook settings of your GitHub reposito ## 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\. diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 9df1641..5c97a58 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -356,9 +356,13 @@ This procedure shows you how to add a build action in a build stage between the 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\. +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**\. @@ -499,6 +503,8 @@ This procedure shows you how to add a test action inside of a test stage between 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**\. @@ -568,6 +574,8 @@ To store and retrieve sensitive values, we recommend your build commands use the 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\. diff --git a/doc_source/how-to-integrate-config.md b/doc_source/how-to-integrate-config.md index 1468894..8dcf61f 100644 --- a/doc_source/how-to-integrate-config.md +++ b/doc_source/how-to-integrate-config.md @@ -31,9 +31,13 @@ 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\. +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. Choose **Look up**\. 1. After the list of CodeBuild projects is added, choose the CodeBuild project name link in the **Config timeline** column\. 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 cf4f02a..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) diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index d811dfd..52d1325 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,13 @@ For more information, see [Editing customer managed policies](https://docs.aws.a } ``` - Compare your results: + 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\. @@ -244,16 +256,24 @@ 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`: + 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: + 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 CodeBuild directly](how-to-run.md)\. diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md index 0703291..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)\. diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md index be05657..8bea6e3 100644 --- a/doc_source/sample-docker-custom-image.md +++ b/doc_source/sample-docker-custom-image.md @@ -57,8 +57,8 @@ This sample assumes this directory structure\. ``` (root directory name) - |-- buildspec.yml - `-- Dockerfile +├── buildspec.yml +└── Dockerfile ``` ## Files diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md index 205f544..3a6e0bc 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -151,8 +151,8 @@ This sample assumes this directory structure\. ``` (root directory name) - |-- buildspec.yml - `-- Dockerfile +├── buildspec.yml +└── Dockerfile ``` ## Files diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 3cd5ccf..8b0f7c9 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -148,8 +148,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 8555744..4b01715 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\. @@ -125,6 +127,8 @@ 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\. diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 49e8aff..0432d8b 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 `my-web-app.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)\. @@ -20,19 +20,19 @@ In this section, you use Maven to produce the source code\. Later, you use CodeB 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 + . + └── my-web-app + ├── 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 `my-web-app` directory\. In the `.ebextensions` subdirectory, create a file named `fix-path.config` with this content\. ``` container_commands: @@ -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 `my-web-app` directory\. ``` version: 0.2 @@ -75,25 +75,25 @@ 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 + . + └── my-web-app + ├── .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\. **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 `my-web-app`, just the directories and files in `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 `my-web-app` to the ZIP file, just the directories and files in `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*\. ### Step a2: Create the build project and run the build @@ -164,25 +164,25 @@ In this step, you create and add a buildspec file to the code you created in [Cr 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 + . + └── my-web-app + ├── .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\. **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 `my-web-app`, just the directories and files in `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 `my-web-app` to the ZIP file, just the directories and files in `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*\. ### Step b2: Create a build project @@ -271,23 +271,25 @@ 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 + . + └── my-web-app + ├── .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\. diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 82812e4..76b7dcd 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -90,16 +90,16 @@ ``` (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\. @@ -313,13 +313,13 @@ The build project in this example uses source code in the GitHub [AWS samples](h 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\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index d30d115..d0d126a 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -7,6 +7,8 @@ Running these samples might result in charges to your AWS account\. These includ ## Running the samples + + **To run these samples** 1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or a CodeCommit or GitHub repository\. @@ -57,56 +59,56 @@ These samples assume the following directory structures\. ``` (root directory name) - |-- buildspec.yml - |-- CSharpHelloWorld.sln - `-- CSharpHelloWorld - |-- App.config - |-- CSharpHelloWorld.csproj - |-- Program.cs - `-- Properties - `-- AssemblyInfo.cs +├── 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 +├── 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 +├── HelloWorldSample.csproj +└── Program.cs ``` ## Files 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-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/troubleshooting.md b/doc_source/troubleshooting.md index 50ce621..1d87b8c 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -341,6 +341,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`\. diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md index ef42efb..9aacc11 100644 --- a/doc_source/update-report-group-cli.md +++ b/doc_source/update-report-group-cli.md @@ -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/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 213492c..d2ae45f 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -104,4 +104,6 @@ You can subscribe to Amazon SNS notifications so you know when new versions of t 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 8c31e53..b18506c 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -306,6 +306,8 @@ sudo tail -f /var/log/squid/access.log ## Run a package manager and other tools 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\. 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-project-details.md b/doc_source/view-project-details.md index 4738c9f..77e689e 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: ``` diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index 962b300..f584360 100644 --- a/doc_source/vpc-support.md +++ b/doc_source/vpc-support.md @@ -33,8 +33,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*\. diff --git a/doc_source/welcome.md b/doc_source/welcome.md index 2bde9c8..8417428 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -19,14 +19,22 @@ For more information, see [AWS CodeBuild](https://aws.amazon.com/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 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)\. From 975103bd8bbc98bd5cd287729063114a2ee8be13 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 16 Dec 2020 23:01:52 +0000 Subject: [PATCH 090/156] General updates --- doc_source/build-caching.md | 2 +- doc_source/history.md | 2 +- doc_source/how-to-create-pipeline-add-test.md | 84 +++ doc_source/how-to-create-pipeline-add.md | 100 ++++ doc_source/how-to-create-pipeline-cli.md | 150 +++++ doc_source/how-to-create-pipeline-console.md | 106 ++++ doc_source/how-to-create-pipeline.md | 540 +----------------- doc_source/index.md | 4 + doc_source/run-build-cli.md | 2 +- doc_source/sample-elastic-beanstalk.md | 2 +- doc_source/sample-test-report-cli.md | 105 ++-- doc_source/setting-up.md | 4 +- 12 files changed, 504 insertions(+), 597 deletions(-) create mode 100644 doc_source/how-to-create-pipeline-add-test.md create mode 100644 doc_source/how-to-create-pipeline-add.md create mode 100644 doc_source/how-to-create-pipeline-cli.md create mode 100644 doc_source/how-to-create-pipeline-console.md diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 230181e..9a5b0e8 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -11,7 +11,7 @@ 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 and 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 diff --git a/doc_source/history.md b/doc_source/history.md index f8bb8a8..f8b77cc 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -79,7 +79,7 @@ The following table describes important changes in each release of the *AWS Code | 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 | +| 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 | 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 5c97a58..a67021a 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -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)\. @@ -54,530 +47,9 @@ For CodeDeploy, see the [AWS CodeDeploy sample](sample-codedeploy.md) in this gu 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-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\. - -## 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-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. 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=overlay2 & - - 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-console.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. 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=overlay2 & - - 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/index.md b/doc_source/index.md index a2a749d..fcfc4e8 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -179,6 +179,10 @@ Amazon's trademarks and trade dress may not be used in + [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) diff --git a/doc_source/run-build-cli.md b/doc_source/run-build-cli.md index b2c9d6b..0b41d78 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: diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 0432d8b..5035040 100644 --- a/doc_source/sample-elastic-beanstalk.md +++ b/doc_source/sample-elastic-beanstalk.md @@ -222,7 +222,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\. diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 0c34f41..efa3b2d 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -45,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\. @@ -79,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" } @@ -99,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 @@ -114,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" @@ -149,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\. @@ -194,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, @@ -228,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\. @@ -246,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/setting-up.md b/doc_source/setting-up.md index 83e68f8..83dca49 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -219,8 +219,8 @@ 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) ++ [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\. From c63d40b65a6434fc10ee6d71464f7e106a4b95db Mon Sep 17 00:00:00 2001 From: Turkhan Date: Wed, 23 Dec 2020 15:14:51 +0200 Subject: [PATCH 091/156] Update getting-started-cli-create-build-project.md Fix docker image tag --- doc_source/getting-started-cli-create-build-project.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index b988cd7..5a49f2e 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -47,7 +47,7 @@ For this build environment, you instruct CodeBuild to use a Docker image that co + 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`, `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`\)\. @@ -109,4 +109,4 @@ An IAM user in your AWS account with the `AWSCodeBuildAdminAccess`, `AmazonS3Rea ## Next step -[Step 6: Run the build](getting-started-cli-run-build.md) \ No newline at end of file +[Step 6: Run the build](getting-started-cli-run-build.md) From 23037a5d81b6902e55d544ca109b4870f59824ea Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 23 Dec 2020 16:26:21 +0000 Subject: [PATCH 092/156] General updates --- doc_source/access-tokens.md | 231 ++++++++++++++++++ doc_source/build-caching.md | 36 +-- doc_source/change-project-console.md | 5 + doc_source/create-project-cli.md | 3 +- doc_source/create-project-console.md | 5 + ...etting-started-cli-create-build-project.md | 6 +- doc_source/index.md | 2 +- doc_source/sample-access-tokens.md | 137 ----------- doc_source/security.md | 3 +- doc_source/trigger-create.md | 12 +- doc_source/triggers-edit.md | 10 +- doc_source/troubleshooting.md | 15 +- doc_source/use-case-based-samples.md | 3 - 13 files changed, 298 insertions(+), 170 deletions(-) create mode 100644 doc_source/access-tokens.md delete mode 100644 doc_source/sample-access-tokens.md 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/build-caching.md b/doc_source/build-caching.md index 9a5b0e8..22191b5 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,22 +11,22 @@ 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 and 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\. +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** @@ -37,22 +37,22 @@ The `ARM_CONTAINER` and `LINUX_GPU_CONTAINER` environment types and the `BUILD_G + [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 +70,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: diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 99777f6..1044a03 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -63,6 +63,8 @@ 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\. + 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)\. + **Note** The status of a build triggered by a webhook is always reported to your source provider\. @@ -92,6 +94,8 @@ 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\. + 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)\. + **Note** The status of a build triggered by a webhook is always reported to your source provider\. @@ -121,6 +125,7 @@ Select 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)\. The status of a build triggered by a webhook is always reported to your source provider\. **Insecure SSL** diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 14b70f6..f599874 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -227,7 +227,8 @@ 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\. +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`\. diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index ff1f3fd..b9e3d7d 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -83,6 +83,8 @@ 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\. +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)\. + **Note** The status of a build triggered by a webhook is always reported to your source provider\. @@ -112,6 +114,8 @@ 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\. +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)\. + **Note** The status of a build triggered by a webhook is always reported to your source provider\. @@ -141,6 +145,7 @@ Select 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)\. The status of a build triggered by a webhook is always reported to your source provider\. **Insecure SSL** diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 5a49f2e..140858e 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,7 +46,7 @@ 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`, `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)\. @@ -109,4 +109,4 @@ An IAM user in your AWS account with the `AWSCodeBuildAdminAccess`, `AmazonS3Rea ## Next step -[Step 6: Run the build](getting-started-cli-run-build.md) +[Step 6: Run the build](getting-started-cli-run-build.md) \ No newline at end of file diff --git a/doc_source/index.md b/doc_source/index.md index fcfc4e8..c87bc4b 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -44,7 +44,6 @@ Amazon's trademarks and trade dress may not be used in + [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) @@ -172,6 +171,7 @@ 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) 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/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/trigger-create.md b/doc_source/trigger-create.md index 0eefff9..b3006f8 100644 --- a/doc_source/trigger-create.md +++ b/doc_source/trigger-create.md @@ -1,8 +1,10 @@ # 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\. + +You create a trigger after you create a project\. **To create a trigger** @@ -36,4 +38,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 1d87b8c..4dd7d6f 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -31,6 +31,7 @@ Use the information in this topic to help you identify, diagnose, and address is + [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) ++ [Accessing GitHub metadata in locally cached builds](#troubleshooting-github-metadata) ## Apache Maven builds reference artifacts from the wrong repository @@ -499,4 +500,16 @@ artifacts: **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`\. \ No newline at end of file +**Recommended solution:** Change any custom IAM role tags that have the key `jobId` to have a different key, such as `jobIdentifier`\. + +## 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 +``` \ 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 b651482..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\. From 090db8a48a0a0ba6c5f60f0111f36410661ef1d9 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 4 Jan 2021 21:20:30 +0000 Subject: [PATCH 093/156] General update --- doc_source/sample-efs.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index 4b01715..cff6303 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -100,15 +100,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 buildspec commands into the editor\. Replace `` with the identifier you entered in step 17\. Use capital letters \(for example, `CODEBUILD_MY_EFS`\)\. ``` version: 0.2 @@ -118,7 +129,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\. From fc471ad19575e8ee20e1a59564df631d47a86fda Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 8 Jan 2021 16:31:56 +0000 Subject: [PATCH 094/156] General update --- doc_source/batch-build-buildspec.md | 129 ++++++++------ doc_source/batch-build.md | 18 +- doc_source/sample-windows.md | 262 +--------------------------- doc_source/troubleshooting.md | 9 + 4 files changed, 92 insertions(+), 326 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index b977c67..904f391 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -22,31 +22,33 @@ The contents of the `batch` property varies based on the type of batch build bei ## `batch/build-graph` -Defines a *build graph*\. A build graph defines a set of tasks that have dependencies on other tasks in the batch\. +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)\. -batch/build\-graph/**buildspec** +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\. -batch/build\-graph/**depend\-on** -An array of task identifiers that this task depends on\. This task will not run until these tasks are completed\. +**depend\-on** +Optional\. An array of task identifiers that this task depends on\. This task will not run until these tasks are completed\. -batch/build\-graph/**env** -Optional\. The build environment overrides for the task\. -batch/build\-graph/env/**compute\-type** +**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\. -batch/build\-graph/env/**image** +**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\. -batch/build\-graph/env/**privileged\-mode** -Optional\. 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`\. -batch/build\-graph/env/**type** +**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\. -batch/build\-graph/env/**variables** +**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, \. -batch/build\-graph/**identifier** -Required\. The identifier of the task\. - -batch/build\-graph/**ignore\-failure** +**ignore\-failure** Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` The default value\. If one build task fails, the batch build will fail\. @@ -78,28 +80,33 @@ For more information, see [Build graph](batch-build.md#batch_build_graph)\. ## `batch/build-list` -Defines a *build list*\. A build list is used to define a number of tasks that run in parallel\. +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\. -batch/build\-list/**buildspec** +**buildspec** Optional\. The path and file name of the buildspec file to use for this task\. -batch/build\-list/**env** -Optional\. The build environment overrides for the task\. -batch/build\-list/env/**compute\-type** +**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\. -batch/build\-list/env/**image** +**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\. -batch/build\-list/env/**privileged\-mode** -Optional\. 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`\. -batch/build\-list/env/**type** +**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\. -batch/build\-list/env/**variables** +**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, \. -batch/build\-list/**identifier** -Optional\. The identifier of the task\. - -batch/build\-list/**ignore\-failure** +**ignore\-failure** Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` The default value\. If one build task fails, the batch build will fail\. @@ -112,50 +119,60 @@ The following is an example of a build list buildspec entry: batch: fast-fail: false build-list: - ignore-failure: true - - identifier: linux_small - env: - compute-type: BUILD_GENERAL1_SMALL - - identifier: windows_medium - env: - type: WINDOWS_SERVER_2019_CONTAINER - image: aws/codebuild/windows-base:2019-1.0 - compute-type: BUILD_GENERAL1_MEDIUM + - identifier: linux_small + env: + compute-type: BUILD_GENERAL1_SMALL + ignore-failure: true + - identifier: windows_medium + env: + type: WINDOWS_SERVER_2019_CONTAINER + image: aws/codebuild/windows-base:2019-1.0 + compute-type: BUILD_GENERAL1_MEDIUM ``` For more information, see [Build list](batch-build.md#batch_build_list)\. ## `batch/build-matrix` -Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. +Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. For more information, see [Build matrix](batch-build.md#batch_build_matrix)\. -batch/build\-matrix/**static** +**static** The static properties apply to all build tasks\. -batch/build\-matrix/static/**ignore\-failure** +**ignore\-failure** Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. `false` The default value\. If one build task fails, the batch build will fail\. `true` If one build task fails, the remaining build tasks will still run\. -batch/build\-matrix/static/**env** -Optional\. The build environment overrides for the task\. -batch/build\-matrix/static/env/**privileged\-mode** +**env** +Optional\. The build environment overrides for all tasks\. +**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, \. +**privileged\-mode** Optional\. 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`\. -batch/build\-matrix/static/env/**type** +**type** Optional\. 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\. -batch/build\-matrix/**dynamic** +**dynamic** The dynamic properties define the build matrix\. -batch/build\-matrix/dynamic/**buildspec** -Optional\. The path and file name of the buildspec file to use for this task\. -batch/build\-matrix/dynamic/**env** +**buildspec** +Optional\. An array that contains the path and file name of the buildspec files to use for these tasks\. +**env** Optional\. The build environment overrides for the task\. -batch/build\-matrix/dynamic/env/**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\. -batch/build\-matrix/dynamic/env/**image** -Optional\. 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\. -batch/build\-matrix/dynamic/env/**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, \. +**compute\-type** +An array that containbs 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** +Optional\. 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: diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index 6737a43..c77b69b 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -64,15 +64,15 @@ The following example defines a build list\. The `linux_small` and `windows_medi batch: fast-fail: false build-list: - ignore-failure: true - - identifier: linux_small - env: - compute-type: BUILD_GENERAL1_SMALL - - identifier: windows_medium - env: - type: WINDOWS_SERVER_2019_CONTAINER - image: aws/codebuild/windows-base:2019-1.0 - compute-type: BUILD_GENERAL1_MEDIUM + - identifier: linux_small + env: + compute-type: BUILD_GENERAL1_SMALL + ignore-failure: true + - identifier: windows_medium + env: + type: WINDOWS_SERVER_2019_CONTAINER + image: aws/codebuild/windows-base:2019-1.0 + compute-type: BUILD_GENERAL1_MEDIUM ``` For more information about the build list buildspec syntax, see [`batch/build-list`](batch-build-buildspec.md#build-spec.batch.build-list)\. diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md index d0d126a..355e436 100644 --- a/doc_source/sample-windows.md +++ b/doc_source/sample-windows.md @@ -1,14 +1,12 @@ # 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 runtime files 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)\. ## Running the samples - - **To run these samples** 1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or a CodeCommit or GitHub repository\. @@ -46,29 +44,13 @@ If you are using an S3 input bucket, be sure to create a ZIP file that contains 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 C\# sample using the \.NET Framework, `CSharpHelloWorld.exe`, can be found in the `CSharpHelloWorld\bin\Debug` directory\. + 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\. - + The runtime file for the C\# sample using \.NET Core, `HelloWorldSample.dll`, can be found in the `bin\Debug\net5.0` 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 ``` @@ -102,207 +84,10 @@ These samples assume the following directory structures\. └── Settings.settings ``` -### C\# and \.NET Core - -``` -(root directory name) -├── buildspec.yml -├── HelloWorldSample.csproj -└── Program.cs -``` - ## 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)`\): @@ -1043,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\net5.0\* -``` - -`HelloWorldSample.csproj` \(in `(root directory name)` - -``` - - - Exe - net5.0 - - -``` - -`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/troubleshooting.md b/doc_source/troubleshooting.md index 4dd7d6f..38497f7 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -9,6 +9,7 @@ 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) ++ [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) @@ -173,6 +174,14 @@ pre_build: **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*\. +## Build status not reported to source provider + +**Issue:** After allowing build status reporting to a source provider, such as GitHub or Bitbucket, the build status is not updated\. + +**Possible cause:** The user associated with the source provider does not have write access to the repo\. + +**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 2019 platform **Issue:** You cannot find or select the base image of the Windows Server Core 2019 platform\. From a1084aab8c354a0507c23af57d599e2702adb61c Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 12 Jan 2021 18:08:05 +0000 Subject: [PATCH 095/156] General updates --- doc_source/build-env-ref-available.md | 19 +++++++++++++++---- doc_source/build-spec-ref.md | 2 +- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index f40020a..38e6137 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -5,21 +5,32 @@ 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: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\-aarch64\-standard:1\.0 | [al2/aarch64/standard/1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.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) | +| 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: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:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | +| 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) | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | 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)\. + 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)\. + +The following list contains links to the available runtimes for each of the standard Linux images\. ++ [Amazon Linux 2 x86 standard:2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/2.0/runtimes.yml) ++ [Amazon Linux 2 x86 standard:3\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/3.0/runtimes.yml) ++ [Amazon Linux 2 aarch64 standard:1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.0/runtimes.yml) ++ [Amazon Linux 2 aarch64 standard:2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/2.0/runtimes.yml) ++ [Ubuntu standard:3\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/3.0/runtimes.yml) ++ [Ubuntu standard:4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0/runtimes.yml) ++ [Ubuntu standard:5\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/5.0/runtimes.yml) 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** +**Ubuntu 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** diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 7df245d..6a2eee8 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -261,7 +261,7 @@ phases: 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** +**Ubuntu 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) 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** From 92820fa8625f917a197150eb6dd08593339dc018 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 14 Jan 2021 17:39:13 +0000 Subject: [PATCH 096/156] General updates --- .../getting-started-monitor-build-console.md | 4 +- .../getting-started-run-build-console.md | 4 +- doc_source/index.md | 2 +- doc_source/run-build-cli.md | 16 +-- doc_source/run-build-console.md | 123 +++--------------- 5 files changed, 29 insertions(+), 120 deletions(-) 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-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/index.md b/doc_source/index.md index c87bc4b..a27ac29 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 © 2021 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** ----- Amazon's trademarks and trade dress may not be used in diff --git a/doc_source/run-build-cli.md b/doc_source/run-build-cli.md index 0b41d78..f5f12cb 100644 --- a/doc_source/run-build-cli.md +++ b/doc_source/run-build-cli.md @@ -34,21 +34,21 @@ 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", diff --git a/doc_source/run-build-console.md b/doc_source/run-build-console.md index 2547711..7a1c3b3 100644 --- a/doc_source/run-build-console.md +++ b/doc_source/run-build-console.md @@ -4,116 +4,27 @@ To use AWS CodePipeline to run a build with CodeBuild, skip these steps and foll 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 **Build configuration**, choose from the following:\. -**Single build** -Choose this to perform a single build\. -**Batch build** -Choose this to perform a batch build\. + 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 **Batch configuration**, set the batch build configuration overrides for this build\. -**Note** -This section is only displayed when **Batch build** is selected in **Build configuration**\. -**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\. -To change whether CodeBuild can modify the batch service role you use for this build, 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)\. -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\. + 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 **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\. + When you have made your override selections, choose **Start build**\. - 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\. - - 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\. - - 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 From cda83be6505213d85ba111c659174d4669bfaf65 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 25 Jan 2021 16:24:35 +0000 Subject: [PATCH 097/156] General update --- doc_source/batch-build-buildspec.md | 7 ---- doc_source/build-env-ref-available.md | 19 ++++----- doc_source/build-spec-ref.md | 28 +++++++------- doc_source/sample-build-badges.md | 13 ++++++- doc_source/sample-elastic-beanstalk.md | 53 +++++++++++++------------- doc_source/sample-runtime-versions.md | 2 +- doc_source/sample-source-version.md | 2 +- 7 files changed, 61 insertions(+), 63 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 904f391..0848530 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -76,8 +76,6 @@ batch: - build2 ``` -For more information, see [Build graph](batch-build.md#batch_build_graph)\. - ## `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)\. @@ -90,9 +88,6 @@ Required\. The identifier of the task\. **buildspec** Optional\. The path and file name of the buildspec file to use for this task\. -**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** @@ -130,8 +125,6 @@ batch: compute-type: BUILD_GENERAL1_MEDIUM ``` -For more information, see [Build list](batch-build.md#batch_build_list)\. - ## `batch/build-matrix` Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. For more information, see [Build matrix](batch-build.md#batch_build_matrix)\. diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 38e6137..f3bd7d8 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -16,21 +16,18 @@ AWS CodeBuild manages the following Docker images that are available in the Code 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)\. + 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)\. -The following list contains links to the available runtimes for each of the standard Linux images\. -+ [Amazon Linux 2 x86 standard:2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/2.0/runtimes.yml) -+ [Amazon Linux 2 x86 standard:3\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/x86_64/standard/3.0/runtimes.yml) -+ [Amazon Linux 2 aarch64 standard:1\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/1.0/runtimes.yml) -+ [Amazon Linux 2 aarch64 standard:2\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/al2/aarch64/standard/2.0/runtimes.yml) -+ [Ubuntu standard:3\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/3.0/runtimes.yml) -+ [Ubuntu standard:4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0/runtimes.yml) -+ [Ubuntu standard:5\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/5.0/runtimes.yml) +The following table contains the available runtimes and the standard Linux images that support them\. - 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 and Amazon Linux 2 platform runtimes** +[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) -**Ubuntu and Amazon Linux 2 platforms runtimes** +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 and Amazon Linux 2 platform runtime versions** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-available.html) **Note** diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 6a2eee8..a9dd6b3 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -261,7 +261,7 @@ phases: 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 and Amazon Linux 2 platforms runtimes** +**Ubuntu and Amazon Linux 2 platform runtime versions** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) 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** @@ -353,8 +353,8 @@ 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\. @@ -408,27 +408,27 @@ You can use `files` and `discard-paths` to further restrict which files and subd ``` . -├── my-build1 -│ └── my-file1.txt -└── my-build2 - ├── my-file2.txt +├── my-build-1 +│ └── my-file-1.txt +└── my-build-2 + ├── my-file-2.txt └── my-subdirectory - └── my-file3.txt + └── 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-file-3.txt ``` While for the following `artifacts` sequence: @@ -443,9 +443,9 @@ 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/**secondary\-artifacts** diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 201eaee..783250b 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -59,8 +59,17 @@ 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 default 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 for the "master" branch, but you can specify any branch in your source repository that you have used to run a build\. For example: + +``` +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: + +``` +https://codebuild.us-east-1.amazon.com/badges?uuid=...&tag= +``` ## Publish your CodeBuild build badges diff --git a/doc_source/sample-elastic-beanstalk.md b/doc_source/sample-elastic-beanstalk.md index 5035040..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 uses AWS CodeBuild with Maven to produce a single WAR file named `my-web-app.war` as the build output\. 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,14 +14,14 @@ 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\. ``` . - └── my-web-app + └── ROOT ├── pom.xml └── src └── main @@ -32,12 +32,12 @@ In this section, you use Maven to produce the source code\. Later, you use CodeB └── index.jsp ``` -1. Create a subdirectory named `.ebextensions` in the `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 `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,10 +65,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/**/* ``` @@ -76,7 +76,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi ``` . - └── my-web-app + └── ROOT ├── .ebextensions │ └── fix-path.config ├── src @@ -90,10 +90,10 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi └── 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 `my-web-app`, just the directories and files in `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 `my-web-app` to the ZIP file, just the directories and files in `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,19 +153,18 @@ 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\. ``` . - └── my-web-app + └── ROOT ├── .ebextensions │ └── fix-path.config ├── src @@ -179,10 +178,10 @@ In this step, you create and add a buildspec file to the code you created in [Cr └── 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 `my-web-app`, just the directories and files in `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 `my-web-app` to the ZIP file, just the directories and files in `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\. @@ -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 @@ -272,7 +271,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi ``` . - └── my-web-app + └── ROOT ├── .ebextensions │ └── fix-path.config ├── src @@ -292,7 +291,7 @@ In this step, you add an Elastic Beanstalk configuration file and a buildspec fi 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-runtime-versions.md b/doc_source/sample-runtime-versions.md index 76b7dcd..700a8fe 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -333,7 +333,7 @@ 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**\. diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md index 2de7eae..4b4f24a 100644 --- a/doc_source/sample-source-version.md +++ b/doc_source/sample-source-version.md @@ -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**\. From 9f7181388857d5f4b0f7f0335bc773d0846a6774 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 8 Feb 2021 16:34:35 +0000 Subject: [PATCH 098/156] General updates --- doc_source/build-env-ref-compute-types.md | 50 ++++++++++++++++++++--- doc_source/notice.md | 2 +- doc_source/sample-build-badges.md | 2 +- doc_source/trigger-create.md | 3 +- 4 files changed, 49 insertions(+), 8 deletions(-) diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index 9416682..c88ff6f 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -16,11 +16,51 @@ AWS CodeBuild provides build environments with the following available memory, v The disk space listed for each build environment is available only in the directory specified by the `CODEBUILD_SRC_DIR` environment variable\. -**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\)\. +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 \(Oregon\) + + Asia Pacific \(Mumbai\) + + Asia Pacific \(Sydney\) + + Asia Pacific \(Tokyo\) + + Europe \(Frankfurt\) + + Europe \(Ireland\) ++ 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 \(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\. diff --git a/doc_source/notice.md b/doc_source/notice.md index 59eb089..16a129c 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 diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 783250b..5905ef3 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -59,7 +59,7 @@ 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)\. -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\. For example: +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: ``` https://codebuild.us-east-1.amazon.com/badges?uuid=...&branch= diff --git a/doc_source/trigger-create.md b/doc_source/trigger-create.md index b3006f8..8a028af 100644 --- a/doc_source/trigger-create.md +++ b/doc_source/trigger-create.md @@ -4,7 +4,8 @@ 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\. -You create a trigger after you create a project\. +**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** From ac5f8e9efc5dc8b435a27d6a405740ef4d04df41 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 10 Feb 2021 15:59:31 +0000 Subject: [PATCH 099/156] General updates --- doc_source/build-spec-ref.md | 123 ++++++++++++++++++------------ doc_source/history.md | 97 ++++++++++++----------- doc_source/use-codebuild-agent.md | 2 +- 3 files changed, 127 insertions(+), 95 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index a9dd6b3..c92cc69 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -69,6 +69,7 @@ batch: phases: install: run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE runtime\-versions: runtime: version runtime: version @@ -80,26 +81,29 @@ phases: - command pre\_build: run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE commands: - command - command - finally: + finally: - command - command build: run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE commands: - command - command - finally: + finally: - command - command post\_build: run\-as: Linux-user-name + on\-failure: ABORT | CONTINUE commands: - command - command - finally: + finally: - command - command reports: @@ -117,6 +121,9 @@ artifacts: name: artifact-name discard\-paths: no | yes base\-directory: location + exclude\-paths: excluded paths + enable\-symlinks: no | yes + s3\-prefix: prefix secondary\-artifacts: artifactIdentifier: files: @@ -243,6 +250,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** @@ -258,40 +274,29 @@ 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\. +The following supported runtimes can be specified\. **Ubuntu and Amazon Linux 2 platform runtime versions** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) 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 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\. +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 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\. +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 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\. +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 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\. - -**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 @@ -356,33 +361,46 @@ Optional name\. Specifies a name for your build artifact\. This name is used whe + 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 @@ -393,7 +411,7 @@ phases: artifacts: files: - '**/*' - name: $AWS_REGION-$(date +%Y-%m-%d) + name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts ``` artifacts/**discard\-paths** @@ -448,6 +466,15 @@ The following files would be included in the build output artifact: └── 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\. diff --git a/doc_source/history.md b/doc_source/history.md index f8b77cc..6a6ad32 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -1,26 +1,31 @@ # 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 30, 2020 ++ **Latest API version:** 2016\-10\-06 ++ **Latest documentation update: **February 9, 2021 | Change | Description | Date | | --- |--- |--- | +| [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 | +| [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 | @@ -53,38 +58,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-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 +| 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/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index d2ae45f..25c5828 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -36,7 +36,7 @@ You only need to set up the build image the first time you run the agent, or whe 1. 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: ``` - 948390fe21cd700f7c8b8c64ee89faf7aeca8ab87cd9dac4ba6c853a35817ae3 + sha256:2197749043428393c60626cccad0bb5017bf72889b6fc38921cd5b3529a85a8b ``` You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: From 7bb2eba87ada269f8fbc8b325449f0110f1c4034 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 10 Feb 2021 22:51:00 +0000 Subject: [PATCH 100/156] Update CodeBuild agent SHA --- doc_source/use-codebuild-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 25c5828..a8c31b3 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -36,7 +36,7 @@ You only need to set up the build image the first time you run the agent, or whe 1. 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: ``` - sha256:2197749043428393c60626cccad0bb5017bf72889b6fc38921cd5b3529a85a8b + sha256:fdfff9470520c53dcd522606a3cc2b5df195ae8a5546697b08249b48175f45ed ``` You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: From a2f07cf1537c4f2cbcf8a8a4304d75b4e6118297 Mon Sep 17 00:00:00 2001 From: Tom Mast Date: Sat, 13 Feb 2021 07:14:50 -0500 Subject: [PATCH 101/156] Fixed a few indentation errors and master->main occurrences --- CONTRIBUTING.md | 6 +++--- doc_source/build-spec-ref.md | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) 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/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index c92cc69..796f1f2 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -85,7 +85,7 @@ phases: commands: - command - command - finally: + finally: - command - command build: @@ -94,7 +94,7 @@ phases: commands: - command - command - finally: + finally: - command - command post\_build: @@ -103,7 +103,7 @@ phases: commands: - command - command - finally: + finally: - command - command reports: @@ -637,4 +637,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\. | \ No newline at end of file +| 0\.1 | This is the initial definition of the build specification format\. | From c64e0d02fdb3d4efd6951c1f46cdd79bd5c2a438 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 17 Feb 2021 15:52:40 +0000 Subject: [PATCH 102/156] Updates for project concurrent build limits --- doc_source/build-spec-ref.md | 2 +- doc_source/create-project-cli.md | 9 ++++++++- doc_source/create-project-console.md | 10 +++++++++- doc_source/history.md | 3 ++- doc_source/run-batch-build-cli.md | 2 +- doc_source/troubleshooting.md | 11 ++++++++++- 6 files changed, 31 insertions(+), 6 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 796f1f2..09ce5ad 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -637,4 +637,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/create-project-cli.md b/doc_source/create-project-cli.md index f599874..291fdfd 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -163,7 +163,8 @@ Modify the JSON data as follows and save your results\. ] }, "timeoutInMins": - } + }, + "concurrentBuildLimit": } ``` @@ -479,6 +480,12 @@ An array of strings that specify the compute types that are allowed for the batc buildBatchConfig/**timeoutInMinutes** The maximum amount of time, in minutes, that the batch build must be completed in\. +### 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: diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index b9e3d7d..589c0cd 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -26,9 +26,17 @@ Enter a name for this build project\. Build project names must be unique across Enter an optional description of the build project to help other users understand what this project is used for\. **Build badge** -Select to make your project's build status visible and embeddable\. For more information, see [Build badges sample](sample-build-badges.md)\. +\(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\. +**Enable concurrent build limit** +\(Optional\) 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\. + **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\. diff --git a/doc_source/history.md b/doc_source/history.md index 6a6ad32..46fd8f5 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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: **February 9, 2021 ++ **Latest documentation update: **February 16, 2021 | Change | Description | Date | | --- |--- |--- | +| [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 | diff --git a/doc_source/run-batch-build-cli.md b/doc_source/run-batch-build-cli.md index 76ac1a7..7e58b7a 100644 --- a/doc_source/run-batch-build-cli.md +++ b/doc_source/run-batch-build-cli.md @@ -48,7 +48,7 @@ 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` command again\. +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 diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 38497f7..f65ae37 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -33,6 +33,7 @@ Use the information in this topic to help you identify, diagnose, and address is + [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) + [Accessing GitHub metadata in locally cached builds](#troubleshooting-github-metadata) ++ [Build failed to start](#troubleshooting-build-failed-to-start) ## Apache Maven builds reference artifacts from the wrong repository @@ -521,4 +522,12 @@ artifacts: ``` git rev-parse --git-dir -``` \ No newline at end of file +``` + +## 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)\. \ No newline at end of file From f5b5762696dd0523a4b9bb7e8b2f2fe29a852224 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 23 Feb 2021 19:30:49 +0000 Subject: [PATCH 103/156] Add webhook best practices --- doc_source/bitbucket-webhook.md | 4 ++-- doc_source/github-webhook.md | 2 +- doc_source/index.md | 5 +++-- doc_source/sample-bitbucket-pull-request.md | 5 ++++- doc_source/sample-github-pull-request.md | 2 +- doc_source/webhooks.md | 24 +++++++++++++++++++++ doc_source/working-with-build-projects.md | 3 +-- 7 files changed, 36 insertions(+), 9 deletions(-) create mode 100644 doc_source/webhooks.md diff --git a/doc_source/bitbucket-webhook.md b/doc_source/bitbucket-webhook.md index 42082f1..f754b8e 100644 --- a/doc_source/bitbucket-webhook.md +++ b/doc_source/bitbucket-webhook.md @@ -1,8 +1,8 @@ # 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 triggered for specified branches only\. +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: +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: diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md index ca85456..fe4c263 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -1,6 +1,6 @@ # 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 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: diff --git a/doc_source/index.md b/doc_source/index.md index a27ac29..17c0a19 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -92,8 +92,9 @@ 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) - + [Bitbucket webhook events](bitbucket-webhook.md) - + [GitHub webhook events](github-webhook.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) diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index 55b187e..d137d74 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -1,9 +1,12 @@ # 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 events](bitbucket-webhook.md)\. +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) diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 5e2299a..21b7994 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 [GitHub webhook events](github-webhook.md)\. +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\) 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/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 2179c8f..9292e7f 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -12,8 +12,7 @@ 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) -+ [Bitbucket webhook events](bitbucket-webhook.md) -+ [GitHub webhook events](github-webhook.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) From aa43776ec5db8808952385a7c785fc7fb2f67725 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 1 Mar 2021 16:57:43 +0000 Subject: [PATCH 104/156] General update --- doc_source/create-project-console.md | 1 + doc_source/index.md | 2 +- doc_source/report-group-create.md | 2 +- doc_source/sample-docker.md | 3 + doc_source/session-manager.md | 3 + doc_source/test-report-group-create-cli.md | 58 ++++++++++--------- .../test-report-group-create-console.md | 22 +++---- doc_source/troubleshooting.md | 23 ++++++-- 8 files changed, 69 insertions(+), 45 deletions(-) diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 589c0cd..b7e05cc 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -176,6 +176,7 @@ 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** \(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\. diff --git a/doc_source/index.md b/doc_source/index.md index 17c0a19..f7ef714 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -128,8 +128,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) 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/sample-docker.md b/doc_source/sample-docker.md index 3a6e0bc..5039dcc 100644 --- a/doc_source/sample-docker.md +++ b/doc_source/sample-docker.md @@ -200,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\. diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md index a1f36b6..f6b94d7 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) diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index 78e25f7..a6c9efd 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 master key \(CMK\)\. 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..dd0ced9 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 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:::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/troubleshooting.md b/doc_source/troubleshooting.md index f65ae37..fd735b3 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -32,8 +32,9 @@ Use the information in this topic to help you identify, diagnose, and address is + [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) -+ [Accessing GitHub metadata in locally cached builds](#troubleshooting-github-metadata) + [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 @@ -512,6 +513,14 @@ artifacts: **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\. @@ -524,10 +533,14 @@ artifacts: git rev-parse --git-dir ``` -## Build failed to start +## AccessDenied: The bucket owner for the report group does not match the owner of the S3 bucket\.\.\. -**Issue:** When starting a build, you receive a **Build failed to start** error message\. +**Issue:** When uploading test data to an Amazon S3 bucket, CodeBuild is unable to write the test data to the bucket\. -**Possible cause:** The number of concurrent builds has been reached\. +**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:** 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)\. \ No newline at end of file +**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 From caf8dd51d7fbb374e88db2a6fdb6ec6c98b26bb8 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 8 Mar 2021 16:07:13 +0000 Subject: [PATCH 105/156] Add batch build debug session --- doc_source/batch-build-buildspec.md | 17 +++++++++++++++++ doc_source/batch-build.md | 3 +++ doc_source/history.md | 5 +++-- 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 0848530..7be7c63 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -32,6 +32,13 @@ Required\. The identifier of the task\. **buildspec** Optional\. The path and file name of the buildspec file to use for this task\. +**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\. @@ -64,11 +71,13 @@ batch: - identifier: build1 env: compute-type: BUILD_GENERAL1_SMALL + debug-session: true - identifier: build2 env: compute-type: BUILD_GENERAL1_MEDIUM depend-on: - build1 + debug-session: false - identifier: build3 env: compute-type: BUILD_GENERAL1_LARGE @@ -88,6 +97,13 @@ Required\. The identifier of the task\. **buildspec** Optional\. The path and file name of the buildspec file to use for this task\. +**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** @@ -118,6 +134,7 @@ batch: env: compute-type: BUILD_GENERAL1_SMALL ignore-failure: true + debug-session: true - identifier: windows_medium env: type: WINDOWS_SERVER_2019_CONTAINER diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index c77b69b..bb158b8 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -35,11 +35,13 @@ batch: - identifier: build1 env: compute-type: BUILD_GENERAL1_SMALL + debug-session: true - identifier: build2 env: compute-type: BUILD_GENERAL1_MEDIUM depend-on: - build1 + debug-session: false - identifier: build3 env: compute-type: BUILD_GENERAL1_LARGE @@ -68,6 +70,7 @@ batch: env: compute-type: BUILD_GENERAL1_SMALL ignore-failure: true + debug-session: true - identifier: windows_medium env: type: WINDOWS_SERVER_2019_CONTAINER diff --git a/doc_source/history.md b/doc_source/history.md index 46fd8f5..e60ccdf 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -1,11 +1,12 @@ # 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: **February 16, 2021 ++ **Latest API version:** 2016\-10\-06 ++ **Latest documentation update: **March 3, 2021 | Change | Description | Date | | --- |--- |--- | +| [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 | From 66c99fe0d40763497ce1e3ecc195b1b9008329d5 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 9 Mar 2021 19:17:08 +0000 Subject: [PATCH 106/156] General update --- doc_source/batch-build-buildspec.md | 25 +++++++++++++------------ doc_source/batch-build.md | 26 ++++++++++++++------------ doc_source/build-spec-ref.md | 3 ++- 3 files changed, 29 insertions(+), 25 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 7be7c63..a036fc3 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -30,7 +30,7 @@ This element contains an array of build tasks\. Each build task contains the fol Required\. The identifier of the task\. **buildspec** -Optional\. The path and file name of the buildspec file to use for this task\. +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)\. @@ -95,7 +95,7 @@ This element contains an array of build tasks\. Each build task contains the fol Required\. The identifier of the task\. **buildspec** -Optional\. The path and file name of the buildspec file to use for this task\. +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)\. @@ -144,7 +144,7 @@ batch: ## `batch/build-matrix` -Defines a *build matrix*\. A build matrix is used to define tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. For more information, see [Build matrix](batch-build.md#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\. @@ -167,20 +167,20 @@ The identifier of the environment type to use for the task\. See **Environment t **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, \. **privileged\-mode** -Optional\. 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`\. +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** -Optional\. 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\. +The identifier of the environment type to use for these tasks\. 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 name of the buildspec files to use for these tasks\. +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 the task\. +Optional\. The build environment overrides for these tasks\. **compute\-type** -An array that containbs 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\. +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** -Optional\. 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\. +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, \. @@ -193,12 +193,13 @@ batch: ignore-failure: false env: type: LINUX_CONTAINER + image: aws/codebuild/amazonlinux2-x86_64-standard:3.0 privileged-mode: true dynamic: + buildspec: + - matrix1.yml + - matrix2.yml env: - image: - - aws/codebuild/amazonlinux2-x86_64-standard:3.0 - - aws/codebuild/windows-base:2019-1.0 variables: MY_VAR: - VALUE1 diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index bb158b8..9d64194 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -82,9 +82,9 @@ For more information about the build list buildspec syntax, see [`batch/build-li ### Build matrix -A build matrix defines tasks that will run in parallel with different environments\. CodeBuild creates a separate build for each possible environment configuration\. +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 images and three values for an environment variable\. +The following example shows a build matrix with two buildspec files and three values for an environment variable\. ``` batch: @@ -93,12 +93,13 @@ batch: ignore-failure: false env: type: LINUX_CONTAINER + image: aws/codebuild/amazonlinux2-x86_64-standard:3.0 privileged-mode: true dynamic: + buildspec: + - matrix1.yml + - matrix2.yml env: - image: - - aws/codebuild/amazonlinux2-x86_64-standard:3.0 - - aws/codebuild/windows-base:2019-1.0 variables: MY_VAR: - VALUE1 @@ -107,17 +108,18 @@ batch: ``` In this example, CodeBuild creates six builds: -+ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE1` -+ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE2` -+ `aws/codebuild/amazonlinux2-x86_64-standard:3.0` / `MY_VAR=VALUE3` -+ `aws/codebuild/windows-base:2019-1.0` / `MY_VAR=VALUE1` -+ `aws/codebuild/windows-base:2019-1.0` / `MY_VAR=VALUE2` -+ `aws/codebuild/windows-base:2019-1.0` / `MY_VAR=VALUE3` ++ `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/privileged`\-mode set to `true` ++ `env/image` set to `aws/codebuild/amazonlinux2-x86_64-standard:3.0` ++ `env/privileged-mode` set to `true` These builds run in parallel\. diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index 09ce5ad..e888ac4 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -220,7 +220,8 @@ For more information, see [What is AWS Secrets Manager](https://docs.aws.amazon. 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 From dd1a3317fa66865cd2b603e09d4c33472dd3a2ea Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 19 Mar 2021 20:26:32 +0000 Subject: [PATCH 107/156] Update test file list with extensions --- doc_source/sample-test-report-cli.md | 12 ++++++------ doc_source/test-reporting.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index efa3b2d..8b6c617 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -14,12 +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 - + NUnit3 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*\. diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index 5b8c084..d8ff1b4 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -3,12 +3,12 @@ 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 -+ NUnit3 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\)\. From a0483f0cc2cfcf2a7ef3a23ff1fa2f583e4d2623 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 24 Mar 2021 15:28:02 +0000 Subject: [PATCH 108/156] Reorganize getting started tutorials --- doc_source/getting-started-clean-up-console.md | 6 +++--- doc_source/getting-started-cli-clean-up.md | 6 +++--- .../getting-started-cli-create-build-spec.md | 6 +++--- .../getting-started-cli-create-source-code.md | 6 +++--- doc_source/getting-started-cli-input-bucket.md | 6 +++--- doc_source/getting-started-cli-output.md | 2 +- .../getting-started-cli-upload-source-code.md | 2 +- doc_source/getting-started-cli.md | 8 ++++---- ...etting-started-create-build-spec-console.md | 6 +++--- ...tting-started-create-source-code-console.md | 6 +++--- .../getting-started-input-bucket-console.md | 6 +++--- doc_source/getting-started-output-console.md | 2 +- ...tting-started-upload-source-code-console.md | 2 +- doc_source/getting-started.md | 8 ++++---- doc_source/index.md | 18 +++++++++--------- 15 files changed, 45 insertions(+), 45 deletions(-) diff --git a/doc_source/getting-started-clean-up-console.md b/doc_source/getting-started-clean-up-console.md index b3d3db5..e016aa1 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 Developer 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..367dac8 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 Developer 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-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-output.md b/doc_source/getting-started-cli-output.md index f7b581e..edc86d9 100644 --- a/doc_source/getting-started-cli-output.md +++ b/doc_source/getting-started-cli-output.md @@ -28,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 9ab0cbc..81e613e 100644 --- a/doc_source/getting-started-cli.md +++ b/doc_source/getting-started-cli.md @@ -8,14 +8,14 @@ You can work with CodeBuild through the CodeBuild console, AWS CodePipeline, the 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-output-console.md b/doc_source/getting-started-output-console.md index d9f0c7a..b92c297 100644 --- a/doc_source/getting-started-output-console.md +++ b/doc_source/getting-started-output-console.md @@ -28,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-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 95a68af..8292576 100644 --- a/doc_source/getting-started.md +++ b/doc_source/getting-started.md @@ -8,14 +8,14 @@ You can work with CodeBuild through the CodeBuild console, AWS CodePipeline, the 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/index.md b/doc_source/index.md index f7ef714..5fae8d9 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,7 +1,7 @@ # AWS CodeBuild User Guide ----- -*****Copyright © 2021 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,28 +18,28 @@ 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) From ef240266eea53d1970f3e9b05dd2181ec0cde1d6 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 24 Mar 2021 16:15:56 +0000 Subject: [PATCH 109/156] Entity change --- doc_source/code-coverage-report.md | 4 ++-- doc_source/test-report-jasmine.md | 4 ++-- doc_source/test-report-jest.md | 4 ++-- doc_source/test-report-pytest.md | 2 +- doc_source/test-report-rspec.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc_source/code-coverage-report.md b/doc_source/code-coverage-report.md index b7d6988..e304e18 100644 --- a/doc_source/code-coverage-report.md +++ b/doc_source/code-coverage-report.md @@ -22,7 +22,7 @@ The following code coverage report file formats are supported: ## 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\. AWS 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 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** @@ -30,7 +30,7 @@ To create a code coverage report, you run a build project that is configured wit 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\. AWS 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, AWS 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 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)\. diff --git a/doc_source/test-report-jasmine.md b/doc_source/test-report-jasmine.md index 5c55771..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\. @@ -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\. diff --git a/doc_source/test-report-jest.md b/doc_source/test-report-jest.md index dca5ecd..53e2948 100644 --- a/doc_source/test-report-jest.md +++ b/doc_source/test-report-jest.md @@ -3,10 +3,10 @@ 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 diff --git a/doc_source/test-report-pytest.md b/doc_source/test-report-pytest.md index 76c90c1..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\. diff --git a/doc_source/test-report-rspec.md b/doc_source/test-report-rspec.md index 3b94737..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\. From db8a8ef500a85bb9b27282f06b543ac6916052ca Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 2 Apr 2021 16:27:01 +0000 Subject: [PATCH 110/156] General update --- doc_source/build-env-ref-compute-types.md | 2 + doc_source/create-project-cli.md | 2 +- doc_source/use-codebuild-agent.md | 46 +++++++++++++++++------ 3 files changed, 38 insertions(+), 12 deletions(-) diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index c88ff6f..a23ace3 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -33,8 +33,10 @@ Some environment and compute types have Region availability limitations: + 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 \(Singapore\) + Asia Pacific \(Sydney\) + Asia Pacific \(Tokyo\) + Europe \(Frankfurt\) diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 291fdfd..f42d077 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -374,7 +374,7 @@ If you choose **New service role**, the service role includes permission to decr 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\. +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: diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index a8c31b3..84ccc70 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -1,14 +1,16 @@ # Run builds locally with the AWS CodeBuild agent -You can use the AWS CodeBuild agent to run CodeBuild builds on a local machine\. You can also 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\. + +You can also subscribe to receive notifications when new versions of the agent are published\. ## Prerequisites Before you begin, you need to do the following: + Install Git on your local machine\. -+ Install and setup [Docker](https://www.docker.com/) on your local machine\. ++ Install and set up [Docker](https://www.docker.com/) on your local machine\. -## Setup the build image +## Set up the build image You only need to set up the build image the first time you run the agent, or when the image has changed\. @@ -27,19 +29,35 @@ You only need to set up the build image the first time you run the agent, or whe $ docker build -t aws/codebuild/standard:4.0 . ``` -1. Run the following Docker command to download the local CodeBuild agent\.: +1. Download the agent\. + + To download the x86\_64 version of the agent, run the following command: ``` $ docker pull amazon/aws-codebuild-local:latest --disable-content-trust=false ``` -1. 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: + To download the ARM version of the agent, run the following command: + + ``` + $ docker pull amazon/aws-codebuild-local:aarch64 --disable-content-trust=false + ``` + +1. The CodeBuild agent is available from [https://hub\.docker\.com/r/amazon/aws\-codebuild\-local/](https://hub.docker.com/r/amazon/aws-codebuild-local/)\. + + The Secure Hash Algorithm \(SHA\) signature for the x86\_64 version of the agent is: ``` sha256:fdfff9470520c53dcd522606a3cc2b5df195ae8a5546697b08249b48175f45ed ``` - You can use this to identify the version of the agent\. To see the agent's SHA signature, run the following command: + The SHA signature for the ARM version of the agent is: + + ``` + sha256:5480b70cf48435e276c21789c61280cfada24e17701ede6386e5d82088bc41ca + ``` + + You can use the SHA to identify the version of the agent\. To see the agent's SHA signature, run the following command: ``` $ docker inspect amazon/aws-codebuild-local @@ -58,17 +76,25 @@ You only need to set up the build image the first time you run the agent, or whe $ chmod +x codebuild_build.sh ``` -1. Run the `codebuild_build.sh` script and specify your container image and the output directory: +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 aws/codebuild/standard:4.0 -a ``` + To run an ARM build, run the following command: + + ``` + $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a -l amazon/aws-codebuild-local:aarch64 + ``` + 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 know when new versions of the AWS CodeBuild agent are released\. +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** @@ -104,6 +130,4 @@ You can subscribe to Amazon SNS notifications so you know when new versions of t 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 From 6929ea4dd95cbbbb4f2d5b7a188c9ae4e93ba8ef Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 9 Apr 2021 15:55:13 +0000 Subject: [PATCH 111/156] General update --- doc_source/build-spec-ref.md | 4 ++-- doc_source/change-project-console.md | 4 ++-- doc_source/create-project-cli.md | 2 +- doc_source/create-project-console.md | 4 ++-- ...getting-started-cli-create-build-project.md | 2 +- doc_source/report-group-export-settings.md | 6 +++--- doc_source/security-encryption.md | 12 ++++++------ doc_source/security-key-management.md | 2 +- doc_source/setting-up.md | 18 +++++++++--------- doc_source/test-report-group-create-cli.md | 2 +- doc_source/test-report-group-create-console.md | 4 ++-- doc_source/update-report-group-cli.md | 10 +++++----- doc_source/update-report-group-console.md | 10 +++++----- 13 files changed, 40 insertions(+), 40 deletions(-) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index e888ac4..d6dd7d4 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -565,7 +565,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: @@ -612,7 +612,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\. diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 1044a03..635f02e 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -221,9 +221,9 @@ Select **Combine all artifacts from batch into a single location** to have all o 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**\. +1. To change information about the AWS KMS key, 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\. +If you leave **Encryption key** blank, CodeBuild uses the KMS key 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**\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index f42d077..564ec2d 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -412,7 +412,7 @@ Optional\. The number of minutes, between 5 to 480 \(8 hours\), after which Code ### 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\. +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 diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index b7e05cc..b55b73f 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -289,8 +289,8 @@ For each secondary set of artifacts you want: **Additional configuration** **Encryption key** \(Optional\) 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`\. ++ 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**\. diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 140858e..43a6ab1 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -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/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/security-encryption.md b/doc_source/security-encryption.md index ab8d189..6fca4a5 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*\. +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 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#cli.encryptionkey)\. + + 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** \- CodeBuild requires access to a KMS key in order to encrypt its build output artifacts\. By default, CodeBuild uses an AWS managed key Amazon S3\. If you do not want to use this AWS managed key, you must create and configure a customer managed key\. For more information [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index 495e7da..e752043 100644 --- a/doc_source/security-key-management.md +++ b/doc_source/security-key-management.md @@ -1,6 +1,6 @@ # 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 CodeBuild 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)\. diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index 83dca49..fa75cfe 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -7,7 +7,7 @@ We assume you already have an AWS account\. However, if you do not already have **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 @@ -460,15 +460,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 +532,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/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index a6c9efd..c2d8a83 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -33,7 +33,7 @@ + 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 master key \(CMK\)\. For more information, see [Update a report group](report-group-export-settings.md)\. + + 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: ``` diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index dd0ced9..3c131b3 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -25,8 +25,8 @@ 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:::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*\. + + **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)\. diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md index 9aacc11..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": [] 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 From 37c644f21e24d4c4ecc609c16d26b17631fcd884 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 15 Apr 2021 15:17:06 +0000 Subject: [PATCH 112/156] General update --- doc_source/change-project-console.md | 4 ++-- doc_source/create-project-cli.md | 2 +- doc_source/create-project-console.md | 4 ++-- ...getting-started-cli-create-build-project.md | 2 +- doc_source/report-group-export-settings.md | 6 +++--- doc_source/security-encryption.md | 12 ++++++------ doc_source/security-key-management.md | 2 +- doc_source/setting-up.md | 18 +++++++++--------- doc_source/test-report-group-create-cli.md | 2 +- doc_source/test-report-group-create-console.md | 4 ++-- doc_source/update-report-group-cli.md | 10 +++++----- doc_source/update-report-group-console.md | 10 +++++----- 12 files changed, 38 insertions(+), 38 deletions(-) diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 635f02e..1044a03 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -221,9 +221,9 @@ Select **Combine all artifacts from batch into a single location** to have all o 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 key, in **Additional configuration**, change the value for **Encryption key**\. +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 KMS key for Amazon S3 in your AWS account instead\. +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**\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 564ec2d..f42d077 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -412,7 +412,7 @@ Optional\. The number of minutes, between 5 to 480 \(8 hours\), after which Code ### 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\. +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\. ### tags diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index b55b73f..b7e05cc 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -289,8 +289,8 @@ For each secondary set of artifacts you want: **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`\. ++ 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`\. **Cache type** For **Cache type**, choose one of the following: + If you do not want to use a cache, choose **No cache**\. diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 43a6ab1..140858e 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -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 customer managed key that CodeBuild used to encrypt the build output artifact\. + + `encryptionKey` represents the ARN of the AWS KMS customer master key \(CMK\) that CodeBuild used to encrypt the build output artifact\. + `arn` represents the ARN of the build project\. **Note** diff --git a/doc_source/report-group-export-settings.md b/doc_source/report-group-export-settings.md index 9918839..e5dea19 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: - + An AWS managed key for Amazon S3\. - + A customer managed key that you create and configure\. + + A customer master key \(CMK\) for Amazon S3 that is managed by the AWS Key Management Service\. + + A CMK 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/security-encryption.md b/doc_source/security-encryption.md index 6fca4a5..ab8d189 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 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*\. + 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 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)\. + + 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#cli.encryptionkey)\. - 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** \- CodeBuild requires access to a KMS key in order to encrypt its build output artifacts\. By default, CodeBuild uses an AWS managed key Amazon S3\. If you do not want to use this AWS managed key, you must create and configure a customer managed key\. 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 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 diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index e752043..495e7da 100644 --- a/doc_source/security-key-management.md +++ b/doc_source/security-key-management.md @@ -1,6 +1,6 @@ # 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 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)\. + 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)\. 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)\. diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index fa75cfe..83dca49 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -7,7 +7,7 @@ We assume you already have an AWS account\. However, if you do not already have **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 a customer managed key for CodeBuild](#setting-up-kms) ++ [Create and configure an AWS KMS CMK 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 @@ -460,15 +460,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 a customer managed key for CodeBuild +## Create and configure an AWS KMS CMK for CodeBuild -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\. +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\. -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\. +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\. -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*\. +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*\. -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\. +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\. ``` { @@ -532,14 +532,14 @@ To configure a customer managed key for use by CodeBuild, follow the instruction } ``` + *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 customer managed key\. ++ *account\-ID* represents the ID of the of the AWS account that owns the CMK\. + *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 customer managed key 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 CMK 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 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*\. +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*\. ## Install and configure the AWS CLI diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index c2d8a83..a6c9efd 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -33,7 +33,7 @@ + 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 `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)\. + Use the following JSON to specify that your test report does not export raw test files: ``` diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index 3c131b3..dd0ced9 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -25,8 +25,8 @@ 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 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*\. + + **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:::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)\. diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md index 257c344..9aacc11 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 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: +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: ``` { @@ -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": [] diff --git a/doc_source/update-report-group-console.md b/doc_source/update-report-group-console.md index abe5f6c..9fb9985 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 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 + 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 From d0c802c04a8712197f672340a446bfbb34bd9f4d Mon Sep 17 00:00:00 2001 From: Trivikram Kamat <16024985+trivikr@users.noreply.github.com> Date: Thu, 15 Apr 2021 11:52:33 -0700 Subject: [PATCH 113/156] Use standard:5.0 in local codebuild guide Standard 5.0 image was released on 2021/01/08 https://github.com/aws/aws-codebuild-docker-images/releases/tag/21.01.08 --- doc_source/use-codebuild-agent.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 84ccc70..eec500a 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -22,11 +22,11 @@ You only need to set up the build image the first time you run the agent, or whe $ git clone https://github.com/aws/aws-codebuild-docker-images.git ``` -1. Build the image\. For this example, use the `aws/codebuild/standard:4.0` image\. This will take several minutes\. +1. Build the image\. For this example, use the `aws/codebuild/standard:5.0` image\. This will take several minutes\. ``` - $ cd aws-codebuild-docker-images/ubuntu/standard/4.0 - $ docker build -t aws/codebuild/standard:4.0 . + $ cd aws-codebuild-docker-images/ubuntu/standard/5.0 + $ docker build -t aws/codebuild/standard:5.0 . ``` 1. Download the agent\. @@ -81,13 +81,13 @@ You only need to set up the build image the first time you run the agent, or whe To run an x86\_64 build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a + $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a ``` To run an ARM build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a -l amazon/aws-codebuild-local:aarch64 + $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a -l amazon/aws-codebuild-local:aarch64 ``` 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\. @@ -130,4 +130,4 @@ You can subscribe to Amazon SNS notifications so you will be notified when new v 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**\. From dd87e09e9c48355674244c92c0ea47ed2b18a3de Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 15 Apr 2021 22:46:34 +0000 Subject: [PATCH 114/156] General update --- doc_source/use-codebuild-agent.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index eec500a..d28abdf 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -22,10 +22,15 @@ You only need to set up the build image the first time you run the agent, or whe $ git clone https://github.com/aws/aws-codebuild-docker-images.git ``` -1. Build the image\. For this example, use the `aws/codebuild/standard:5.0` image\. This will take several minutes\. +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 . ``` @@ -81,13 +86,13 @@ You only need to set up the build image the first time you run the agent, or whe To run an x86\_64 build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a + $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a ``` To run an ARM build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a -l amazon/aws-codebuild-local:aarch64 + $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a -l amazon/aws-codebuild-local:aarch64 ``` 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\. @@ -130,4 +135,4 @@ You can subscribe to Amazon SNS notifications so you will be notified when new v 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**\. +1. Select the subscription and from **Actions**, choose **Delete subscriptions**\. When you are prompted to confirm, choose **Delete**\. \ No newline at end of file From 030542a7ea5d3a8902d6a2f8fe35d423838d7e21 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 21 Apr 2021 15:25:25 +0000 Subject: [PATCH 115/156] General update --- doc_source/sample-bitbucket-pull-request.md | 8 +++++--- doc_source/sample-github-pull-request.md | 6 +++++- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/doc_source/sample-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md index d137d74..b458484 100644 --- a/doc_source/sample-bitbucket-pull-request.md +++ b/doc_source/sample-bitbucket-pull-request.md @@ -40,11 +40,11 @@ Choose **Bitbucket**\. Follow the instructions to connect \(or reconnect\) with 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\. -**Bitbucket repository** Enter the URL for your Bitbucket repository\. -1. In **Primary source webhook events**, select the following\. This section is only available when you chose **Repository in my Bitbucket account** in the previous step\. +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 Bitbucket account** in the previous step\. 1. Select **Rebuild every time a code change is pushed to this repository** when you create your project\. @@ -56,6 +56,8 @@ Enter the URL for your Bitbucket repository\. 1. Choose **Add filter group** to add another filter group, if needed\. + For more information about Bitbucket webhook event types and filters, see [Bitbucket webhook events](bitbucket-webhook.md)\. + 1. In **Environment**: **Environment image** Choose one of the following: diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index 21b7994..f020735 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -25,7 +25,9 @@ Choose **Repository in my GitHub account**\. **GitHub repository** Enter the URL for your GitHub repository\. -1. In **Primary source webhook events**, select the following\. This section is only available when you chose **Repository in my GitHub account** in the previous step\. +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\. @@ -37,6 +39,8 @@ Enter the URL for your GitHub repository\. 1. Choose **Add filter group** to add another filter group, if needed\. + For more information about GitHub webhook event types and filters, see [GitHub webhook events](github-webhook.md)\. + 1. In **Environment**: **Environment image** Choose one of the following: From 75249de9fba4d546ac61941191a0b2e1e2a3dc1b Mon Sep 17 00:00:00 2001 From: Adam Cox Date: Tue, 27 Apr 2021 15:51:29 +0100 Subject: [PATCH 116/156] Fix agent version in Run the CodeBuild agent steps --- doc_source/use-codebuild-agent.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index d28abdf..3d75aab 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -86,13 +86,13 @@ You only need to set up the build image the first time you run the agent, or whe To run an x86\_64 build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a + $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a ``` To run an ARM build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:4.0 -a -l amazon/aws-codebuild-local:aarch64 + $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a -l amazon/aws-codebuild-local:aarch64 ``` 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\. @@ -135,4 +135,4 @@ You can subscribe to Amazon SNS notifications so you will be notified when new v 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**\. From b85358007eda6333060159c78510963ee8215823 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 28 Apr 2021 16:18:40 +0000 Subject: [PATCH 117/156] General update --- doc_source/available-runtimes.md | 33 +++++++++++++++++++++ doc_source/build-caching.md | 2 +- doc_source/build-env-ref-available.md | 41 ++++----------------------- doc_source/build-spec-ref.md | 4 +-- doc_source/index.md | 2 ++ doc_source/runtime-versions.md | 12 ++++++++ doc_source/use-codebuild-agent.md | 2 +- 7 files changed, 56 insertions(+), 40 deletions(-) create mode 100644 doc_source/available-runtimes.md create mode 100644 doc_source/runtime-versions.md diff --git a/doc_source/available-runtimes.md b/doc_source/available-runtimes.md new file mode 100644 index 0000000..2d4ef67 --- /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` | +| --- | --- | +| dotnet | 3\.1\.4045\.0 | +| golang | 1\.14 | +| nodejs | 12\.18 | +| java | corretto11 | +| php | 7\.4\.7 | +| powershell | 7\.0\.2 | +| python | 3\.8\.3 | +| ruby | 2\.7 | \ No newline at end of file diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 22191b5..210ecc4 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -87,7 +87,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 f3bd7d8..bda2593 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -14,46 +14,13 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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) | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | -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)\. - -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/build-env-ref-available.html) - -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 and Amazon Linux 2 platform runtime versions** -[\[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 2019 contains the following runtimes\. - - -| Runtime name | Version in `windows-base:2019-1.0` | -| --- | --- | -| dotnet | 3\.1\.4045\.0 | -| golang | 1\.14 | -| nodejs | 12\.18 | -| java | corretto11 | -| php | 7\.4\.7 | -| powershell | 7\.0\.2 | -| python | 3\.8\.3 | -| ruby | 2\.7 | - 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\) -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 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`\. 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-console.md)\. @@ -62,4 +29,8 @@ CodeBuild frequently updates the list of Docker images\. To get the most current ``` 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-spec-ref.md b/doc_source/build-spec-ref.md index d6dd7d4..f33059d 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -277,9 +277,7 @@ phases: ``` 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 and Amazon Linux 2 platform runtime versions** -[\[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** 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\. diff --git a/doc_source/index.md b/doc_source/index.md index 5fae8d9..a2d1a32 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -70,6 +70,8 @@ Amazon's trademarks and trade dress may not be used in + [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) diff --git a/doc_source/runtime-versions.md b/doc_source/runtime-versions.md new file mode 100644 index 0000000..d7138f3 --- /dev/null +++ b/doc_source/runtime-versions.md @@ -0,0 +1,12 @@ +# Runtime versions + +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 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/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 3d75aab..bd862c7 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -135,4 +135,4 @@ You can subscribe to Amazon SNS notifications so you will be notified when new v 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**\. +1. Select the subscription and from **Actions**, choose **Delete subscriptions**\. When you are prompted to confirm, choose **Delete**\. \ No newline at end of file From 030e93500127cfbe47772e6a7305023d4fb559d6 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 30 Apr 2021 20:42:30 +0000 Subject: [PATCH 118/156] General update --- doc_source/build-env-ref-available.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index bda2593..5833a00 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -9,11 +9,13 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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\-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: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: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:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | | 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) | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | +¹ No longer maintained after May 2021\. + The base image of the Windows Server Core 2019 platform is only available in the following regions: + US East \(N\. Virginia\) + US East \(Ohio\) From 4b8a32d5d0ec48e7998fbc75049e0c62e6eb91d4 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 7 May 2021 18:58:12 +0000 Subject: [PATCH 119/156] General update --- doc_source/codecov-integration.md | 2 +- doc_source/sample-github-pull-request.md | 3 +-- doc_source/sample-pipeline-multi-input-output.md | 2 +- doc_source/sample-private-registry.md | 3 +-- doc_source/troubleshooting.md | 2 +- doc_source/use-vpc-endpoints-with-codebuild.md | 2 +- 6 files changed, 6 insertions(+), 8 deletions(-) diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index d75d801..aaa06ee 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -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/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md index f020735..95f5a99 100644 --- a/doc_source/sample-github-pull-request.md +++ b/doc_source/sample-github-pull-request.md @@ -89,5 +89,4 @@ Expand **Additional configuration** and set options as appropriate\. 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/) \ 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-pipeline-multi-input-output.md b/doc_source/sample-pipeline-multi-input-output.md index e8401be..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*\. ``` { diff --git a/doc_source/sample-private-registry.md b/doc_source/sample-private-registry.md index 8e3ad43..3f0de73 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -25,8 +25,7 @@ 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\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index fd735b3..f399175 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -474,7 +474,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)\. 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 From c4f2faba04eaddef92c4d86146701138f7db949f Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 10 May 2021 14:56:16 +0000 Subject: [PATCH 120/156] Reformat quotas page --- doc_source/limits.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/doc_source/limits.md b/doc_source/limits.md index 12b9351..542dcd5 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 **** @@ -46,15 +47,14 @@ The following tables list the current quotas in AWS CodeBuild\. These quotas are | Maximum number of report groups per AWS account | 1000 | | 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 From 1773177a389528e870dabb19bf2e89216073834c Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 14 May 2021 20:21:54 +0000 Subject: [PATCH 121/156] General update --- doc_source/index.md | 2 +- doc_source/view-project-details.md | 43 ++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/doc_source/index.md b/doc_source/index.md index a2d1a32..0b13842 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -1,7 +1,7 @@ # AWS CodeBuild User Guide ----- -*****Copyright © 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 diff --git a/doc_source/view-project-details.md b/doc_source/view-project-details.md index 77e689e..f25e255 100644 --- a/doc_source/view-project-details.md +++ b/doc_source/view-project-details.md @@ -62,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\) From b9e3be3442db4fe4e1b923b6d1b84b01b480df4d Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 27 May 2021 18:53:42 +0000 Subject: [PATCH 122/156] General update --- doc_source/sample-private-registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/sample-private-registry.md b/doc_source/sample-private-registry.md index 3f0de73..b8c230b 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -39,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/) From 8cfed61124342b8acf6c79a05fb6f0ac89f26821 Mon Sep 17 00:00:00 2001 From: Manuel Vogel Date: Mon, 31 May 2021 09:56:58 +0200 Subject: [PATCH 123/156] fix: remove dash from COMMIT_MESSAGE pattern item because it belongs to the type filtergroup item above and is not a new item in the list. --- doc_source/github-webhook.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md index fe4c263..0941180 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -242,5 +242,5 @@ CodeBuildProject: - - Type: EVENT Pattern: PUSH - Type: COMMIT_MESSAGE - - Pattern: \[CodeBuild\] -``` \ No newline at end of file + Pattern: \[CodeBuild\] +``` From 6f9a09e97e320f7309d2c4382256895be3ff8ac9 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 1 Jun 2021 16:13:48 +0000 Subject: [PATCH 124/156] General updates --- doc_source/github-webhook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md index 0941180..0b47374 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -243,4 +243,4 @@ CodeBuildProject: Pattern: PUSH - Type: COMMIT_MESSAGE Pattern: \[CodeBuild\] -``` +``` \ No newline at end of file From 88522b338d829b50ab4dcec32b0dbb084b561ae2 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 29 Jun 2021 18:45:16 +0000 Subject: [PATCH 125/156] General update --- .../auth-and-access-control-permissions-reference.md | 6 +++--- doc_source/build-env-ref-available.md | 2 +- doc_source/builds-working.md | 11 +++++++---- doc_source/change-project-console.md | 2 +- doc_source/create-project-cli.md | 2 +- doc_source/create-project-console.md | 4 ++-- doc_source/history.md | 2 +- doc_source/use-vpc-endpoints-with-codebuild.md | 2 +- 8 files changed, 17 insertions(+), 14 deletions(-) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 057ac08..9f1f5f1 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -39,7 +39,7 @@ BatchGetReports Required to get information about reports\. **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` -BatchPutTestCases ¹ +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 ` @@ -51,7 +51,7 @@ Required to create build projects\. + `arn:aws:codebuild:region-ID:account-ID:project/project-name ` + `arn:aws:iam:account-ID:role/role-name ` -CreateReport ¹ +CreateReport ¹ **Action:** `codebuild:CreateReport` Required to create a test report\. **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` @@ -163,7 +163,7 @@ Required to change information about builds\. + `arn:aws:codebuild:region-ID:account-ID:project/project-name ` + `arn:aws:iam:account-ID:role/role-name ` -UpdateReport ¹ +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 ` diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 5833a00..5453c90 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -9,7 +9,7 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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\-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: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: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:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | | 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) | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | diff --git a/doc_source/builds-working.md b/doc_source/builds-working.md index f9d150d..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\. diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 1044a03..15a18f0 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -151,7 +151,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo ``` - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & - - timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" + - timeout 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**\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index f42d077..f88ae55 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -395,7 +395,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo ``` - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & -- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" +- timeout 15 sh -c "until docker info; do echo .; sleep 1; done" ``` ### serviceRole diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index b7e05cc..1c6d00a 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -29,7 +29,7 @@ Enter an optional description of the build project to help other users understan \(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\. -**Enable concurrent build limit** +**Enable concurrent build limit** \(Optional\) 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**\. @@ -184,7 +184,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo ``` - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 & -- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" +- timeout 15 sh -c "until docker info; do echo .; sleep 1; done" ``` **Service role** diff --git a/doc_source/history.md b/doc_source/history.md index e60ccdf..647fa50 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -50,7 +50,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 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 | +| [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 diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index 7fefd42..c950f88 100644 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ b/doc_source/use-vpc-endpoints-with-codebuild.md @@ -8,7 +8,7 @@ You can improve the security of your builds by configuring AWS CodeBuild to use **Note** Use a [NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html) if you want to use CodeBuild with AWS services that do not support Amazon VPC PrivateLink connections\. -+ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP option sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. ++ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP option sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. + VPC endpoints currently do not support cross\-Region requests\. Make sure that you create your endpoint in the same AWS Region as any S3 buckets that store your build input and output\. You can use the Amazon S3 console or the [get\-bucket\-location](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-bucket-location.html) command to find the location of your bucket\. Use a Region\-specific Amazon S3 endpoint to access your bucket \(for example, `mybucket.s3-us-west-2.amazonaws.com`\)\. For more information about Region\-specific endpoints for Amazon S3, see [Amazon Simple Storage Service](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the *Amazon Web Services General Reference*\. If you use the AWS CLI to make requests to Amazon S3, set your default Region to the same Region where your bucket was created, or use the `--region` parameter in your requests\. ## Creating VPC endpoints for CodeBuild From 441d31fdf4e241a5ff61bdb47d3dd5d1437d8404 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 9 Jul 2021 16:15:00 +0000 Subject: [PATCH 126/156] General update --- ...ntrol-iam-access-control-identity-based.md | 2 +- doc_source/batch-build-buildspec.md | 54 ++++++++++--------- doc_source/batch-build.md | 32 ++++++----- doc_source/build-env-ref-compute-types.md | 40 ++++++-------- doc_source/session-manager.md | 2 +- doc_source/troubleshooting.md | 2 +- 6 files changed, 66 insertions(+), 66 deletions(-) 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..a561d86 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 @@ -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/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index a036fc3..cabc026 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -7,11 +7,11 @@ This topic contains the buildspec reference for batch build properties\. Optional mapping\. The batch build settings for the project\. batch/**fast\-fail** -Optional\. +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 if one of the builds fails\. +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\. @@ -56,11 +56,11 @@ The identifier of the environment type to use for the task\. See **Environment t 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 whether failures in the batch can be ignored\. +Optional\. A Boolean value that indicates if a failure of this build task can be ignored\. `false` -The default value\. If one build task fails, the batch build will fail\. +The default value\. If this build task fails, the batch build will fail\. `true` -If one build task fails, the remaining build tasks will still run\. +If this build task fails, the batch build can still succeed\. The following is an example of a build graph buildspec entry: @@ -70,17 +70,20 @@ batch: build-graph: - identifier: build1 env: - compute-type: BUILD_GENERAL1_SMALL - debug-session: true + variables: + BUILD_ID: build1 + ignore-failure: false - identifier: build2 + buildspec: build2.yml env: - compute-type: BUILD_GENERAL1_MEDIUM + variables: + BUILD_ID: build2 depend-on: - build1 - debug-session: false - identifier: build3 env: - compute-type: BUILD_GENERAL1_LARGE + variables: + BUILD_ID: build3 depend-on: - build2 ``` @@ -118,11 +121,11 @@ The identifier of the environment type to use for the task\. See **Environment t 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 whether failures in the batch can be ignored\. +Optional\. A Boolean value that indicates if a failure of this build task can be ignored\. `false` -The default value\. If one build task fails, the batch build will fail\. +The default value\. If this build task fails, the batch build will fail\. `true` -If one build task fails, the remaining build tasks will still run\. +If this build task fails, the batch build can still succeed\. The following is an example of a build list buildspec entry: @@ -130,16 +133,17 @@ The following is an example of a build list buildspec entry: batch: fast-fail: false build-list: - - identifier: linux_small + - identifier: build1 env: - compute-type: BUILD_GENERAL1_SMALL - ignore-failure: true - debug-session: true - - identifier: windows_medium + variables: + BUILD_ID: build1 + ignore-failure: false + - identifier: build2 + buildspec: build2.yml env: - type: WINDOWS_SERVER_2019_CONTAINER - image: aws/codebuild/windows-base:2019-1.0 - compute-type: BUILD_GENERAL1_MEDIUM + variables: + BUILD_ID: build2 + ignore-failure: true ``` ## `batch/build-matrix` @@ -149,11 +153,11 @@ Defines a *build matrix*\. A build matrix defines tasks with different configura **static** The static properties apply to all build tasks\. **ignore\-failure** -Optional\. A Boolean value that indicates whether failures in the batch can be ignored\. +Optional\. A Boolean value that indicates if a failure of this build task can be ignored\. `false` -The default value\. If one build task fails, the batch build will fail\. +The default value\. If this build task fails, the batch build will fail\. `true` -If one build task fails, the remaining build tasks will still run\. +If this build task fails, the batch build can still succeed\. **env** Optional\. The build environment overrides for all tasks\. **compute\-type** @@ -182,7 +186,7 @@ An array that contains the identifiers of the compute types to use for these tas **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, \. +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: diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index 9d64194..d0de92e 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -34,17 +34,20 @@ batch: build-graph: - identifier: build1 env: - compute-type: BUILD_GENERAL1_SMALL - debug-session: true + variables: + BUILD_ID: build1 + ignore-failure: false - identifier: build2 + buildspec: build2.yml env: - compute-type: BUILD_GENERAL1_MEDIUM + variables: + BUILD_ID: build2 depend-on: - build1 - debug-session: false - identifier: build3 env: - compute-type: BUILD_GENERAL1_LARGE + variables: + BUILD_ID: build3 depend-on: - build2 ``` @@ -60,22 +63,23 @@ For more information about the build graph buildspec syntax, see [`batch/build-g A build list defines a number of tasks that run in parallel\. -The following example defines a build list\. The `linux_small` and `windows_medium` builds will be 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: linux_small + - identifier: build1 env: - compute-type: BUILD_GENERAL1_SMALL - ignore-failure: true - debug-session: true - - identifier: windows_medium + variables: + BUILD_ID: build1 + ignore-failure: false + - identifier: build2 + buildspec: build2.yml env: - type: WINDOWS_SERVER_2019_CONTAINER - image: aws/codebuild/windows-base:2019-1.0 - compute-type: BUILD_GENERAL1_MEDIUM + 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)\. diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index a23ace3..3767bb6 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -3,19 +3,24 @@ 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 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\. +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)\. + 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\) @@ -41,7 +46,7 @@ Some environment and compute types have Region availability limitations: + Asia Pacific \(Tokyo\) + Europe \(Frankfurt\) + Europe \(Ireland\) -+ The compute type `build.general1.2xlarge` is only available in these Regions: ++ The compute type `BUILD_GENERAL1_2XLARGE` is only available in these Regions: + US East \(Ohio\) + US East \(N\. Virginia\) + US West \(N\. California\) @@ -63,24 +68,11 @@ Some environment and compute types have Region availability limitations: + Middle East \(Bahrain\) + South America \(São Paulo\) -For the compute type `build.general1.2xlarge`, Docker images up to 100 GB uncompressed are supported\. - - -**Operating system: Windows** - -| Compute type | computeType value | Memory | vCPUs | Disk space | Environment type | -| --- | --- | --- | --- | --- | --- | -| build\.general1\.medium | BUILD\_GENERAL1\_MEDIUM | 7 GB | 4 | 128 GB | WINDOWS\_SERVER\_2019\_CONTAINER | -| build\.general1\.large | BUILD\_GENERAL1\_LARGE | 15 GB | 8 | 128 GB | WINDOWS\_SERVER\_2019\_CONTAINER | +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-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)\. - 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/session-manager.md b/doc_source/session-manager.md index f6b94d7..2c74fa1 100644 --- a/doc_source/session-manager.md +++ b/doc_source/session-manager.md @@ -19,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: diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index f399175..8941493 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -297,7 +297,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)\. From c3a62c911e35552674cc6c1de3463428b55135f1 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 9 Jul 2021 20:26:32 +0000 Subject: [PATCH 127/156] Update runtime versions sample --- doc_source/sample-runtime-versions.md | 117 +++++++++++--------------- 1 file changed, 51 insertions(+), 66 deletions(-) diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index 700a8fe..d453cce 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 buildspec 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: - - ``` - phases: - install: - runtime-versions: - java: openjdk11 - ``` - - 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: +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: - nodejs: 8 + python: 3.7 ``` -+ A `runtime-versions` section that specifies Node\.js version 10: ++ A `runtime-versions` section that specifies Python version 3\.8: ``` phases: install: runtime-versions: - nodejs: 10 + python: 3.8 ``` - 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,11 +66,11 @@ 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) @@ -102,7 +86,7 @@ └── 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,7 +153,7 @@ 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\. @@ -185,9 +169,9 @@ The build project in this example uses source code in the GitHub [AWS samples](h + 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 +189,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 +210,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 +233,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 +247,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 +263,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 +272,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,7 +294,7 @@ 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 @@ -335,25 +319,26 @@ The build project in this example uses source code in the GitHub [AWS samples](h + For **Runtime\(s\)**, choose **Standard**\. + 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 From 59bdade5c4c67e545d302c34f25990a79f18d253 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 15 Jul 2021 16:35:40 +0000 Subject: [PATCH 128/156] General update --- doc_source/data-protection.md | 2 +- doc_source/sample-ecr.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 1105ae7..d6b9f9d 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -10,7 +10,7 @@ For data protection purposes, we recommend that you protect AWS account credenti + 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\. When you provide a URL to an external server, don't 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*\. diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 8b0f7c9..6b84073 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\.\) ``` { From e40472b095f6cd185e3580427fe8cdccaad4174e Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 21 Jul 2021 15:14:09 +0000 Subject: [PATCH 129/156] General update --- ...nd-access-control-permissions-reference.md | 6 +- doc_source/build-env-ref-available.md | 2 +- doc_source/build-env-ref-compute-types.md | 18 +- doc_source/change-project-console.md | 291 ++++++++++++------ doc_source/create-project-console.md | 2 +- doc_source/data-protection.md | 2 +- doc_source/setting-up.md | 47 +-- 7 files changed, 224 insertions(+), 144 deletions(-) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 9f1f5f1..057ac08 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -39,7 +39,7 @@ BatchGetReports Required to get information about reports\. **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` -BatchPutTestCases ¹ +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 ` @@ -51,7 +51,7 @@ Required to create build projects\. + `arn:aws:codebuild:region-ID:account-ID:project/project-name ` + `arn:aws:iam:account-ID:role/role-name ` -CreateReport ¹ +CreateReport ¹ **Action:** `codebuild:CreateReport` Required to create a test report\. **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` @@ -163,7 +163,7 @@ Required to change information about builds\. + `arn:aws:codebuild:region-ID:account-ID:project/project-name ` + `arn:aws:iam:account-ID:role/role-name ` -UpdateReport ¹ +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 ` diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 5453c90..5833a00 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -9,7 +9,7 @@ AWS CodeBuild manages the following Docker images that are available in the Code | 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\-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: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: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:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | | 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) | | Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-1\.0 | N/A | diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index 3767bb6..deb4866 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -1,18 +1,18 @@ # 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: | Compute type | Environment computeType value | Environment type value | Memory | vCPUs | Disk space | | --- | --- | --- | --- | --- | --- | -| 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 | +| 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\. diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 15a18f0..71af0b2 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -1,5 +1,7 @@ # 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**\. @@ -8,14 +10,49 @@ + 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\. +You can modify the following sections: - Choose **Update configuration**\. +**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) - For more information about settings referred to in this procedure, see [Create a build project \(console\)](create-project-console.md)\. +## Project configuration -1. To change information about the source code location, in **Source**, choose **Edit**\. Use the following lists to make selections appropriate for your source provider, and then choose **Update source**\. -**Note** +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\. + +**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\. ------ @@ -61,20 +98,20 @@ Choose **Git clone depth** to create a shallow clone with a history truncated to **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\. +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)\. +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)\. **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\. +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 `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 **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\. +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\. - 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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub ] @@ -92,20 +129,20 @@ Choose **Git clone depth** to create a shallow clone with a history truncated to **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\. +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)\. +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)\. **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\. +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 **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\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ #### [ GitHub Enterprise Server ] @@ -131,49 +168,64 @@ The status of a build triggered by a webhook is always reported to your source p **Insecure SSL** Choose 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\. +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 **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\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. ------ - 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=overlay2 & - - timeout 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\. +## Environment -1. To change information about the VPC you created in Amazon VPC, in **Additional configuration**, change the values for **VPC**, **Subnets**, and **Security groups**\. +In the **Environment** section, choose **Edit**\. When your changes are complete, choose **Update configuration** to save the new configuration\. -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)\. +You can modify the following properties: -1. To change the amount of memory and vCPUs that are used to run builds, in **Additional configuration**, change the value for **Compute**\. +**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\. -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\. +**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\. - 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** +``` +- 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/`\. @@ -181,73 +233,124 @@ 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. Choose **Update environment**\. +## 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)\. -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\. +You can modify the following properties: -1. Choose **Update buildspec**\. +**Define batch configuration** +Select to allow batch builds in this project\. -1. To change information about the batch build configuration, in **Batch configuration**, choose **Edit** and update the folowing values as needed\. **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\. ++ 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\. ++ 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\. +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\. +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\. +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\. -1. Choose **Update batch configuration**\. - -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**\. +## Artifacts -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**\. +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: -1. To change your log settings, in **Logs**, select or clear **CloudWatch logs** and **S3 logs**\. +**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: - 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\. +1. For **Artifact identifier**, enter a value that is fewer than 128 characters and contains only alphanumeric characters and underscores\. - 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. Choose **Add artifact**\. -1. To change information about the way build output artifacts are stored, in **Additional configuration**, change the value of **Artifacts packaging**\. +1. Follow the previous steps to configure your secondary artifacts\. -1. To change whether build artifacts are encrypted, use **Disable artifacts encryption**\. +1. Choose **Save artifact**\. -1. Choose **Update artifacts**\. \ No newline at end of file +**Additional configuration** +**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`\. +**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\. 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)\. + +## 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/create-project-console.md b/doc_source/create-project-console.md index 1c6d00a..f188cb0 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -195,7 +195,7 @@ When you use the console to create a build project, you can create a CodeBuild s **Additional configuration** **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\. +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\. diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index d6b9f9d..845b394 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -10,7 +10,7 @@ For data protection purposes, we recommend that you protect AWS account credenti + 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 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\. 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*\. diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index 83dca49..5d088f4 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -274,9 +274,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 +282,7 @@ The service role described on this page contains a policy that grants the minimu "Action": [ "codecommit:GitPull" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3GetObjectPolicy", @@ -295,9 +291,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 +299,7 @@ The service role described on this page contains a policy that grants the minimu "Action": [ "s3:PutObject" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "ECRPullPolicy", @@ -317,9 +309,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 +317,7 @@ The service role described on this page contains a policy that grants the minimu "Action": [ "ecr:GetAuthorizationToken" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3BucketIdentity", @@ -338,8 +326,7 @@ The service role described on this page contains a policy that grants the minimu "s3:GetBucketAcl", "s3:GetBucketLocation" ], - "Resource": - "*" + "Resource": "*" } ] } @@ -398,9 +385,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 +393,7 @@ If you use a different name, be sure to use it throughout this procedure\. "Action": [ "codecommit:GitPull" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3GetObjectPolicy", @@ -419,9 +402,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 +410,7 @@ If you use a different name, be sure to use it throughout this procedure\. "Action": [ "s3:PutObject" ], - "Resource": [ - "*" - ] + "Resource": "*" }, { "Sid": "S3BucketIdentity", @@ -440,9 +419,7 @@ If you use a different name, be sure to use it throughout this procedure\. "s3:GetBucketAcl", "s3:GetBucketLocation" ], - "Resource": [ - "*" - ] + "Resource": "*" } ] } From 5af28d09d26a36cc9c462ab3f2b799a329a07ab2 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 30 Jul 2021 18:24:42 +0000 Subject: [PATCH 130/156] General update --- doc_source/change-project-console.md | 70 +++++++++++----------------- doc_source/create-project-console.md | 70 +++++++++++----------------- doc_source/endpoint-specify.md | 4 +- doc_source/history.md | 2 +- 4 files changed, 57 insertions(+), 89 deletions(-) diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 71af0b2..72f7185 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -79,8 +79,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 ] @@ -95,23 +95,17 @@ 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\. +**Git submodules** +Select **Use Git submodules** 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\. - -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)\. - -**Note** +**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)\. 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\. - -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 **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\. -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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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 ] @@ -126,55 +120,45 @@ 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\. +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. -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)\. - -**Note** +**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)\. 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\. - -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 **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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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\. 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)\. The status of a build triggered by a webhook is always reported to your source provider\. - - **Insecure SSL** -Choose 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 **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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +**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)\. ------ diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index f188cb0..6f018f2 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -70,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 ] @@ -86,23 +86,17 @@ 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\. +**Git submodules** +Select **Use Git submodules** 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\. - -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)\. - -**Note** +**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)\. 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\. - -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 **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\. -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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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 ] @@ -117,55 +111,45 @@ 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\. +**Git submodules** +Select **Use Git submodules** if you want to include Git submodules in your repository\. -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)\. - -**Note** +**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)\. 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\. - -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 **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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +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\. 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)\. The status of a build triggered by a webhook is always reported to your source provider\. - - **Insecure SSL** -Choose 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 **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 [GitHub webhook events](github-webhook.md) and [Bitbucket webhook events](bitbucket-webhook.md)\. +**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)\. ------ 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/history.md b/doc_source/history.md index 647fa50..b1493a6 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,7 +2,7 @@ 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: **March 3, 2021 ++ **Latest documentation update:** March 3rd, 2021 | Change | Description | Date | | --- |--- |--- | From b589f80a69855e985c22b82d8c19c2ca2fe2ff11 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 3 Aug 2021 20:17:40 +0000 Subject: [PATCH 131/156] General update --- ...auth-and-access-control-iam-access-control-identity-based.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 a561d86..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 From dc437971b6c4ecbebccf6de21d46c9ed48fba45d Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 13 Aug 2021 17:35:29 +0000 Subject: [PATCH 132/156] Document new features --- ...nd-access-control-permissions-reference.md | 7 ++++++ doc_source/build-env-ref-env-vars.md | 3 +++ doc_source/builds-projects-and-builds.md | 2 +- doc_source/change-project-console.md | 16 ++++++++++++ doc_source/history.md | 3 ++- doc_source/index.md | 1 + doc_source/public-builds.md | 25 +++++++++++++++++++ doc_source/welcome.md | 16 +++++------- doc_source/working-with-build-projects.md | 3 ++- 9 files changed, 63 insertions(+), 13 deletions(-) create mode 100644 doc_source/public-builds.md diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 057ac08..ff622e0 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -163,6 +163,13 @@ Required to change information about builds\. + `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\. diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md index 10734c9..f760c22 100644 --- a/doc_source/build-env-ref-env-vars.md +++ b/doc_source/build-env-ref-env-vars.md @@ -35,6 +35,9 @@ The identifier of the AWS KMS key that CodeBuild is using to encrypt the build o 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 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/change-project-console.md b/doc_source/change-project-console.md index 72f7185..ef7065d 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -42,6 +42,22 @@ If you want to limit the number of concurrent builds for this project, perform t 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\. diff --git a/doc_source/history.md b/doc_source/history.md index b1493a6..22ddc42 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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:** March 3rd, 2021 ++ **Latest documentation update:** August 11, 2021 | Change | Description | Date | | --- |--- |--- | +| [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 | diff --git a/doc_source/index.md b/doc_source/index.md index 0b13842..6c66743 100644 --- a/doc_source/index.md +++ b/doc_source/index.md @@ -109,6 +109,7 @@ Amazon's trademarks and trade dress may not be used in + [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) 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/welcome.md b/doc_source/welcome.md index 8417428..d9b2e98 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -1,19 +1,15 @@ # 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 diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md index 9292e7f..21a1fb5 100644 --- a/doc_source/working-with-build-projects.md +++ b/doc_source/working-with-build-projects.md @@ -17,4 +17,5 @@ You can perform these tasks when working with build projects: + [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) -+ [Batch builds in AWS CodeBuild](batch-build.md) \ No newline at end of file ++ [Batch builds in AWS CodeBuild](batch-build.md) ++ [Public build projects in AWS CodeBuild](public-builds.md) \ No newline at end of file From 30208ec250695cb5ff39f08c354f409de2b5b061 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 16 Aug 2021 23:15:56 +0000 Subject: [PATCH 133/156] Add batch report mode feature --- doc_source/batch-build.md | 9 +++++++++ doc_source/change-project-console.md | 26 +++++++++++++++++--------- doc_source/create-project-cli.md | 10 +++++++++- doc_source/create-project-console.md | 23 +++++++++++++++++------ doc_source/history.md | 3 ++- 5 files changed, 54 insertions(+), 17 deletions(-) diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index d0de92e..dab320a 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -5,6 +5,7 @@ You can use AWS CodeBuild to run concurrent and coordinated builds of a project **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 @@ -129,6 +130,14 @@ 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: diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index ef7065d..be5f1a5 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -117,9 +117,10 @@ Select **Use Git submodules** if you want to include Git submodules in your repo **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)\. -The status of a build triggered by a webhook is always reported to your source provider\. 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\. +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)\. @@ -142,9 +143,10 @@ Select **Use Git submodules** if you want to include Git submodules in your repo **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)\. -The status of a build triggered by a webhook is always reported to your source provider\. 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\. +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)\. @@ -167,9 +169,10 @@ Select **Use Git submodules** if you want to include Git submodules in your repo **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)\. -The status of a build triggered by a webhook is always reported to your source provider\. 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\. +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\. @@ -260,9 +263,6 @@ In the **Batch configuration** section, choose **Edit**\. When your changes are You can modify the following properties: -**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: @@ -284,6 +284,14 @@ 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\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index f88ae55..62471f2 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -162,7 +162,8 @@ Modify the JSON data as follows and save your results\. "" ] }, - "timeoutInMins": + "timeoutInMins": , + "batchReportMode": "REPORT_AGGREGATED_BATCH" | "REPORT_INDIVIDUAL_BUILDS" }, "concurrentBuildLimit": } @@ -480,6 +481,13 @@ An array of strings that specify the compute types that are allowed for the batc 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\. diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 6f018f2..e829202 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -92,9 +92,10 @@ Select **Use Git submodules** if you want to include Git submodules in your repo **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)\. -The status of a build triggered by a webhook is always reported to your source provider\. 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\. +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)\. @@ -117,9 +118,10 @@ Select **Use Git submodules** if you want to include Git submodules in your repo **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)\. -The status of a build triggered by a webhook is always reported to your source provider\. 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\. +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)\. @@ -142,9 +144,10 @@ Select **Use Git submodules** if you want to include Git submodules in your repo **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)\. -The status of a build triggered by a webhook is always reported to your source provider\. 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\. +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\. @@ -249,6 +252,14 @@ 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** diff --git a/doc_source/history.md b/doc_source/history.md index 22ddc42..a8e8331 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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:** August 11, 2021 ++ **Latest documentation update:** August 16, 2021 | Change | Description | Date | | --- |--- |--- | +| [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)\. | August 16, 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 | From 7240f12ca2c9df0c4987cea7b9d9cfe315364013 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 17 Aug 2021 17:14:47 +0000 Subject: [PATCH 134/156] General update --- .../auth-and-access-control-permissions-reference.md | 10 ++++++++++ doc_source/run-build-cli-auto-start.md | 2 +- doc_source/sample-runtime-versions.md | 7 +++++-- 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index ff622e0..64193fe 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -106,6 +106,16 @@ InvalidateProjectCache Required to reset the cache for a project\. **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:** `*` + +ListBuildBatchesForProjects + **Action:** `codebuild:ListBuildBatchesForProjects` +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` Required to get a list of build IDs\. 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/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md index d453cce..087c35f 100644 --- a/doc_source/sample-runtime-versions.md +++ b/doc_source/sample-runtime-versions.md @@ -160,13 +160,16 @@ The build project in this example uses source code in the GitHub [AWS samples](h 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**\. From 76cf25499ad1840510ca2c6050cb94b731a63a5c Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 19 Aug 2021 20:32:40 +0000 Subject: [PATCH 135/156] General update --- doc_source/batch-build.md | 9 --------- doc_source/change-project-console.md | 8 -------- doc_source/create-project-console.md | 8 -------- doc_source/history.md | 1 - doc_source/notice.md | 2 +- 5 files changed, 1 insertion(+), 27 deletions(-) diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index dab320a..d0de92e 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -5,7 +5,6 @@ You can use AWS CodeBuild to run concurrent and coordinated builds of a project **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 @@ -130,14 +129,6 @@ 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: diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index be5f1a5..2e845f8 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -284,14 +284,6 @@ 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\. diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index e829202..aca23a1 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -252,14 +252,6 @@ 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** diff --git a/doc_source/history.md b/doc_source/history.md index a8e8331..76cf5bb 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -6,7 +6,6 @@ The following table describes the important changes to the documentation since t | Change | Description | Date | | --- |--- |--- | -| [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)\. | August 16, 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 | diff --git a/doc_source/notice.md b/doc_source/notice.md index 16a129c..30b657e 100644 --- a/doc_source/notice.md +++ b/doc_source/notice.md @@ -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\) From 7aea1c88b55212ca8fccc510615dba831f16e7c7 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 25 Aug 2021 20:53:26 +0000 Subject: [PATCH 136/156] Syncing content --- doc_source/sample-multi-in-out.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index 4e9dcf7..7317d22 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -83,6 +83,8 @@ phases: - touch file2 artifacts: + files: + - '**.*' secondary-artifacts: artifact1: base-directory: $CODEBUILD_SRC_DIR_source1 From 59db953d4f21fb735dcb1935bfc905d7969832e1 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 31 Aug 2021 17:32:27 +0000 Subject: [PATCH 137/156] General doc sync --- doc_source/change-project-console.md | 4 ++-- doc_source/create-project-cli.md | 2 +- doc_source/create-project-console.md | 4 ++-- ...etting-started-cli-create-build-project.md | 2 +- doc_source/report-group-export-settings.md | 6 +++--- doc_source/security-encryption.md | 12 +++++------ doc_source/security-key-management.md | 2 +- doc_source/setting-up.md | 20 +++++++++---------- doc_source/test-report-group-create-cli.md | 2 +- .../test-report-group-create-console.md | 4 ++-- doc_source/update-report-group-cli.md | 10 +++++----- doc_source/update-report-group-console.md | 10 +++++----- 12 files changed, 39 insertions(+), 39 deletions(-) diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index 2e845f8..e1064a3 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -312,8 +312,8 @@ For each secondary set of artifacts you want: **Additional configuration** **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`\. ++ 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**\. diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 62471f2..2095c5c 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -413,7 +413,7 @@ Optional\. The number of minutes, between 5 to 480 \(8 hours\), after which Code ### 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\. +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 diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index aca23a1..dde5517 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -276,8 +276,8 @@ For each secondary set of artifacts you want: **Additional configuration** **Encryption key** \(Optional\) 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`\. ++ 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**\. diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md index 140858e..43a6ab1 100644 --- a/doc_source/getting-started-cli-create-build-project.md +++ b/doc_source/getting-started-cli-create-build-project.md @@ -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/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/security-encryption.md b/doc_source/security-encryption.md index ab8d189..6fca4a5 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*\. +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 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#cli.encryptionkey)\. + + 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** \- CodeBuild requires access to a KMS key in order to encrypt its build output artifacts\. By default, CodeBuild uses an AWS managed key Amazon S3\. If you do not want to use this AWS managed key, you must create and configure a customer managed key\. For more information [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index 495e7da..e752043 100644 --- a/doc_source/security-key-management.md +++ b/doc_source/security-key-management.md @@ -1,6 +1,6 @@ # 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 CodeBuild 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)\. diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index 5d088f4..fec2fd8 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 @@ -437,15 +437,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\. ``` { @@ -509,14 +509,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/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md index a6c9efd..c2d8a83 100644 --- a/doc_source/test-report-group-create-cli.md +++ b/doc_source/test-report-group-create-cli.md @@ -33,7 +33,7 @@ + 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 master key \(CMK\)\. For more information, see [Update a report group](report-group-export-settings.md)\. + + 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: ``` diff --git a/doc_source/test-report-group-create-console.md b/doc_source/test-report-group-create-console.md index dd0ced9..3c131b3 100644 --- a/doc_source/test-report-group-create-console.md +++ b/doc_source/test-report-group-create-console.md @@ -25,8 +25,8 @@ 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:::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*\. + + **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)\. diff --git a/doc_source/update-report-group-cli.md b/doc_source/update-report-group-cli.md index 9aacc11..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": [] 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 From bc351b0370f31c05673d150bdc2b2f1b2c0d1874 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 10 Sep 2021 16:52:49 +0000 Subject: [PATCH 138/156] General update --- ...ntrol-iam-identity-based-access-control.md | 485 ++++++++++-------- doc_source/create-project-cli.md | 2 +- doc_source/monitoring-alarms.md | 9 +- doc_source/sample-build-notifications.md | 21 - 4 files changed, 284 insertions(+), 233 deletions(-) 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 e2d6f82..b2dcf21 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 @@ -87,100 +87,137 @@ 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": "*" + } + ] } ``` @@ -192,76 +229,105 @@ 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" } ``` @@ -273,49 +339,60 @@ 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" } ``` diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index 2095c5c..c283109 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -446,7 +446,7 @@ aws ec2 describe-security-groups --filters "Name=vpc-id,Values=" -- -Optional\. Specifies whener to include build badges with your CodeBuild project\. Set to `true` to enable build baddes, or `false` otehrwise\. For more information, see [Build badges sample with CodeBuild](sample-build-badges.md)\. +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 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/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 52d1325..2511b02 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -123,13 +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\. @@ -256,24 +249,10 @@ 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 CodeBuild directly](how-to-run.md)\. From fe19265e544cc59b5f51628113357505b254a27d Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 17 Sep 2021 23:25:34 +0000 Subject: [PATCH 139/156] General update --- ...ntrol-iam-identity-based-access-control.md | 62 +++++++++---------- doc_source/build-env-ref-compute-types.md | 1 + doc_source/history.md | 3 +- .../use-vpc-endpoints-with-codebuild.md | 2 +- 4 files changed, 35 insertions(+), 33 deletions(-) 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 b2dcf21..7314817 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 @@ -966,38 +966,38 @@ 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": [ + "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/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index deb4866..d766537 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -5,6 +5,7 @@ AWS CodeBuild provides build environments with the following available memory, | Compute type | Environment computeType value | Environment type value | Memory | vCPUs | Disk space | | --- | --- | --- | --- | --- | --- | +| 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 | diff --git a/doc_source/history.md b/doc_source/history.md index 76cf5bb..fd32c67 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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:** August 16, 2021 ++ **Latest documentation update:** September 13, 2021 | Change | Description | Date | | --- |--- |--- | +| [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 | diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index c950f88..7fefd42 100644 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ b/doc_source/use-vpc-endpoints-with-codebuild.md @@ -8,7 +8,7 @@ You can improve the security of your builds by configuring AWS CodeBuild to use **Note** Use a [NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html) if you want to use CodeBuild with AWS services that do not support Amazon VPC PrivateLink connections\. -+ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP option sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. ++ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP option sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. + VPC endpoints currently do not support cross\-Region requests\. Make sure that you create your endpoint in the same AWS Region as any S3 buckets that store your build input and output\. You can use the Amazon S3 console or the [get\-bucket\-location](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-bucket-location.html) command to find the location of your bucket\. Use a Region\-specific Amazon S3 endpoint to access your bucket \(for example, `mybucket.s3-us-west-2.amazonaws.com`\)\. For more information about Region\-specific endpoints for Amazon S3, see [Amazon Simple Storage Service](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the *Amazon Web Services General Reference*\. If you use the AWS CLI to make requests to Amazon S3, set your default Region to the same Region where your bucket was created, or use the `--region` parameter in your requests\. ## Creating VPC endpoints for CodeBuild From 0a682c32318e68653fb4bf10505ec4c7c9af67fe Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 28 Sep 2021 18:11:39 +0000 Subject: [PATCH 140/156] General update --- ...ntrol-iam-identity-based-access-control.md | 16 ++++++---- ...nd-access-control-permissions-reference.md | 6 ++-- doc_source/report-groups-sharing.md | 2 +- doc_source/sample-test-report-cli.md | 2 +- doc_source/security-encryption.md | 2 +- doc_source/security-key-management.md | 6 ++-- doc_source/security-traffic-privacy.md | 2 +- doc_source/setting-up.md | 32 ++++++++++++++----- doc_source/troubleshooting.md | 9 ------ 9 files changed, 43 insertions(+), 34 deletions(-) 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 7314817..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 @@ -632,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" } ] } @@ -744,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" } ] } @@ -991,10 +991,12 @@ The following example policy statement grants AWS CodeBuild permission to create "StringEquals": { "ec2:AuthorizedService": "codebuild.amazonaws.com" }, - "ArnEquals": [ - "arn:aws:ec2:region:account-id:subnet/subnet-id-1", - "arn:aws:ec2:region:account-id:subnet/subnet-id-2" - ] + "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 64193fe..145716b 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -49,7 +49,7 @@ CreateProject 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:iam::account-ID:role/role-name ` CreateReport ¹ **Action:** `codebuild:CreateReport` @@ -171,14 +171,14 @@ UpdateProject 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: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 ` ++ `arn:aws:iam::account-ID:role/role-name ` UpdateReport ¹ **Action:** `codebuild:UpdateReport` diff --git a/doc_source/report-groups-sharing.md b/doc_source/report-groups-sharing.md index ffd1275..182f100 100644 --- a/doc_source/report-groups-sharing.md +++ b/doc_source/report-groups-sharing.md @@ -99,7 +99,7 @@ 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" ] }, diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md index 8b6c617..d07f03e 100644 --- a/doc_source/sample-test-report-cli.md +++ b/doc_source/sample-test-report-cli.md @@ -147,7 +147,7 @@ Instead of the ARN of an existing report group, you can also specify a name for "image": "aws/codebuild/standard:4.0", "computeType": "small" }, - "serviceRole": "arn:aws:iam::role/service-role/" + "serviceRole": "arn:aws:iam:::role/service-role/" } ``` diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index 6fca4a5..e432325 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -7,4 +7,4 @@ Encryption is an important part of CodeBuild security\. Some encryption, such as 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** \- CodeBuild requires access to a KMS key in order to encrypt its build output artifacts\. By default, CodeBuild uses an AWS managed key Amazon S3\. If you do not want to use this AWS managed key, you must create and configure a customer managed key\. For more information [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file ++ **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 keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file diff --git a/doc_source/security-key-management.md b/doc_source/security-key-management.md index e752043..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 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)\. +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/setting-up.md b/doc_source/setting-up.md index fec2fd8..014bdd7 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -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\. diff --git a/doc_source/troubleshooting.md b/doc_source/troubleshooting.md index 8941493..3853910 100644 --- a/doc_source/troubleshooting.md +++ b/doc_source/troubleshooting.md @@ -16,7 +16,6 @@ Use the information in this topic to help you identify, diagnose, and address is + [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) @@ -272,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`\. From b1b1697e118d8ee79640d75d3e5ae4fa1bddb059 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Fri, 1 Oct 2021 16:29:04 +0000 Subject: [PATCH 141/156] General update --- doc_source/runtime-versions.md | 2 +- doc_source/security-encryption.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/runtime-versions.md b/doc_source/runtime-versions.md index d7138f3..05ecd2d 100644 --- a/doc_source/runtime-versions.md +++ b/doc_source/runtime-versions.md @@ -1,6 +1,6 @@ # Runtime versions -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\. +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\. **Ubuntu and Amazon Linux 2 platform runtime versions** diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md index e432325..e260b00 100644 --- a/doc_source/security-encryption.md +++ b/doc_source/security-encryption.md @@ -7,4 +7,4 @@ Encryption is an important part of CodeBuild security\. Some encryption, such as 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 keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)\. \ No newline at end of file ++ **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 From 0e5792357941fa61f5b69e2718ea8190fbc19766 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 6 Oct 2021 16:09:01 +0000 Subject: [PATCH 142/156] Add batch report mode --- doc_source/batch-build.md | 9 +++++++++ doc_source/change-project-console.md | 8 ++++++++ doc_source/create-project-console.md | 8 ++++++++ doc_source/getting-started-clean-up-console.md | 2 +- doc_source/getting-started-cli-clean-up.md | 2 +- doc_source/history.md | 3 ++- 6 files changed, 29 insertions(+), 3 deletions(-) diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index d0de92e..dab320a 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -5,6 +5,7 @@ You can use AWS CodeBuild to run concurrent and coordinated builds of a project **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 @@ -129,6 +130,14 @@ 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: diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index e1064a3..dae5686 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -284,6 +284,14 @@ 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\. diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index dde5517..71c37fc 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -252,6 +252,14 @@ 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** diff --git a/doc_source/getting-started-clean-up-console.md b/doc_source/getting-started-clean-up-console.md index e016aa1..673bc6e 100644 --- a/doc_source/getting-started-clean-up-console.md +++ b/doc_source/getting-started-clean-up-console.md @@ -2,7 +2,7 @@ \(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 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 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 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\. diff --git a/doc_source/getting-started-cli-clean-up.md b/doc_source/getting-started-cli-clean-up.md index 367dac8..58fb3a6 100644 --- a/doc_source/getting-started-cli-clean-up.md +++ b/doc_source/getting-started-cli-clean-up.md @@ -2,7 +2,7 @@ \(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 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 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 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\. diff --git a/doc_source/history.md b/doc_source/history.md index fd32c67..c2dc914 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -2,10 +2,11 @@ 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:** September 13, 2021 ++ **Latest documentation update:** October 4th, 2021 | Change | Description | Date | | --- |--- |--- | +| [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 | From d81018aa06e3525040d010570bd3249e7394ed7b Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 25 Oct 2021 16:47:40 +0000 Subject: [PATCH 143/156] General update --- doc_source/runtime-versions.md | 2 +- doc_source/use-codebuild-agent.md | 42 +++++++++++++++++++------------ 2 files changed, 27 insertions(+), 17 deletions(-) diff --git a/doc_source/runtime-versions.md b/doc_source/runtime-versions.md index 05ecd2d..bf0d8c8 100644 --- a/doc_source/runtime-versions.md +++ b/doc_source/runtime-versions.md @@ -1,6 +1,6 @@ # 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\. +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** diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index bd862c7..4ae30b6 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -16,39 +16,47 @@ You only need to set up the build image the first time you run the agent, or whe **To set up the build image** -1. Clone the CodeBuild image repo: +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: ``` - $ git clone https://github.com/aws/aws-codebuild-docker-images.git + $ docker pull public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:3.0 ``` -1. Change to the image directory\. For this example, use the `aws/codebuild/standard:5.0` image: + Alternatively, if you want to use another Linux image, perform the following steps: - ``` - $ cd aws-codebuild-docker-images/ubuntu/standard/5.0 - ``` + 1. Clone the CodeBuild image repo: -1. Build the image\. This will take several minutes\. + ``` + $ git clone https://github.com/aws/aws-codebuild-docker-images.git + ``` - ``` - $ docker build -t aws/codebuild/standard:5.0 . - ``` + 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 amazon/aws-codebuild-local:latest --disable-content-trust=false + $ docker pull public.ecr.aws/codebuild/local-builds:latest ``` To download the ARM version of the agent, run the following command: ``` - $ docker pull amazon/aws-codebuild-local:aarch64 --disable-content-trust=false + $ docker pull public.ecr.aws/codebuild/local-builds:aarch64 ``` -1. The CodeBuild agent is available from [https://hub\.docker\.com/r/amazon/aws\-codebuild\-local/](https://hub.docker.com/r/amazon/aws-codebuild-local/)\. +1. The CodeBuild agent is available from [https://gallery\.ecr\.aws/codebuild/local\-builds](https://gallery.ecr.aws/codebuild/local-builds)\. The Secure Hash Algorithm \(SHA\) signature for the x86\_64 version of the agent is: @@ -65,7 +73,7 @@ You only need to set up the build image the first time you run the agent, or whe You can use the SHA to identify the version of the agent\. To see the agent's SHA signature, run the following command: ``` - $ docker inspect amazon/aws-codebuild-local + $ docker inspect public.ecr.aws/codebuild/local-builds:latest ``` ## Run the CodeBuild agent @@ -86,15 +94,17 @@ You only need to set up the build image the first time you run the agent, or whe To run an x86\_64 build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a + $ ./codebuild_build.sh -i -a ``` To run an ARM build, run the following command: ``` - $ ./codebuild_build.sh -i aws/codebuild/standard:5.0 -a -l amazon/aws-codebuild-local:aarch64 + $ ./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 From 572ab08383294561b7c45dbeefd68e7c6bff8e3a Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 2 Nov 2021 20:37:44 +0000 Subject: [PATCH 144/156] Updates per https://github.com/awsdocs/aws-codebuild-user-guide/issues/88 --- doc_source/batch-build-buildspec.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index cabc026..02fe77a 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -53,7 +53,7 @@ A Boolean value that indicates whether to run the Docker daemon inside a Docker **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, \. +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\. @@ -118,7 +118,7 @@ A Boolean value that indicates whether to run the Docker daemon inside a Docker **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, \. +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\. @@ -167,13 +167,7 @@ The identifier of the image to use for the task\. See **Image identifier** in [D **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, \. -**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 these tasks\. See **Environment Type** in [Build environment compute types](build-env-ref-compute-types.md) for possible values\. +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\. From 4559e91530d50870e135129c8a3a6685ff8edf2d Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 4 Nov 2021 19:21:06 +0000 Subject: [PATCH 145/156] Remove suspected unused properties --- doc_source/batch-build-buildspec.md | 8 -------- doc_source/batch-build.md | 4 ---- 2 files changed, 12 deletions(-) diff --git a/doc_source/batch-build-buildspec.md b/doc_source/batch-build-buildspec.md index 02fe77a..46e1415 100644 --- a/doc_source/batch-build-buildspec.md +++ b/doc_source/batch-build-buildspec.md @@ -160,10 +160,6 @@ The default value\. If this build task fails, the batch build will fail\. If this build task fails, the batch build can still succeed\. **env** Optional\. The build environment overrides for all tasks\. -**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** @@ -189,10 +185,6 @@ batch: build-matrix: static: ignore-failure: false - env: - type: LINUX_CONTAINER - image: aws/codebuild/amazonlinux2-x86_64-standard:3.0 - privileged-mode: true dynamic: buildspec: - matrix1.yml diff --git a/doc_source/batch-build.md b/doc_source/batch-build.md index dab320a..2598333 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -96,10 +96,6 @@ batch: build-matrix: static: ignore-failure: false - env: - type: LINUX_CONTAINER - image: aws/codebuild/amazonlinux2-x86_64-standard:3.0 - privileged-mode: true dynamic: buildspec: - matrix1.yml From 8995254f44bcc71caee7ef9d6f74477acc0d8c63 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Tue, 16 Nov 2021 20:44:04 +0000 Subject: [PATCH 146/156] General update --- doc_source/sample-build-badges.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc_source/sample-build-badges.md b/doc_source/sample-build-badges.md index 5905ef3..9c4729d 100644 --- a/doc_source/sample-build-badges.md +++ b/doc_source/sample-build-badges.md @@ -73,12 +73,10 @@ https://codebuild.us-east-1.amazon.com/badges?uuid=...&tag= ## Publish your CodeBuild build badges -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\. - -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=main) +![]() ``` ## CodeBuild badge statuses From da1f744a4311585d9b533083e3643085bb1fe239 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Thu, 18 Nov 2021 21:48:30 +0000 Subject: [PATCH 147/156] Doc sync --- doc_source/how-to-integrate-config.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/doc_source/how-to-integrate-config.md b/doc_source/how-to-integrate-config.md index 8dcf61f..a321a2b 100644 --- a/doc_source/how-to-integrate-config.md +++ b/doc_source/how-to-integrate-config.md @@ -31,12 +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**\. @@ -48,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 From fe0b0b46112717ea56d9eabfdc40d48394db9943 Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Mon, 20 Dec 2021 19:39:05 +0000 Subject: [PATCH 148/156] General update --- doc_source/bitbucket-webhook.md | 12 ++++++------ doc_source/build-caching.md | 2 +- doc_source/codecov-integration.md | 4 ++-- doc_source/concepts.md | 2 +- doc_source/github-webhook.md | 12 ++++++------ doc_source/how-to-create-pipeline-add-test.md | 2 +- doc_source/how-to-create-pipeline-add.md | 2 +- doc_source/monitoring-builds.md | 4 ++-- doc_source/monitoring-metrics.md | 4 ++-- doc_source/monitoring-utilization-metrics.md | 11 ++++++++--- doc_source/run-build-cli-auto-start.md | 2 +- doc_source/sample-build-notifications.md | 4 ++-- doc_source/sample-disable-artifact-encryption.md | 2 +- doc_source/sample-github-enterprise.md | 6 +++--- doc_source/sample-private-registry.md | 2 +- doc_source/use-proxy-server.md | 2 +- doc_source/use-vpc-endpoints-with-codebuild.md | 2 +- doc_source/view-build-details.md | 2 +- doc_source/welcome.md | 4 ++-- 19 files changed, 43 insertions(+), 38 deletions(-) diff --git a/doc_source/bitbucket-webhook.md b/doc_source/bitbucket-webhook.md index f754b8e..581fc00 100644 --- a/doc_source/bitbucket-webhook.md +++ b/doc_source/bitbucket-webhook.md @@ -54,32 +54,32 @@ You can find the webhook payload in the webhook settings of your Bitbucket repos 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-bitbucket.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes-bitbucket.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude-bitbucket.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor-bitbucket.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png) ## Filter Bitbucket webhook events \(SDK\) diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 210ecc4..2c77d09 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -64,7 +64,7 @@ For more information, see [Create a build project \(AWS CLI\)](create-project-cl You specify a cache in the **Artifacts** section of the console\. For **Cache type**, choose **Amazon S3** or **Local**\. If you choose **Local**, choose one or more of the three local cache options\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.png) For more information, see [Create a build project \(console\)](create-project-console.md)\. diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index aaa06ee..a11ffd4 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -13,7 +13,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif 1. In Codecov, add the repository for which you want coverage\. 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-token.png) 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)\. @@ -105,4 +105,4 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif ``` The reports look like the following: -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-report.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 +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-report.png) \ No newline at end of file diff --git a/doc_source/concepts.md b/doc_source/concepts.md index 5596971..358a927 100644 --- a/doc_source/concepts.md +++ b/doc_source/concepts.md @@ -12,7 +12,7 @@ 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/arch.png) diff --git a/doc_source/github-webhook.md b/doc_source/github-webhook.md index 0b47374..2529aec 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -50,32 +50,32 @@ In **Primary source webhook events**, select the following\. This section is onl 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-head-base-regexes.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-exclude.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-file-name-regex.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-actor.png) 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pull-request-webhook-filter-commit-message.png) ## Filter GitHub webhook events \(SDK\) diff --git a/doc_source/how-to-create-pipeline-add-test.md b/doc_source/how-to-create-pipeline-add-test.md index 9acb71e..f367c9f 100644 --- a/doc_source/how-to-create-pipeline-add-test.md +++ b/doc_source/how-to-create-pipeline-add-test.md @@ -45,7 +45,7 @@ This procedure shows you how to add a test action inside of a test stage between 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png) diff --git a/doc_source/how-to-create-pipeline-add.md b/doc_source/how-to-create-pipeline-add.md index 1624ed7..03f1f0e 100644 --- a/doc_source/how-to-create-pipeline-add.md +++ b/doc_source/how-to-create-pipeline-add.md @@ -47,7 +47,7 @@ This procedure shows you how to add a build action in a build stage between the 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png) diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md index 5506dc2..8cef7f1 100644 --- a/doc_source/monitoring-builds.md +++ b/doc_source/monitoring-builds.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-metrics.md b/doc_source/monitoring-metrics.md index 54c47c0..6e79693 100644 --- a/doc_source/monitoring-metrics.md +++ b/doc_source/monitoring-metrics.md @@ -46,7 +46,7 @@ You can customize the metrics and the graphs used to display them with the Cloud 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) 1. Choose **Account Metrics**\. @@ -61,7 +61,7 @@ You can customize the metrics and the graphs used to display them with the Cloud 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) 1. Choose **By Project**\. diff --git a/doc_source/monitoring-utilization-metrics.md b/doc_source/monitoring-utilization-metrics.md index a5eb08a..8d3679d 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) @@ -72,7 +77,7 @@ The Amazon CloudWatch console can be used to access CodeBuild resource utilizati 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) 1. Choose **By Project**\. @@ -91,7 +96,7 @@ The Amazon CloudWatch console can be used to access CodeBuild resource utilizati 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) 1. Choose **BuildId, BuildNumber, ProjectName**\. diff --git a/doc_source/run-build-cli-auto-start.md b/doc_source/run-build-cli-auto-start.md index ae94018..300d4e1 100644 --- a/doc_source/run-build-cli-auto-start.md +++ b/doc_source/run-build-cli-auto-start.md @@ -24,7 +24,7 @@ For GitHub, information similar to the following appears in the output: For GitHub Enterprise Server, information similar to the following appears in the output: -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png) 1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise Server\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 2511b02..6f12327 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -52,7 +52,7 @@ For more information, see [Editing customer managed policies](https://docs.aws.a 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/topic-arn.png) @@ -71,7 +71,7 @@ For more information, see [Editing customer managed policies](https://docs.aws.a 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-subscription.png) diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index 05752c0..9c56ac0 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -13,7 +13,7 @@ 1. In **Source**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub, and then choose **Authorize**\. For **Webhook**, select **Rebuild every time a code change is pushed to this repository**\. You can select this check box only if you chose **Use a repository in my account**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/webhook.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/webhook.png) 1. In **Environment**: diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index e5f046d..3e2a0e7 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -7,7 +7,7 @@ AWS CodeBuild supports GitHub Enterprise Server as a source repository\. This sa 1. Generate a personal access token for your CodeBuild project\. We recommend that you create a GitHub Enterprise user and generate a personal access token for this user\. Copy it to your clipboard so that it can be used 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\. When you create the personal access token, include the **repo** scope in the definition\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png) 1. Download your certificate from GitHub Enterprise Server\. CodeBuild uses the certificate to make a trusted SSL connection to the repository\. @@ -60,7 +60,7 @@ You only need to enter and save the personal access token once\. All future AWS + Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise Server project repository\. **Note** We recommend that you use **Enable insecure SSL** for testing only\. It should not be used in a production environment\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) 1. In **Environment**: @@ -122,6 +122,6 @@ If you need to generate a payload URL and secret key again, you must first delet 1. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. 1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ghe-webhook.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ghe-webhook.png) 1. Return to your CodeBuild project\. Close the **Create webhook** dialog box and choose **Start build**\. \ No newline at end of file diff --git a/doc_source/sample-private-registry.md b/doc_source/sample-private-registry.md index b8c230b..b7b3f95 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -42,7 +42,7 @@ 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/private-registry-sample-iam.png) 1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. **Note** diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index b18506c..3ec782d 100644 --- a/doc_source/use-proxy-server.md +++ b/doc_source/use-proxy-server.md @@ -26,7 +26,7 @@ There are two primary use cases for running CodeBuild in a proxy server: The following diagram shows how the components interact\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-proxy-transparent.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-proxy-transparent.png) ### Set up a VPC, subnets, and a network gateway diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index 7fefd42..ca057fc 100644 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ b/doc_source/use-vpc-endpoints-with-codebuild.md @@ -15,7 +15,7 @@ You can improve the security of your builds by configuring AWS CodeBuild to use Follow the instructions in [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png) *region* represents the region identifier for an AWS Region supported by CodeBuild, such as `us-east-2` for the US East \(Ohio\) Region\. For a list of supported AWS Regions, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the * AWS General Reference*\. The endpoint is prepopulated with the Region you specified when you signed in to AWS\. If you change your Region, the VPC endpoint is updated accordingly\. diff --git a/doc_source/view-build-details.md b/doc_source/view-build-details.md index 5305ff6..c1b84d4 100644 --- a/doc_source/view-build-details.md +++ b/doc_source/view-build-details.md @@ -51,7 +51,7 @@ 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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/build-phases.png) diff --git a/doc_source/welcome.md b/doc_source/welcome.md index d9b2e98..d1c53b6 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -17,7 +17,7 @@ You can use the AWS CodeBuild or AWS CodePipeline console to run CodeBuild\. You -![\[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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/overview.png) @@ -27,7 +27,7 @@ As the following diagram shows, you can add CodeBuild as a build or test action -![\[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/) +![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pipeline.png) From 5d6ac684625dba9ac87ca4cda168d971f8ca246f Mon Sep 17 00:00:00 2001 From: Strohm Armstrong Date: Wed, 22 Dec 2021 21:01:22 +0000 Subject: [PATCH 149/156] Fix typo in API name --- doc_source/auth-and-access-control-permissions-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md index 145716b..364ab35 100644 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ b/doc_source/auth-and-access-control-permissions-reference.md @@ -111,8 +111,8 @@ ListBuildBatches Required to get a list of build batch IDs\. **Resource:** `*` -ListBuildBatchesForProjects - **Action:** `codebuild:ListBuildBatchesForProjects` +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` From 3e9ccf431456f30cbefd3138e01b7b181b326af2 Mon Sep 17 00:00:00 2001 From: Matt Empson Date: Thu, 30 Dec 2021 15:54:35 +1100 Subject: [PATCH 150/156] itBucket is now a supported source provider in CodePipeline https://aws.amazon.com/about-aws/whats-new/2019/12/aws-codepipeline-now-supports-atlassian-bitbucket-cloud/ --- doc_source/how-to-create-pipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index a67021a..3ece23d 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -40,7 +40,7 @@ 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, 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*\. From 2b796efd69169b5a2a35bef57699371e0f5008a7 Mon Sep 17 00:00:00 2001 From: Matt Empson Date: Thu, 30 Dec 2021 16:00:34 +1100 Subject: [PATCH 151/156] Added BitBucket --- doc_source/how-to-create-pipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc_source/how-to-create-pipeline.md b/doc_source/how-to-create-pipeline.md index 3ece23d..0efa474 100644 --- a/doc_source/how-to-create-pipeline.md +++ b/doc_source/how-to-create-pipeline.md @@ -40,7 +40,7 @@ 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\. 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*\. From e0662e019a84f8eca74a06010395fbeaca2282d9 Mon Sep 17 00:00:00 2001 From: Amir Szekely Date: Wed, 8 Jun 2022 09:16:26 -0700 Subject: [PATCH 152/156] Fix JSON typo --- doc_source/sample-multi-in-out.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md index 7317d22..761bb81 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.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" } ], @@ -139,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)\. From c77fb275e5abaa69020e8ec8a0221e51c03daf70 Mon Sep 17 00:00:00 2001 From: Alexandra Eagan Date: Mon, 25 Jul 2022 20:36:12 +0000 Subject: [PATCH 153/156] Periodic update - 07/25/22-04:36pm EST --- doc_source/available-runtimes.md | 20 ++++---- doc_source/batch-build.md | 2 +- doc_source/bitbucket-webhook.md | 12 ++--- doc_source/build-caching.md | 11 ++-- doc_source/build-env-ref-available.md | 9 ++-- doc_source/build-env-ref-compute-types.md | 15 ++++-- doc_source/build-spec-ref.md | 7 ++- doc_source/change-project-console.md | 2 +- doc_source/codecov-integration.md | 4 +- doc_source/concepts.md | 2 +- doc_source/create-project-cli.md | 4 +- doc_source/create-project-console.md | 2 +- doc_source/data-protection.md | 6 +-- .../getting-started-cli-monitor-build.md | 3 ++ doc_source/github-webhook.md | 12 ++--- doc_source/history.md | 3 ++ doc_source/how-to-create-pipeline-add-test.md | 2 +- doc_source/how-to-create-pipeline-add.md | 2 +- doc_source/how-to-run.md | 6 +-- doc_source/limits.md | 4 +- doc_source/monitoring-metrics.md | 4 +- doc_source/monitoring-utilization-metrics.md | 4 +- doc_source/run-build-cli-auto-start.md | 2 +- doc_source/sample-build-notifications.md | 4 +- .../sample-disable-artifact-encryption.md | 2 +- doc_source/sample-ecr.md | 50 +++++++++++++++++++ doc_source/sample-efs.md | 12 +++-- doc_source/sample-github-enterprise.md | 8 +-- doc_source/sample-multi-in-out.md | 2 +- doc_source/sample-private-registry.md | 2 +- doc_source/setting-up.md | 5 +- doc_source/test-reporting.md | 3 ++ doc_source/use-codebuild-agent.md | 2 +- doc_source/use-proxy-server.md | 6 +-- .../use-vpc-endpoints-with-codebuild.md | 2 +- doc_source/view-build-details.md | 2 +- doc_source/vpc-support.md | 3 ++ doc_source/welcome.md | 4 +- 38 files changed, 164 insertions(+), 81 deletions(-) diff --git a/doc_source/available-runtimes.md b/doc_source/available-runtimes.md index 2d4ef67..7003c5d 100644 --- a/doc_source/available-runtimes.md +++ b/doc_source/available-runtimes.md @@ -21,13 +21,13 @@ 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` | -| --- | --- | -| dotnet | 3\.1\.4045\.0 | -| golang | 1\.14 | -| nodejs | 12\.18 | -| java | corretto11 | -| php | 7\.4\.7 | -| powershell | 7\.0\.2 | -| python | 3\.8\.3 | -| ruby | 2\.7 | \ No newline at end of file +| 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.md b/doc_source/batch-build.md index 2598333..5119cff 100644 --- a/doc_source/batch-build.md +++ b/doc_source/batch-build.md @@ -140,4 +140,4 @@ 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 ++ [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 index 581fc00..f754b8e 100644 --- a/doc_source/bitbucket-webhook.md +++ b/doc_source/bitbucket-webhook.md @@ -54,32 +54,32 @@ You can find the webhook payload in the webhook settings of your Bitbucket repos In this example, a webhook filter group triggers a build for pull requests only: -![\[\]](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/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$`\. -![\[\]](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/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\. -![\[\]](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/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\. -![\[\]](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/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\. -![\[\]](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/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\]`\. -![\[\]](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/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\) diff --git a/doc_source/build-caching.md b/doc_source/build-caching.md index 2c77d09..d5efdbc 100644 --- a/doc_source/build-caching.md +++ b/doc_source/build-caching.md @@ -15,7 +15,9 @@ Amazon S3 caching stores the cache in an Amazon S3 bucket that is available acro ## 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 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: +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** @@ -30,7 +32,10 @@ You should consider the security implication before you use a Docker layer cache + 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) @@ -64,7 +69,7 @@ For more information, see [Create a build project \(AWS CLI\)](create-project-cl You specify a cache in the **Artifacts** section of the console\. For **Cache type**, choose **Amazon S3** or **Local**\. If you choose **Local**, choose one or more of the three local cache options\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.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 build project \(console\)](create-project-console.md)\. diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md index 5833a00..e5547a1 100644 --- a/doc_source/build-env-ref-available.md +++ b/doc_source/build-env-ref-available.md @@ -5,16 +5,15 @@ 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: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: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: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: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:4\.0 | [ubuntu/standard/4\.0](https://github.com/aws/aws-codebuild-docker-images/tree/master/ubuntu/standard/4.0) | | 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 | - -¹ No longer maintained after May 2021\. +| Windows Server Core 2019 | aws/codebuild/windows\-base:2019\-2\.0 | N/A | The base image of the Windows Server Core 2019 platform is only available in the following regions: + US East \(N\. Virginia\) @@ -22,8 +21,6 @@ The base image of the Windows Server Core 2019 platform is only available in the + US West \(Oregon\) + Europe \(Ireland\) -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`\. - 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-console.md)\. + For the AWS CLI, run the `list-curated-environment-images` command: diff --git a/doc_source/build-env-ref-compute-types.md b/doc_source/build-env-ref-compute-types.md index d766537..8b634bf 100644 --- a/doc_source/build-env-ref-compute-types.md +++ b/doc_source/build-env-ref-compute-types.md @@ -7,14 +7,18 @@ AWS CodeBuild provides build environments with the following available memory, | --- | --- | --- | --- | --- | --- | | 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 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 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`\. + +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\. To choose a compute type: @@ -42,17 +46,22 @@ Some environment and compute types have Region availability limitations: + 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\) diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md index f33059d..2a287b2 100644 --- a/doc_source/build-spec-ref.md +++ b/doc_source/build-spec-ref.md @@ -183,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** @@ -193,7 +193,7 @@ 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** @@ -346,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`\)\. diff --git a/doc_source/change-project-console.md b/doc_source/change-project-console.md index dae5686..67d6018 100644 --- a/doc_source/change-project-console.md +++ b/doc_source/change-project-console.md @@ -332,7 +332,7 @@ For **Cache type**, choose one of the following: 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)\. ## Logs diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md index a11ffd4..aaa06ee 100644 --- a/doc_source/codecov-integration.md +++ b/doc_source/codecov-integration.md @@ -13,7 +13,7 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif 1. In Codecov, add the repository for which you want coverage\. 1. When token information is displayed, choose **Copy**\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-token.png) +![\[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-console.md)\. @@ -105,4 +105,4 @@ Codecov is a tool that measures the test coverage of your code\. Codecov identif ``` The reports look like the following: -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-report.png) \ No newline at end of file +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-report.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 diff --git a/doc_source/concepts.md b/doc_source/concepts.md index 358a927..5596971 100644 --- a/doc_source/concepts.md +++ b/doc_source/concepts.md @@ -12,7 +12,7 @@ The following diagram shows what happens when you run a build with CodeBuild: -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/arch.png) +![\[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/) diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md index c283109..3f0dec7 100644 --- a/doc_source/create-project-cli.md +++ b/doc_source/create-project-cli.md @@ -421,7 +421,9 @@ Optional\. An array of [Tag](https://docs.aws.amazon.com/codebuild/latest/APIRef ### 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 you rproject\. These properties include: +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: diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md index 71c37fc..65c48e2 100644 --- a/doc_source/create-project-console.md +++ b/doc_source/create-project-console.md @@ -296,7 +296,7 @@ For **Cache type**, choose one of the following: 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)\. ## Logs diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md index 845b394..836f7b5 100644 --- a/doc_source/data-protection.md +++ b/doc_source/data-protection.md @@ -13,9 +13,9 @@ For data protection purposes, we recommend that you protect AWS account credenti 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/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/github-webhook.md b/doc_source/github-webhook.md index 2529aec..0b47374 100644 --- a/doc_source/github-webhook.md +++ b/doc_source/github-webhook.md @@ -50,32 +50,32 @@ In **Primary source webhook events**, select the following\. This section is onl In this example, a webhook filter group triggers a build for pull requests only: -![\[\]](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/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$`\. -![\[\]](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/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\. -![\[\]](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/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\. -![\[\]](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/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\. -![\[\]](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/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\]`\. -![\[\]](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/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\) diff --git a/doc_source/history.md b/doc_source/history.md index c2dc914..a402310 100644 --- a/doc_source/history.md +++ b/doc_source/history.md @@ -6,6 +6,9 @@ The following table describes the important changes to the documentation since t | 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 | diff --git a/doc_source/how-to-create-pipeline-add-test.md b/doc_source/how-to-create-pipeline-add-test.md index f367c9f..9acb71e 100644 --- a/doc_source/how-to-create-pipeline-add-test.md +++ b/doc_source/how-to-create-pipeline-add-test.md @@ -45,7 +45,7 @@ This procedure shows you how to add a test action inside of a test stage between 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\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png) +![\[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/) diff --git a/doc_source/how-to-create-pipeline-add.md b/doc_source/how-to-create-pipeline-add.md index 03f1f0e..1624ed7 100644 --- a/doc_source/how-to-create-pipeline-add.md +++ b/doc_source/how-to-create-pipeline-add.md @@ -47,7 +47,7 @@ This procedure shows you how to add a build action in a build stage between the 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\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-stage.png) +![\[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/) diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md index 0887716..1598318 100644 --- a/doc_source/how-to-run.md +++ b/doc_source/how-to-run.md @@ -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/limits.md b/doc_source/limits.md index 542dcd5..5ddb5c5 100644 --- a/doc_source/limits.md +++ b/doc_source/limits.md @@ -44,7 +44,9 @@ Quotas for the maximum number of concurrent running builds vary, depending on th | 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 diff --git a/doc_source/monitoring-metrics.md b/doc_source/monitoring-metrics.md index 6e79693..54c47c0 100644 --- a/doc_source/monitoring-metrics.md +++ b/doc_source/monitoring-metrics.md @@ -46,7 +46,7 @@ You can customize the metrics and the graphs used to display them with the Cloud 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-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 **Account Metrics**\. @@ -61,7 +61,7 @@ You can customize the metrics and the graphs used to display them with the Cloud 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-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 **By Project**\. diff --git a/doc_source/monitoring-utilization-metrics.md b/doc_source/monitoring-utilization-metrics.md index 8d3679d..461eb5c 100644 --- a/doc_source/monitoring-utilization-metrics.md +++ b/doc_source/monitoring-utilization-metrics.md @@ -77,7 +77,7 @@ The Amazon CloudWatch console can be used to access CodeBuild resource utilizati 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) +![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) 1. Choose **By Project**\. @@ -96,7 +96,7 @@ The Amazon CloudWatch console can be used to access CodeBuild resource utilizati 1. In the navigation pane, choose **Metrics**\. 1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png) +![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) 1. Choose **BuildId, BuildNumber, ProjectName**\. diff --git a/doc_source/run-build-cli-auto-start.md b/doc_source/run-build-cli-auto-start.md index 300d4e1..ae94018 100644 --- a/doc_source/run-build-cli-auto-start.md +++ b/doc_source/run-build-cli-auto-start.md @@ -24,7 +24,7 @@ For GitHub, information similar to the following appears in the output: For GitHub Enterprise Server, information similar to the following appears in the output: -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) 1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise Server\. diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md index 6f12327..2511b02 100644 --- a/doc_source/sample-build-notifications.md +++ b/doc_source/sample-build-notifications.md @@ -52,7 +52,7 @@ For more information, see [Editing customer managed policies](https://docs.aws.a 1. On the **Topic details: CodeBuildDemoTopic** page, copy the **Topic ARN** value\. You need this value for the next step\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/topic-arn.png) +![\[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/) @@ -71,7 +71,7 @@ For more information, see [Editing customer managed policies](https://docs.aws.a 1. For **Endpoint**, enter the recipient's full email address\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-subscription.png) +![\[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/) diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md index 9c56ac0..05752c0 100644 --- a/doc_source/sample-disable-artifact-encryption.md +++ b/doc_source/sample-disable-artifact-encryption.md @@ -13,7 +13,7 @@ 1. In **Source**, for **Source provider**, choose **GitHub**\. Follow the instructions to connect \(or reconnect\) with GitHub, and then choose **Authorize**\. For **Webhook**, select **Rebuild every time a code change is pushed to this repository**\. You can select this check box only if you chose **Use a repository in my account**\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/webhook.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/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. In **Environment**: diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md index 6b84073..a18922a 100644 --- a/doc_source/sample-ecr.md +++ b/doc_source/sample-ecr.md @@ -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", diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md index cff6303..16b1be4 100644 --- a/doc_source/sample-efs.md +++ b/doc_source/sample-efs.md @@ -61,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\. @@ -119,7 +121,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo 1. For **Build specification**, choose **Insert build commands**, and then choose **Switch to editor**\. -1. Enter the following buildspec commands into the editor\. Replace `` with the identifier you entered in step 17\. Use capital letters \(for example, `CODEBUILD_MY_EFS`\)\. +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 @@ -148,7 +150,7 @@ By default, Docker containers do not allow access to any devices\. Privileged mo ## Troubleshooting -The following are errors you might encounter when setting up EFS with CodeBuild\. +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) @@ -157,7 +159,7 @@ The following are errors you might encounter when setting up EFS with CodeBuild\ ### CLIENT\_ERROR: mounting '127\.0\.0\.1:/' failed\. permission denied -IAM authorization is not supported for mounting EFS with CodeBuild\. If you are using a custom EFS file system policy, you will need to grant read and write access to all IAM principals\. For example: +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": { @@ -168,8 +170,8 @@ IAM authorization is not supported for mounting EFS with CodeBuild\. If you are ### 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 EFS mount target\. You can resolve this by adding a VPC subnet in the same availability zone as the EFS mount target\. -+ The security group does not have permissions to communicate with 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\. ++ 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 diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md index 3e2a0e7..49646e8 100644 --- a/doc_source/sample-github-enterprise.md +++ b/doc_source/sample-github-enterprise.md @@ -7,7 +7,7 @@ AWS CodeBuild supports GitHub Enterprise Server as a source repository\. This sa 1. Generate a personal access token for your CodeBuild project\. We recommend that you create a GitHub Enterprise user and generate a personal access token for this user\. Copy it to your clipboard so that it can be used 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\. When you create the personal access token, include the **repo** scope in the definition\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png) 1. Download your certificate from GitHub Enterprise Server\. CodeBuild uses the certificate to make a trusted SSL connection to the repository\. @@ -60,7 +60,7 @@ You only need to enter and save the personal access token once\. All future AWS + Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise Server project repository\. **Note** We recommend that you use **Enable insecure SSL** for testing only\. It should not be used in a production environment\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) 1. In **Environment**: @@ -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)\. @@ -122,6 +122,6 @@ If you need to generate a payload URL and secret key again, you must first delet 1. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. 1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ghe-webhook.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ghe-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. Return to your CodeBuild project\. Close the **Create webhook** dialog box and choose **Start build**\. \ 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 761bb81..e43b9f5 100644 --- a/doc_source/sample-multi-in-out.md +++ b/doc_source/sample-multi-in-out.md @@ -139,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)\. +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-private-registry.md b/doc_source/sample-private-registry.md index b7b3f95..b8c230b 100644 --- a/doc_source/sample-private-registry.md +++ b/doc_source/sample-private-registry.md @@ -42,7 +42,7 @@ 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\. -![\[\]](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/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/) 1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. **Note** diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md index 014bdd7..7987a75 100644 --- a/doc_source/setting-up.md +++ b/doc_source/setting-up.md @@ -241,8 +241,9 @@ You need an AWS CodeBuild service role so that CodeBuild can interact with depen 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\)** diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md index d8ff1b4..07aa636 100644 --- a/doc_source/test-reporting.md +++ b/doc_source/test-reporting.md @@ -10,6 +10,9 @@ The following test report file formats are supported: + 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\)\. To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md index 4ae30b6..076cecd 100644 --- a/doc_source/use-codebuild-agent.md +++ b/doc_source/use-codebuild-agent.md @@ -70,7 +70,7 @@ You only need to set up the build image the first time you run the agent, or whe sha256:5480b70cf48435e276c21789c61280cfada24e17701ede6386e5d82088bc41ca ``` - You can use the SHA to identify the version of the agent\. To see the agent's SHA signature, run the following command: + 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`: ``` $ docker inspect public.ecr.aws/codebuild/local-builds:latest diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md index 3ec782d..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** @@ -26,7 +26,7 @@ There are two primary use cases for running CodeBuild in a proxy server: The following diagram shows how the components interact\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-proxy-transparent.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-proxy-transparent.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) ### Set up a VPC, subnets, and a network gateway @@ -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: diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md index ca057fc..7fefd42 100644 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ b/doc_source/use-vpc-endpoints-with-codebuild.md @@ -15,7 +15,7 @@ You can improve the security of your builds by configuring AWS CodeBuild to use Follow the instructions in [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png) +![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) *region* represents the region identifier for an AWS Region supported by CodeBuild, such as `us-east-2` for the US East \(Ohio\) Region\. For a list of supported AWS Regions, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the * AWS General Reference*\. The endpoint is prepopulated with the Region you specified when you signed in to AWS\. If you change your Region, the VPC endpoint is updated accordingly\. diff --git a/doc_source/view-build-details.md b/doc_source/view-build-details.md index c1b84d4..5305ff6 100644 --- a/doc_source/view-build-details.md +++ b/doc_source/view-build-details.md @@ -51,7 +51,7 @@ Builds in AWS CodeBuild proceed in phases: -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/build-phases.png) +![\[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/) diff --git a/doc_source/vpc-support.md b/doc_source/vpc-support.md index f584360..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) diff --git a/doc_source/welcome.md b/doc_source/welcome.md index d1c53b6..d9b2e98 100644 --- a/doc_source/welcome.md +++ b/doc_source/welcome.md @@ -17,7 +17,7 @@ You can use the AWS CodeBuild or AWS CodePipeline console to run CodeBuild\. You -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/overview.png) +![\[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/) @@ -27,7 +27,7 @@ As the following diagram shows, you can add CodeBuild as a build or test action -![\[\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/pipeline.png) +![\[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/) From 78092fbb12ef73097e4fba030b946207517fa0a1 Mon Sep 17 00:00:00 2001 From: Josh Bean <1139540+joshbean@users.noreply.github.com> Date: Fri, 19 May 2023 14:07:43 -0700 Subject: [PATCH 154/156] Update README to add announcement about archiving --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 1989489..ffae88d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ +# 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. From 66cc3be8e695e9daf47158339ab05df638a90331 Mon Sep 17 00:00:00 2001 From: Josh Bean <1139540+joshbean@users.noreply.github.com> Date: Thu, 15 Jun 2023 15:30:07 -0700 Subject: [PATCH 155/156] Update README prior to archiving --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index ffae88d..c92957f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ +# 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/). From 4a5cd950b6a03e503581d9e69a1f10eec18efd4e Mon Sep 17 00:00:00 2001 From: Josh Bean <1139540+joshbean@users.noreply.github.com> Date: Thu, 15 Jun 2023 15:40:27 -0700 Subject: [PATCH 156/156] Update README.md and delete content directory --- README.md | 21 +- doc_source/access-tokens.md | 231 ---- doc_source/advanced-topics.md | 14 - ...ntrol-iam-access-control-identity-based.md | 110 -- ...ntrol-iam-identity-based-access-control.md | 1021 ----------------- ...nd-access-control-permissions-reference.md | 198 ---- .../auth-and-access-control-using-tags.md | 128 --- doc_source/auth-and-access-control.md | 30 - doc_source/available-runtimes.md | 33 - doc_source/batch-build-buildspec.md | 200 ---- doc_source/batch-build.md | 143 --- doc_source/bitbucket-webhook.md | 247 ---- doc_source/build-caching.md | 117 -- doc_source/build-env-ref-available.md | 35 - doc_source/build-env-ref-background-tasks.md | 24 - doc_source/build-env-ref-cmd.md | 16 - doc_source/build-env-ref-compute-types.md | 89 -- doc_source/build-env-ref-env-vars.md | 110 -- doc_source/build-env-ref.md | 19 - doc_source/build-spec-ref.md | 642 ----------- doc_source/builds-projects-and-builds.md | 7 - doc_source/builds-working.md | 28 - doc_source/change-project-cli.md | 41 - doc_source/change-project-console.md | 364 ------ doc_source/change-project-sdks.md | 3 - doc_source/change-project.md | 10 - doc_source/cloudformation-vpc-template.md | 245 ---- doc_source/cloudtrail.md | 103 -- doc_source/cmd-ref.md | 35 - doc_source/code-coverage-report.md | 51 - doc_source/codebuild-compliance-validation.md | 14 - .../codebuild-disaster-recovery-resiliency.md | 5 - doc_source/codecov-integration.md | 108 -- doc_source/concepts.md | 39 - doc_source/console-resources.md | 15 - doc_source/create-project-cli.md | 513 --------- doc_source/create-project-cloud-formation.md | 3 - doc_source/create-project-console.md | 324 ------ doc_source/create-project-sdks.md | 3 - doc_source/create-project.md | 14 - doc_source/data-protection.md | 25 - doc_source/delete-builds.md | 44 - doc_source/delete-project.md | 42 - doc_source/endpoint-specify.md | 82 -- .../getting-started-build-log-console.md | 23 - .../getting-started-clean-up-console.md | 32 - doc_source/getting-started-cli-build-log.md | 76 -- doc_source/getting-started-cli-clean-up.md | 32 - ...etting-started-cli-create-build-project.md | 112 -- .../getting-started-cli-create-build-spec.md | 63 - .../getting-started-cli-create-source-code.md | 122 -- .../getting-started-cli-input-bucket.md | 20 - .../getting-started-cli-monitor-build.md | 87 -- doc_source/getting-started-cli-next-steps.md | 7 - doc_source/getting-started-cli-output.md | 31 - doc_source/getting-started-cli-run-build.md | 62 - .../getting-started-cli-upload-source-code.md | 36 - doc_source/getting-started-cli.md | 21 - ...ng-started-create-build-project-console.md | 52 - ...tting-started-create-build-spec-console.md | 63 - ...ting-started-create-source-code-console.md | 122 -- .../getting-started-input-bucket-console.md | 20 - .../getting-started-monitor-build-console.md | 32 - .../getting-started-next-steps-console.md | 7 - doc_source/getting-started-output-console.md | 31 - doc_source/getting-started-overview.md | 8 - .../getting-started-run-build-console.md | 17 - ...ting-started-upload-source-code-console.md | 36 - doc_source/getting-started.md | 21 - doc_source/github-webhook.md | 246 ---- doc_source/glossary.md | 3 - doc_source/history.md | 103 -- doc_source/how-to-create-pipeline-add-test.md | 84 -- doc_source/how-to-create-pipeline-add.md | 100 -- doc_source/how-to-create-pipeline-cli.md | 150 --- doc_source/how-to-create-pipeline-console.md | 106 -- doc_source/how-to-create-pipeline.md | 55 - doc_source/how-to-integrate-config.md | 46 - doc_source/how-to-run.md | 21 - doc_source/how-to-tag-project-add.md | 38 - doc_source/how-to-tag-project-delete.md | 33 - doc_source/how-to-tag-project-list.md | 38 - doc_source/how-to-tag-project-update.md | 28 - doc_source/how-to-tag-project.md | 17 - doc_source/how-to-tag-report-group-add.md | 38 - doc_source/how-to-tag-report-group-delete.md | 35 - doc_source/how-to-tag-report-group-list.md | 72 -- doc_source/how-to-tag-report-group-update.md | 28 - doc_source/how-to-tag-report-group.md | 17 - doc_source/index.md | 197 ---- doc_source/infrastructure-security.md | 7 - doc_source/jenkins-plugin.md | 81 -- doc_source/limits.md | 62 - doc_source/logging-monitoring.md | 7 - doc_source/monitoring-alarms.md | 21 - doc_source/monitoring-builds.md | 162 --- doc_source/monitoring-metrics.md | 72 -- doc_source/monitoring-utilization-metrics.md | 107 -- doc_source/notice.md | 389 ------- doc_source/notification-rule-create.md | 81 -- doc_source/planning.md | 23 - doc_source/project-sharing.md | 186 --- doc_source/public-builds.md | 25 - doc_source/report-create.md | 37 - doc_source/report-group-create.md | 9 - doc_source/report-group-export-settings.md | 18 - doc_source/report-group-test-case-commands.md | 12 - doc_source/report-group-test-cases.md | 19 - doc_source/report-groups-sharing.md | 200 ---- doc_source/retry-build.md | 39 - doc_source/run-batch-build-cli.md | 57 - doc_source/run-build-cli-auto-start.md | 33 - doc_source/run-build-cli-auto-stop.md | 15 - doc_source/run-build-cli.md | 127 -- doc_source/run-build-console.md | 30 - doc_source/run-build-sdks.md | 5 - doc_source/run-build.md | 11 - doc_source/runtime-versions.md | 12 - doc_source/sample-bitbucket-pull-request.md | 116 -- doc_source/sample-build-badges.md | 86 -- doc_source/sample-build-notifications.md | 538 --------- .../sample-buildspec-artifact-naming.md | 82 -- doc_source/sample-codedeploy.md | 173 --- .../sample-disable-artifact-encryption.md | 49 - doc_source/sample-docker-custom-image.md | 105 -- doc_source/sample-docker.md | 310 ----- doc_source/sample-ecr.md | 250 ---- doc_source/sample-efs.md | 178 --- doc_source/sample-elastic-beanstalk.md | 341 ------ doc_source/sample-github-enterprise.md | 127 -- doc_source/sample-github-pull-request.md | 92 -- doc_source/sample-multi-in-out.md | 142 --- doc_source/sample-pipeline-batch.md | 277 ----- .../sample-pipeline-multi-input-output.md | 132 --- doc_source/sample-private-registry.md | 59 - doc_source/sample-runtime-versions.md | 378 ------ doc_source/sample-source-version.md | 98 -- doc_source/sample-test-report-cli.md | 258 ----- doc_source/sample-windows.md | 831 -------------- doc_source/samples.md | 7 - doc_source/sdk-ref.md | 18 - doc_source/security-encryption.md | 10 - doc_source/security-key-management.md | 7 - doc_source/security-traffic-privacy.md | 3 - doc_source/security.md | 15 - doc_source/serverless-applications.md | 12 - doc_source/session-manager.md | 156 --- doc_source/setting-up.md | 558 --------- doc_source/stop-batch-build.md | 41 - doc_source/stop-build.md | 41 - doc_source/test-framework-reporting.md | 9 - doc_source/test-permissions.md | 109 -- .../test-report-group-create-buildspec.md | 24 - doc_source/test-report-group-create-cfn.md | 40 - doc_source/test-report-group-create-cli.md | 55 - .../test-report-group-create-console.md | 36 - doc_source/test-report-group-naming.md | 14 - doc_source/test-report-group.md | 16 - doc_source/test-report-jasmine.md | 91 -- doc_source/test-report-jest.md | 59 - doc_source/test-report-pytest.md | 36 - doc_source/test-report-rspec.md | 31 - doc_source/test-report.md | 24 - doc_source/test-reporting.md | 34 - doc_source/test-view-reports.md | 52 - doc_source/trigger-create.md | 46 - doc_source/triggers-edit.md | 34 - doc_source/troubleshooting.md | 537 --------- doc_source/update-report-group-cli.md | 55 - doc_source/update-report-group-console.md | 24 - doc_source/use-case-based-samples.md | 63 - doc_source/use-codebuild-agent.md | 148 --- doc_source/use-proxy-server.md | 369 ------ .../use-vpc-endpoints-with-codebuild.md | 48 - doc_source/view-build-details.md | 59 - doc_source/view-build-list.md | 125 -- doc_source/view-builds-for-project.md | 130 --- doc_source/view-project-details.md | 112 -- doc_source/view-project-list.md | 77 -- doc_source/vpc-support.md | 105 -- doc_source/webhooks.md | 24 - doc_source/welcome.md | 50 - doc_source/working-with-build-projects.md | 21 - 183 files changed, 2 insertions(+), 18126 deletions(-) delete mode 100644 doc_source/access-tokens.md delete mode 100644 doc_source/advanced-topics.md delete mode 100644 doc_source/auth-and-access-control-iam-access-control-identity-based.md delete mode 100644 doc_source/auth-and-access-control-iam-identity-based-access-control.md delete mode 100644 doc_source/auth-and-access-control-permissions-reference.md delete mode 100644 doc_source/auth-and-access-control-using-tags.md delete mode 100644 doc_source/auth-and-access-control.md delete mode 100644 doc_source/available-runtimes.md delete mode 100644 doc_source/batch-build-buildspec.md delete mode 100644 doc_source/batch-build.md delete mode 100644 doc_source/bitbucket-webhook.md delete mode 100644 doc_source/build-caching.md delete mode 100644 doc_source/build-env-ref-available.md delete mode 100644 doc_source/build-env-ref-background-tasks.md delete mode 100644 doc_source/build-env-ref-cmd.md delete mode 100644 doc_source/build-env-ref-compute-types.md delete mode 100644 doc_source/build-env-ref-env-vars.md delete mode 100644 doc_source/build-env-ref.md delete mode 100644 doc_source/build-spec-ref.md delete mode 100644 doc_source/builds-projects-and-builds.md delete mode 100644 doc_source/builds-working.md delete mode 100644 doc_source/change-project-cli.md delete mode 100644 doc_source/change-project-console.md delete mode 100644 doc_source/change-project-sdks.md delete mode 100644 doc_source/change-project.md delete mode 100644 doc_source/cloudformation-vpc-template.md delete mode 100644 doc_source/cloudtrail.md delete mode 100644 doc_source/cmd-ref.md delete mode 100644 doc_source/code-coverage-report.md delete mode 100644 doc_source/codebuild-compliance-validation.md delete mode 100644 doc_source/codebuild-disaster-recovery-resiliency.md delete mode 100644 doc_source/codecov-integration.md delete mode 100644 doc_source/concepts.md delete mode 100644 doc_source/console-resources.md delete mode 100644 doc_source/create-project-cli.md delete mode 100644 doc_source/create-project-cloud-formation.md delete mode 100644 doc_source/create-project-console.md delete mode 100644 doc_source/create-project-sdks.md delete mode 100644 doc_source/create-project.md delete mode 100644 doc_source/data-protection.md delete mode 100644 doc_source/delete-builds.md delete mode 100644 doc_source/delete-project.md delete mode 100644 doc_source/endpoint-specify.md delete mode 100644 doc_source/getting-started-build-log-console.md delete mode 100644 doc_source/getting-started-clean-up-console.md delete mode 100644 doc_source/getting-started-cli-build-log.md delete mode 100644 doc_source/getting-started-cli-clean-up.md delete mode 100644 doc_source/getting-started-cli-create-build-project.md delete mode 100644 doc_source/getting-started-cli-create-build-spec.md delete mode 100644 doc_source/getting-started-cli-create-source-code.md delete mode 100644 doc_source/getting-started-cli-input-bucket.md delete mode 100644 doc_source/getting-started-cli-monitor-build.md delete mode 100644 doc_source/getting-started-cli-next-steps.md delete mode 100644 doc_source/getting-started-cli-output.md delete mode 100644 doc_source/getting-started-cli-run-build.md delete mode 100644 doc_source/getting-started-cli-upload-source-code.md delete mode 100644 doc_source/getting-started-cli.md delete mode 100644 doc_source/getting-started-create-build-project-console.md delete mode 100644 doc_source/getting-started-create-build-spec-console.md delete mode 100644 doc_source/getting-started-create-source-code-console.md delete mode 100644 doc_source/getting-started-input-bucket-console.md delete mode 100644 doc_source/getting-started-monitor-build-console.md delete mode 100644 doc_source/getting-started-next-steps-console.md delete mode 100644 doc_source/getting-started-output-console.md delete mode 100644 doc_source/getting-started-overview.md delete mode 100644 doc_source/getting-started-run-build-console.md delete mode 100644 doc_source/getting-started-upload-source-code-console.md delete mode 100644 doc_source/getting-started.md delete mode 100644 doc_source/github-webhook.md delete mode 100644 doc_source/glossary.md delete mode 100644 doc_source/history.md delete mode 100644 doc_source/how-to-create-pipeline-add-test.md delete mode 100644 doc_source/how-to-create-pipeline-add.md delete mode 100644 doc_source/how-to-create-pipeline-cli.md delete mode 100644 doc_source/how-to-create-pipeline-console.md delete mode 100644 doc_source/how-to-create-pipeline.md delete mode 100644 doc_source/how-to-integrate-config.md delete mode 100644 doc_source/how-to-run.md delete mode 100644 doc_source/how-to-tag-project-add.md delete mode 100644 doc_source/how-to-tag-project-delete.md delete mode 100644 doc_source/how-to-tag-project-list.md delete mode 100644 doc_source/how-to-tag-project-update.md delete mode 100644 doc_source/how-to-tag-project.md delete mode 100644 doc_source/how-to-tag-report-group-add.md delete mode 100644 doc_source/how-to-tag-report-group-delete.md delete mode 100644 doc_source/how-to-tag-report-group-list.md delete mode 100644 doc_source/how-to-tag-report-group-update.md delete mode 100644 doc_source/how-to-tag-report-group.md delete mode 100644 doc_source/index.md delete mode 100644 doc_source/infrastructure-security.md delete mode 100644 doc_source/jenkins-plugin.md delete mode 100644 doc_source/limits.md delete mode 100644 doc_source/logging-monitoring.md delete mode 100644 doc_source/monitoring-alarms.md delete mode 100644 doc_source/monitoring-builds.md delete mode 100644 doc_source/monitoring-metrics.md delete mode 100644 doc_source/monitoring-utilization-metrics.md delete mode 100644 doc_source/notice.md delete mode 100644 doc_source/notification-rule-create.md delete mode 100644 doc_source/planning.md delete mode 100644 doc_source/project-sharing.md delete mode 100644 doc_source/public-builds.md delete mode 100644 doc_source/report-create.md delete mode 100644 doc_source/report-group-create.md delete mode 100644 doc_source/report-group-export-settings.md delete mode 100644 doc_source/report-group-test-case-commands.md delete mode 100644 doc_source/report-group-test-cases.md delete mode 100644 doc_source/report-groups-sharing.md delete mode 100644 doc_source/retry-build.md delete mode 100644 doc_source/run-batch-build-cli.md delete mode 100644 doc_source/run-build-cli-auto-start.md delete mode 100644 doc_source/run-build-cli-auto-stop.md delete mode 100644 doc_source/run-build-cli.md delete mode 100644 doc_source/run-build-console.md delete mode 100644 doc_source/run-build-sdks.md delete mode 100644 doc_source/run-build.md delete mode 100644 doc_source/runtime-versions.md delete mode 100644 doc_source/sample-bitbucket-pull-request.md delete mode 100644 doc_source/sample-build-badges.md delete mode 100644 doc_source/sample-build-notifications.md delete mode 100644 doc_source/sample-buildspec-artifact-naming.md delete mode 100644 doc_source/sample-codedeploy.md delete mode 100644 doc_source/sample-disable-artifact-encryption.md delete mode 100644 doc_source/sample-docker-custom-image.md delete mode 100644 doc_source/sample-docker.md delete mode 100644 doc_source/sample-ecr.md delete mode 100644 doc_source/sample-efs.md delete mode 100644 doc_source/sample-elastic-beanstalk.md delete mode 100644 doc_source/sample-github-enterprise.md delete mode 100644 doc_source/sample-github-pull-request.md delete mode 100644 doc_source/sample-multi-in-out.md delete mode 100644 doc_source/sample-pipeline-batch.md delete mode 100644 doc_source/sample-pipeline-multi-input-output.md delete mode 100644 doc_source/sample-private-registry.md delete mode 100644 doc_source/sample-runtime-versions.md delete mode 100644 doc_source/sample-source-version.md delete mode 100644 doc_source/sample-test-report-cli.md delete mode 100644 doc_source/sample-windows.md delete mode 100644 doc_source/samples.md delete mode 100644 doc_source/sdk-ref.md delete mode 100644 doc_source/security-encryption.md delete mode 100644 doc_source/security-key-management.md delete mode 100644 doc_source/security-traffic-privacy.md delete mode 100644 doc_source/security.md delete mode 100644 doc_source/serverless-applications.md delete mode 100644 doc_source/session-manager.md delete mode 100644 doc_source/setting-up.md delete mode 100644 doc_source/stop-batch-build.md delete mode 100644 doc_source/stop-build.md delete mode 100644 doc_source/test-framework-reporting.md delete mode 100644 doc_source/test-permissions.md delete mode 100644 doc_source/test-report-group-create-buildspec.md delete mode 100644 doc_source/test-report-group-create-cfn.md delete mode 100644 doc_source/test-report-group-create-cli.md delete mode 100644 doc_source/test-report-group-create-console.md delete mode 100644 doc_source/test-report-group-naming.md delete mode 100644 doc_source/test-report-group.md delete mode 100644 doc_source/test-report-jasmine.md delete mode 100644 doc_source/test-report-jest.md delete mode 100644 doc_source/test-report-pytest.md delete mode 100644 doc_source/test-report-rspec.md delete mode 100644 doc_source/test-report.md delete mode 100644 doc_source/test-reporting.md delete mode 100644 doc_source/test-view-reports.md delete mode 100644 doc_source/trigger-create.md delete mode 100644 doc_source/triggers-edit.md delete mode 100644 doc_source/troubleshooting.md delete mode 100644 doc_source/update-report-group-cli.md delete mode 100644 doc_source/update-report-group-console.md delete mode 100644 doc_source/use-case-based-samples.md delete mode 100644 doc_source/use-codebuild-agent.md delete mode 100644 doc_source/use-proxy-server.md delete mode 100644 doc_source/use-vpc-endpoints-with-codebuild.md delete mode 100644 doc_source/view-build-details.md delete mode 100644 doc_source/view-build-list.md delete mode 100644 doc_source/view-builds-for-project.md delete mode 100644 doc_source/view-project-details.md delete mode 100644 doc_source/view-project-list.md delete mode 100644 doc_source/vpc-support.md delete mode 100644 doc_source/webhooks.md delete mode 100644 doc_source/welcome.md delete mode 100644 doc_source/working-with-build-projects.md diff --git a/README.md b/README.md index c92957f..a02f592 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,5 @@ # 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. +This repository is archived, read-only, and no longer updated. For more information, read [the announcement on the AWS News Blog](https://aws.amazon.com/blogs/aws/retiring-the-aws-documentation-on-github/). -# 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. - -## License Summary - -The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file. - -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 have checked out the previous default branch, please update your local repo to use the `main` branch. \ No newline at end of file +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. diff --git a/doc_source/access-tokens.md b/doc_source/access-tokens.md deleted file mode 100644 index eaaddd6..0000000 --- a/doc_source/access-tokens.md +++ /dev/null @@ -1,231 +0,0 @@ -# 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 deleted file mode 100644 index 3ea57fa..0000000 --- a/doc_source/advanced-topics.md +++ /dev/null @@ -1,14 +0,0 @@ -# Advanced topics - -This section includes several advanced topics that are useful to more experienced AWS CodeBuild users\. - -**Topics** -+ [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) -+ [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 deleted file mode 100644 index 9664f48..0000000 --- a/doc_source/auth-and-access-control-iam-access-control-identity-based.md +++ /dev/null @@ -1,110 +0,0 @@ -# Overview of managing access permissions to your AWS CodeBuild resources - -Every AWS resource is owned by an AWS account, and permissions to create or access a resource are governed by permissions policies\. An account administrator can attach permissions policies to IAM identities \(that is, users, groups, and roles\)\. - -**Note** -An account administrator \(or administrator user\) is a user with administrator privileges\. For more information, see [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*\. - -When you grant permissions, you decide who is getting the permissions, the resources they can access, and the actions that can be performed on those resources\. - -**Topics** -+ [AWS CodeBuild resources and operations](#arn-formats) -+ [Understanding resource ownership](#understanding-resource-ownership) -+ [Managing access to resources](#managing-access-resources) -+ [Specifying policy elements: Actions, effects, and principals](#actions-effects-principals) - -## AWS CodeBuild resources and operations - -In AWS CodeBuild, the primary resource is a build project\. In a policy, you use an Amazon Resource Name \(ARN\) to identify the resource the policy applies to\. Builds are also resources and have ARNs associated with them\. For more information, see [Amazon Resource Names \(ARN\) and AWS Service Namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the *Amazon Web Services General Reference*\. - - -| Resource type | ARN format | -| --- | --- | -| Build project | `arn:aws:codebuild:region-ID:account-ID:project/project-name` | -| Build | `arn:aws:codebuild:region-ID:account-ID:build/build-ID` | -| Report group | arn:aws:codebuild:region\-ID:account\-ID:report\-group/report\-group\-name | -| Report | arn:aws:codebuild:region\-ID:account\-ID:report/report\-ID | -| All CodeBuild resources | `arn:aws:codebuild:*` | -| All CodeBuild resources owned by the specified account in the specified AWS Region | `arn:aws:codebuild:region-ID:account-ID:*` | - -**Note** -Most AWS services treat a colon \(:\) or a forward slash \(/\) as the same character in ARNs\. However, CodeBuild uses an exact match in resource patterns and rules\. Be sure to use the correct characters when you create event patterns so that they match the ARN syntax in the resource\. - -For example, you can indicate a specific build project \(*myBuildProject*\) in your statement using its ARN as follows: - -``` -"Resource": "arn:aws:codebuild:us-east-2:123456789012:project/myBuildProject" -``` - -To specify all resources, or if an API action does not support ARNs, use the wildcard character \(\*\) in the `Resource` element as follows: - -``` -"Resource": "*" -``` - -Some CodeBuild API actions accept multiple resources \(for example, `BatchGetProjects`\)\. To specify multiple resources in a single statement, separate their ARNs with commas, as follows: - -``` -"Resource": [ - "arn:aws:codebuild:us-east-2:123456789012:project/myBuildProject", - "arn:aws:codebuild:us-east-2:123456789012:project/myOtherBuildProject" -] -``` - -CodeBuild provides a set of operations to work with the CodeBuild resources\. For a list, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. - -## Understanding resource ownership - -The AWS account owns the resources that are created in the account, regardless of who created the resources\. Specifically, the resource owner is the AWS account of the [principal entity](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html) \(that is, the root account, an IAM user, or an IAM role\) that authenticates the resource creation request\. The following examples illustrate how this works: -+ If you use the root account credentials of your AWS account to create a rule, your AWS account is the owner of the CodeBuild resource\. -+ If you create an IAM user in your AWS account and grant permissions to create CodeBuild resources to that user, the user can create CodeBuild resources\. However, your AWS account, to which the user belongs, owns the CodeBuild resources\. -+ If you create an IAM role in your AWS account with permissions to create CodeBuild resources, anyone who can assume the role can create CodeBuild resources\. Your AWS account, to which the role belongs, owns the CodeBuild resources\. - -## Managing access to resources - -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 policies, and resource\-based policies for certain read only APIs for the purpose of cross\-account resource sharing\. - -### Identity\-based policies - -You can attach policies to IAM identities\. -+ **Attach a permissions policy to a user or a group in your account** – To grant a user permissions to view build projects and other AWS CodeBuild resources in the AWS CodeBuild console, you can attach a permissions policy to a user or group that the user belongs to\. -+ **Attach a permissions policy to a role \(grant cross\-account permissions\)** – You can attach an identity\-based permissions policy to an IAM role to grant cross\-account permissions\. For example, the administrator in Account A can create a role to grant cross\-account permissions to another AWS account \(for example, Account B\) or an AWS service as follows: - - 1. Account A administrator creates an IAM role and attaches a permissions policy to the role that grants permissions on resources in Account A\. - - 1. Account A administrator attaches a trust policy to the role identifying Account B as the principal who can assume the role\. - - 1. Account B administrator can then delegate permissions to assume the role to any users in Account B\. Doing this allows users in Account B to create or access resources in Account A\. The principal in the trust policy must also be an AWS service principal if you want to grant an AWS service permissions to assume the role\. - - For more information about using IAM to delegate permissions, see [Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html) in the *IAM User Guide*\. - -In CodeBuild, identity\-based policies are used to manage permissions to the resources related to the deployment process\. For example, you can control access to build projects\. - -You can create IAM policies to restrict the calls and resources that users in your account have access to, and then attach those policies to IAM users\. For more information about how to create IAM roles and to explore example IAM policy statements for CodeBuild, see [Overview of managing access permissions to your AWS CodeBuild resources](#auth-and-access-control-iam-access-control-identity-based)\. - -### 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: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)\. - -## Specifying policy elements: Actions, effects, and principals - -For each AWS CodeBuild resource, the service defines a set of API operations\. To grant permissions for these API operations, CodeBuild defines a set of actions that you can specify in a policy\. Some API operations can require permissions for more than one action in order to perform the API operation\. For more information, see [AWS CodeBuild resources and operations](#arn-formats) and [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. - -The following are the basic policy elements: -+ **Resource** – You use an Amazon Resource Name \(ARN\) to identify the resource that the policy applies to\. -+ **Action** – You use action keywords to identify resource operations you want to allow or deny\. For example, the `codebuild:CreateProject` permission gives the user permissions to perform the `CreateProject` operation\. -+ **Effect** – You specify the effect, either allow or deny, when the user requests the action\. If you don't explicitly grant access to \(allow\) a resource, access is implicitly denied\. You can also explicitly deny access to a resource\. You might do this to make sure a user cannot access a resource, even if a different policy grants access\. -+ **Principal** – In identity\-based policies \(IAM policies\), the user the policy is attached to is the implicit principal\. For resource\-based policies, you specify the user, account, service, or other entity that you want to receive permissions\. - -To learn more 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*\. - -For a table showing all of the CodeBuild API actions and the resources they apply to, see the [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. \ No newline at end of file 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 deleted file mode 100644 index 4f455e0..0000000 --- a/doc_source/auth-and-access-control-iam-identity-based-access-control.md +++ /dev/null @@ -1,1021 +0,0 @@ -# Using identity\-based policies for AWS CodeBuild - -This topic provides examples of identity\-based policies that demonstrate how an account administrator can attach permissions policies to IAM identities \(that is, users, groups, and roles\) and thereby grant permissions to perform operations on AWS CodeBuild resources\. - -**Important** -We recommend that you first review the introductory topics that explain the basic concepts and options available to manage access to your CodeBuild resources\. For more information, see [Overview of managing access permissions to your AWS CodeBuild resources](auth-and-access-control-iam-access-control-identity-based.md)\. - -**Topics** -+ [Permissions required to use the AWS CodeBuild console](#console-permissions) -+ [Permissions required for the AWS CodeBuild console to connect to source providers](#console-policies) -+ [AWS managed \(predefined\) policies for AWS CodeBuild](#managed-policies) -+ [CodeBuild managed policies and notifications](#notifications-permissions) -+ [Customer\-managed policy examples](#customer-managed-policies) - -The following shows an example of a permissions policy that allows a user to get information about build projects only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:BatchGetProjects", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" - } - ] -} -``` - -## Permissions required to use the AWS CodeBuild console - -A user who uses the AWS CodeBuild console must have a minimum set of permissions that allows the user to describe other AWS resources for the AWS account\. You must have permissions from the following services: -+ AWS CodeBuild -+ Amazon CloudWatch -+ CodeCommit \(if you are storing your source code in an AWS CodeCommit repository\) -+ Amazon Elastic Container Registry \(Amazon ECR\) \(if you are using a build environment that relies on a Docker image in an Amazon ECR repository\) -+ Amazon Elastic Container Service \(Amazon ECS\) \(if you are using a build environment that relies on a Docker image in an Amazon ECR repository\) -+ AWS Identity and Access Management \(IAM\) -+ AWS Key Management Service \(AWS KMS\) -+ Amazon Simple Storage Service \(Amazon S3\) - -If you create an IAM policy that is more restrictive than the minimum required permissions, the console won't function as intended\. - -## Permissions required for the AWS CodeBuild console to connect to source providers - -The AWS CodeBuild console uses the following API actions to connect to source providers \(for example, GitHub repositories\)\. -+ `codebuild:ListConnectedOAuthAccounts` -+ `codebuild:ListRepositories` -+ `codebuild:PersistOAuthToken` -+ `codebuild:ImportSourceCredentials` - -You can associate source providers \(such as GitHub repositories\) with your build projects using the AWS CodeBuild console\. To do this, you must first add the preceding API actions to IAM access policies associated with the IAM user you use to access the AWS CodeBuild console\. - -The `ListConnectedOAuthAccounts`, `ListRepositories`, and `PersistOAuthToken` API actions are not intended to be called by your code\. Therefore, these API actions are not included in the AWS CLI and AWS SDKs\. - -## 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 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\. - -To access build output artifacts that CodeBuild creates, you must also attach the AWS managed policy named `AmazonS3ReadOnlyAccess`\. - -To create and manage CodeBuild service roles, you must also attach the AWS managed policy named `IAMFullAccess`\. - -You can also create your own custom IAM policies to allow permissions for CodeBuild actions and resources\. You can attach these custom policies to the IAM users or groups that require those permissions\. - -**Topics** -+ [AWSCodeBuildAdminAccess](#admin-access-policy) -+ [AWSCodeBuildDeveloperAccess](#developer-access-policy) -+ [AWSCodeBuildReadOnlyAccess](#read-only-access-policy) - -### AWSCodeBuildAdminAccess - -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", - "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 - -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: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:*" - } - } - }, - { - "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 - -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", - "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:*" - } - } - }, - { - "Sid": "CodeStarNotificationsListAccess", - "Effect": "Allow", - "Action": [ - "codestar-notifications:ListNotificationRules", - "codestar-notifications:ListEventTypes", - "codestar-notifications:ListTargets" - ], - "Resource": "*" - } - ], - "Version": "2012-10-17" -} -``` - -## CodeBuild managed policies and notifications - -CodeBuild supports notifications, which can notify users of important changes to build projects\. Managed policies for CodeBuild include policy statements for notification functionality\. For more information, see [What are notifications?](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/welcome.html)\. - -### Permissions related to notifications in full access managed policies - -The `AWSCodeBuildFullAccess` managed policy includes the following statements to allow full access to notifications\. Users with this managed policy applied can also create and manage Amazon SNS topics for notifications, subscribe and unsubscribe users to topics, list topics to choose as targets for notification rules, and list AWS Chatbot clients configured for Slack\. - -``` - { - "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:ListTargets", - "codestar-notifications:ListTagsforResource", - "codestar-notifications:ListEventTypes" - ], - "Resource": "*" - }, - { - "Sid": "CodeStarNotificationsSNSTopicCreateAccess", - "Effect": "Allow", - "Action": [ - "sns:CreateTopic", - "sns:SetTopicAttributes" - ], - "Resource": "arn:aws:sns:*:*:codestar-notifications*" - }, - { - "Sid": "SNSTopicListAccess", - "Effect": "Allow", - "Action": [ - "sns:ListTopics" - ], - "Resource": "*" - }, - { - "Sid": "CodeStarNotificationsChatbotAccess", - "Effect": "Allow", - "Action": [ - "chatbot:DescribeSlackChannelConfigurations" - ], - "Resource": "*" - } -``` - -### Permissions related to notifications in read\-only managed policies - -The `AWSCodeBuildReadOnlyAccess` managed policy includes the following statements to allow read\-only access to notifications\. Users with this managed policy applied can view notifications for resources, but cannot create, manage, or subscribe to them\. - -``` - { - "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", - "codestar-notifications:ListTargets" - ], - "Resource": "*" - } -``` - -### Permissions related to notifications in other managed policies - -The `AWSCodeBuildDeveloperAccess` managed policy includes the following statements to allow users to create, edit, and subscribe to notifications\. Users cannot delete notification rules or manage tags for resources\. - -``` - { - "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:ListTargets", - "codestar-notifications:ListTagsforResource", - "codestar-notifications:ListEventTypes" - ], - "Resource": "*" - }, - { - "Sid": "SNSTopicListAccess", - "Effect": "Allow", - "Action": [ - "sns:ListTopics" - ], - "Resource": "*" - }, - { - "Sid": "CodeStarNotificationsChatbotAccess", - "Effect": "Allow", - "Action": [ - "chatbot:DescribeSlackChannelConfigurations" - ], - "Resource": "*" - } -``` - -For more information about IAM and notifications, see [Identity and Access Management for AWS CodeStar Notifications](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security-iam.html)\. - -## Customer\-managed policy examples - -In this section, you can find example user policies that grant permissions for AWS CodeBuild actions\. These policies work when you are using the CodeBuild API, AWS SDKs, or AWS CLI\. When you are using the console, you must grant additional, console\-specific permissions\. For information, see [Permissions required to use the AWS CodeBuild console](#console-permissions)\. - -You can use the following sample IAM policies to limit CodeBuild access for your IAM users and roles\. - -**Topics** -+ [Allow a user to get information about build projects](#customer-managed-policies-example-batch-get-projects) -+ [Allow a user to get information about report groups](#customer-managed-policies-get-information-about-report-group) -+ [Allow a user to get information about reports](#customer-managed-policies-get-information-about-reports) -+ [Allow a user to create build projects](#customer-managed-policies-example-create-project) -+ [Allow a user to create a report group](#customer-managed-policies-example-create-report-group) -+ [Allow a user to delete a report group](#customer-managed-policies-example-delete-report-group) -+ [Allow a user to delete a report](#customer-managed-policies-example-delete-report) -+ [Allow a user to delete build projects](#customer-managed-policies-example-delete-project) -+ [Allow a user to get a list of build project names](#customer-managed-policies-example-list-projects) -+ [Allow a user to change information about build projects](#customer-managed-policies-example-update-project) -+ [Allow a user to change a report group](#customer-managed-policies-example-change-report-group) -+ [Allow a user to get information about builds](#customer-managed-policies-example-batch-get-builds) -+ [Allow a user to get a list of build IDs for a build project](#customer-managed-policies-example-list-builds-for-project) -+ [Allow a user to get a list of build IDs](#customer-managed-policies-example-list-builds) -+ [Allow a user to get a list of report groups](#customer-managed-policies-example-get-list-of-report-groups) -+ [Allow a user to get a list of reports](#customer-managed-policies-example-get-list-of-reports) -+ [Allow a user to get a list of reports for a report group](#customer-managed-policies-example-get-list-of-reports-for-report-group) -+ [Allow a user to get a list of test cases for a report](#customer-managed-policies-example-get-list-of-test-cases-for-report) -+ [Allow a user to start running builds](#customer-managed-policies-example-start-build) -+ [Allow a user to attempt to stop builds](#customer-managed-policies-example-stop-build) -+ [Allow a user to attempt to delete builds](#customer-managed-policies-example-delete-builds) -+ [Allow a user to get information about Docker images that are managed by CodeBuild](#customer-managed-policies-example-list-curated-environment-images) -+ [Allow CodeBuild access to AWS services required to create a VPC network interface](#customer-managed-policies-example-create-vpc-network-interface) -+ [Use a deny statement to prevent AWS CodeBuild from disconnecting from source providers](#customer-managed-policies-example-deny-disconnect) - -### Allow a user to get information about build projects - -The following example policy statement allows a user to get information about build projects in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:BatchGetProjects", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" - } - ] -} -``` - -### Allow a user to get information about report groups - -The following example policy statement allows a user to get information about report groups in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:BatchGetReportGroups", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to get information about reports - -The following example policy statement allows a user to get information about reports in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:BatchGetReports", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to create build projects - -The following example policy statement allows a user to create build projects with any name but only in the `us-east-2` Region for account `123456789012` and only using the specified CodeBuild service role: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:CreateProject", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/*" - }, - { - "Effect": "Allow", - "Action": "iam:PassRole", - "Resource": "arn:aws:iam::123456789012:role/CodeBuildServiceRole" - } - ] -} -``` - -### Allow a user to create a report group - -The following example policy statement allows a user to create a report group in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:CreateReportGroup", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to delete a report group - -The following example policy statement allows a user to delete a report group in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:DeleteReportGroup", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to delete a report - -The following example policy statement allows a user to delete a report in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:DeleteReport", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to delete build projects - -The following example policy statement allows a user to delete build projects in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:DeleteProject", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" - } - ] -} -``` - -### Allow a user to get a list of build project names - -The following example policy statement allows a user to get a list of build project names for the same account: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListProjects", - "Resource": "*" - } - ] -} -``` - -### Allow a user to change information about build projects - -The following example policy statement allows a user to change information about build projects with any name but only in the `us-east-2` Region for account `123456789012` and only using the specified AWS CodeBuild service role: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:UpdateProject", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/*" - }, - { - "Effect": "Allow", - "Action": "iam:PassRole", - "Resource": "arn:aws:iam::123456789012:role/CodeBuildServiceRole" - } - ] -} -``` - -### Allow a user to change a report group - -The following example policy statement allows a user to change a report group in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:UpdateReportGroup", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to get information about builds - -The following example policy statement allows a user to get information about builds in the `us-east-2` Region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:BatchGetBuilds", - "Resource": [ - "arn:aws:codebuild:us-east-2:123456789012:project/my-build-project", - "arn:aws:codebuild:us-east-2:123456789012:project/my-other-build-project" - ] - } - ] -} -``` - -### Allow a user to get a list of build IDs for a build project - -The following example policy statement allows a user to get a list of build IDs in the `us-east-2` Region for account `123456789012` for the build projects named `my-build-project` and `my-other-build-project`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListBuildsForProject", - "Resource": [ - "arn:aws:codebuild:us-east-2:123456789012:project/my-build-project", - "arn:aws:codebuild:us-east-2:123456789012:project/my-other-build-project" - ] - } - ] -} -``` - -### Allow a user to get a list of build IDs - -The following example policy statement allows a user to get a list of all build IDs for the same account: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListBuilds", - "Resource": "*" - } - ] -} -``` - -### Allow a user to get a list of report groups - -The following example policy statement allows a user to get a list of report groups in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListReportGroups", - "Resource": "*" - } - ] -} -``` - -### Allow a user to get a list of reports - -The following example policy statement allows a user to get a list of reports in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListReports", - "Resource": "*" - } - ] -} -``` - -### Allow a user to get a list of reports for a report group - -The following example policy statement allows a user to get a list of reports for a report group in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListReportsForReportGroup", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to get a list of test cases for a report - -The following example policy statement allows a user to get a list of test cases for a report in the `us-east-2` Region for account `123456789012`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:DescribeTestCases", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:report-group/*" - } - ] -} -``` - -### Allow a user to start running builds - -The following example policy statement allows a user to run builds in the `us-east-2` Region for account `123456789012` for a build project that starts with the name `my`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:StartBuild", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" - } - ] -} -``` - -### Allow a user to attempt to stop builds - -The following example policy statement allows a user to attempt to stop running builds only in the `us-east-2` region for account `123456789012` for any build project that starts with the name `my`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:StopBuild", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" - } - ] -} -``` - -### Allow a user to attempt to delete builds - -The following example policy statement allows a user to attempt to delete builds only in the `us-east-2` Region for account `123456789012` for any build project that starts with the name `my`: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:BatchDeleteBuilds", - "Resource": "arn:aws:codebuild:us-east-2:123456789012:project/my*" - } - ] -} -``` - -### Allow a user to get information about Docker images that are managed by CodeBuild - -The following example policy statement allows a user to get information about all Docker images that are managed by CodeBuild: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "codebuild:ListCuratedEnvironmentImages", - "Resource": "*" - } - ] -} -``` - -### Allow CodeBuild access to AWS services required to create a VPC network interface - -The following example policy statement grants AWS CodeBuild permission to create a network interface in a VPC with two subnets: - -``` -{ - "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" - }, - "ArnEquals": { - "ec2:Subnet": [ - "arn:aws:ec2:region:account-id:subnet/subnet-id-1", - "arn:aws:ec2:region:account-id:subnet/subnet-id-2" - ] - } - } - } - ] -} -``` - -### Use a deny statement to prevent AWS CodeBuild from disconnecting from source providers - - The following example policy statement uses a deny statement to prevent AWS CodeBuild from disconnecting from source providers\. It uses `codebuild:DeleteOAuthToken`, which is the inverse of `codebuild:PersistOAuthToken` and `codebuild:ImportSourceCredentials`, to connect with source providers\. For more information, see [Permissions required for the AWS CodeBuild console to connect to source providers](#console-policies)\. - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Deny", - "Action": "codebuild:DeleteOAuthToken", - "Resource": "*" - } - ] -} -``` \ No newline at end of file diff --git a/doc_source/auth-and-access-control-permissions-reference.md b/doc_source/auth-and-access-control-permissions-reference.md deleted file mode 100644 index 364ab35..0000000 --- a/doc_source/auth-and-access-control-permissions-reference.md +++ /dev/null @@ -1,198 +0,0 @@ -# AWS CodeBuild permissions reference - -You can use the following table as a reference when you are setting up [Access control](auth-and-access-control.md#access-control) and writing permissions policies that you can attach to an IAM identity \(identity\-based policies\)\. - -You can use AWS\-wide condition keys in your AWS CodeBuild policies to express conditions\. For a list, see [Available Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#AvailableKeys) in the *IAM User Guide*\. - -You specify the actions in the policy's `Action` field\. To specify an action, use the `codebuild:` prefix followed by the API operation name \(for example, `codebuild:CreateProject` and `codebuild:StartBuild`\)\. To specify multiple actions in a single statement, separate them with commas \(for example, `"Action": [ "codebuild:CreateProject", "codebuild:StartBuild" ]`\)\. - -**Using Wildcard Characters** - -You specify an ARN, with or without a wildcard character \(\*\), as the resource value in the policy's `Resource` field\. You can use a wildcard to specify multiple actions or resources\. For example, `codebuild:*` specifies all CodeBuild actions and `codebuild:Batch*` specifies all CodeBuild actions that begin with the word `Batch`\. The following example grants access to all build project with names that begin with `my`: - -``` -arn:aws:codebuild:us-east-2:123456789012:project/my* -```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 ` - -BatchGetBuilds - **Action:** `codebuild:BatchGetBuilds` -Required to get information about builds\. - **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 ` - -BatchGetReportGroups - **Action:** `codebuild:BatchGetReportGroups` -Required to get information about report groups\. - **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 ` - -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 ` - -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 ` - -CreateReport ¹ - **Action:** `codebuild:CreateReport` -Required to create a test report\. - **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 ` - -CreateWebhook - **Action:** `codebuild:CreateWebhook` -Required to create a webhook\. - **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 ` - -DeleteReportGroup - **Action:** `codebuild:DeleteReportGroup` -Required to delete a report group\. - **Resource:** `arn:aws:codebuild:region-ID:account-ID:report-group/report-group-name ` - -DeleteSourceCredentials - **Action:** `codebuild:DeleteSourceCredentials` -Required to delete a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise Server, or Bitbucket repository\. - **Resource:** `*` - -DeleteWebhook - **Action:** `codebuild:DeleteWebhook` -Required to create a webhook\. - **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 ` - -ImportSourceCredentials - **Action:** `codebuild:ImportSourceCredentials` -Required to import a set of `SourceCredentialsInfo` objects that contain information about credentials for a GitHub, GitHub Enterprise Server, or Bitbucket repository\. - **Resource:** `*` - -InvalidateProjectCache - **Action:** `codebuild:InvalidateProjectCache` -Required to reset the cache for a project\. - **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` -Required to get a list of build IDs\. - **Resource:** `*` - -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 ` - -ListCuratedEnvironmentImages - **Action:** `codebuild:ListCuratedEnvironmentImages` -Required to get information about all Docker images that are managed by AWS CodeBuild\. - **Resource:** `*` \(required, but does not refer to an addressable AWS resource\) - -ListProjects - **Action:** `codebuild:ListProjects` -Required to get a list of build project names\. - **Resource:** `*` - -ListReportGroups - **Action:** `codebuild:ListReportGroups` -Required to get a list of report groups\. - **Resource:** `*` - -ListReports - **Action:** `codebuild:ListReports` -Required to get a list of reports\. - **Resource:** `*` - -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 ` - -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 ` - -StopBuild - **Action:** `codebuild:StopBuild` -Required to attempt to stop running builds\. - **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 ` - -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 ` - -UpdateReportGroup - **Action:** `codebuild:UpdateReportGroup` -Required to update a report group\. - **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 ` - -¹ 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 deleted file mode 100644 index 8fdc271..0000000 --- a/doc_source/auth-and-access-control-using-tags.md +++ /dev/null @@ -1,128 +0,0 @@ -# Using tags to control access to AWS CodeBuild resources - -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 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\. - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Deny", - "Action": [ - "codebuild:BatchGetProjects" - ], - "Resource": "*", - "Condition": { - "ForAnyValue:StringEquals": { - "aws:ResourceTag/Environment": "Production" - } - } - } - ] -} -``` - -**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 - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Deny", - "Action": [ - "codebuild:CreateProject" - ], - "Resource": "*", - "Condition": { - "ForAnyValue:StringEquals": { - "aws:RequestTag/Environment": "Production" - } - } - }, - { - "Effect": "Deny", - "Action": [ - "codebuild:UpdateProject" - ], - "Resource": "*", - "Condition": { - "ForAnyValue:StringEquals": { - "aws:TagKeys": ["Environment"] - } - } - } - ] -} -``` - -**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`: - -``` -{ - "Version": "2012-10-17", - "Statement" : [ - { - "Effect" : "Deny", - "Action" : [ - "codebuild:BatchGetReportGroups," - "codebuild:CreateReportGroup", - "codebuild:DeleteReportGroup", - "codebuild:ListReportGroups", - "codebuild:ListReportsForReportGroup", - "codebuild:UpdateReportGroup" - ] - "Resource" : "*", - "Condition" : { - "StringEquals" : "aws:ResourceTag/Status": "Secret" - } - } - ] -} -``` - -**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: - -``` -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "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" - ], - "Resource": "*", - "Condition": { - "StringNotEquals": { - "aws:ResourceTag/Status": "Secret", - "aws:ResourceTag/Team": "Saanvi" - } - } - } - ] -} -``` \ No newline at end of file diff --git a/doc_source/auth-and-access-control.md b/doc_source/auth-and-access-control.md deleted file mode 100644 index f3a054a..0000000 --- a/doc_source/auth-and-access-control.md +++ /dev/null @@ -1,30 +0,0 @@ -# Identity and access management in AWS CodeBuild - -Access to AWS CodeBuild requires credentials\. Those credentials must have permissions to access AWS resources, such as storing and retrieving build artifacts in S3 buckets and viewing Amazon CloudWatch Logs for builds\. The following sections describe how you can use [AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) \(IAM\) and CodeBuild to help secure access to your resources: -+ [Authentication](#authentication) -+ [Access control](#access-control) - -## Authentication - -You can access AWS as any of the following types of identities: -+ **AWS account root user** – When you sign up for AWS, you provide an email address and password that is associated with your AWS account\. These are your *root credentials* and they provide complete access to all of your AWS resources\. -**Important** -For security reasons, we recommend that you use the root credentials only to create an administrator user, which is an IAM user with full permissions to your AWS account\. Then, you can use this administrator user to create other IAM users and roles with limited permissions\. For more information, see [IAM Best Practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users) and [Creating an Admin User and Group](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) in the *IAM User Guide*\. -+ **IAM user** – An [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html) is simply an identity in your AWS account that has custom permissions \(for example, permission to create build projects in CodeBuild\)\. You can use an IAM user name and password to sign in to secure AWS webpages like the [AWS Management Console](https://console.aws.amazon.com/), [AWS Discussion Forums](https://forums.aws.amazon.com/), or the [AWS Support Center](https://console.aws.amazon.com/support/home#/)\. - - In addition to a user name and password, you can also generate [access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for each user\. You can use these keys when you access AWS services programmatically, either through [one of the AWS SDKs](https://aws.amazon.com/tools/) or by using the [AWS Command Line Interface \(AWS CLI\)](https://aws.amazon.com/cli/)\. The AWS SDKs and AWS CLI tools use the access keys to cryptographically sign your request\. If you don’t use the AWS tools, you must sign the request yourself\. CodeBuild supports Signature Version 4, a protocol for authenticating inbound API requests\. For more information about authenticating requests, see the [Signature Version 4 Signing Process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference*\. -+ **IAM role** – An [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is similar to an IAM user, but it is not associated with a specific person\. An IAM role enables you to obtain temporary access keys that can be used to access AWS services and resources\. IAM roles with temporary credentials are useful in the following situations: - + **Federated user access** – Instead of creating an IAM user, you can use preexisting user identities from AWS Directory Service, your enterprise user directory, or a web identity provider\. These are known as federated users\. AWS assigns a role to a federated user when access is requested through an [identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)\. For more information about federated users, see [Federated Users and Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_access-management.html#intro-access-roles) in the *IAM User Guide*\. - + **Cross\-account access** – You can use an IAM role in your account to grant another AWS account permissions to access your account’s resources\. For an example, see [Tutorial: Delegate Access Across AWS Accounts Using IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html) in the *IAM User Guide*\. - + **AWS service access** – You can use an IAM role in your account to grant permissions to an AWS service to access your account’s resources\. For example, you can create a role that allows Amazon Redshift to access an S3 bucket on your behalf and then load data stored in the bucket into an Amazon Redshift cluster\. For more information, see [Creating a Role to Delegate Permissions to an AWS Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide*\. - + **Applications running on Amazon EC2** – Instead of storing access keys in the Amazon EC2 instance for use by applications running on the instance and making AWS API requests, you can use an IAM role to manage temporary credentials for these applications\. To assign an AWS role to an Amazon EC2 instance and make it available to all of its applications, you can create an instance profile that is attached to the instance\. An instance profile contains the role and enables programs running on the Amazon EC2 instance to get temporary credentials\. For more information, see [Using Roles for Applications on Amazon EC2](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) in the *IAM User Guide*\. - -## Access control - -You can have valid credentials to authenticate your requests, but unless you have permissions, you cannot create or access AWS CodeBuild resources\. For example, you must have permissions to create, view, or delete build projects and to start, stop, or view builds\. - -The following sections describe how to manage permissions for CodeBuild\. We recommend that you read the overview first\. -+ [Overview of managing access permissions to your AWS CodeBuild resources](auth-and-access-control-iam-access-control-identity-based.md) -+ [Using identity\-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) -+ [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md) -+ [Viewing resources in the console](console-resources.md) \ No newline at end of file diff --git a/doc_source/available-runtimes.md b/doc_source/available-runtimes.md deleted file mode 100644 index 7003c5d..0000000 --- a/doc_source/available-runtimes.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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 deleted file mode 100644 index 46e1415..0000000 --- a/doc_source/batch-build-buildspec.md +++ /dev/null @@ -1,200 +0,0 @@ -# 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 deleted file mode 100644 index 5119cff..0000000 --- a/doc_source/batch-build.md +++ /dev/null @@ -1,143 +0,0 @@ -# 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 deleted file mode 100644 index f754b8e..0000000 --- a/doc_source/bitbucket-webhook.md +++ /dev/null @@ -1,247 +0,0 @@ -# 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 deleted file mode 100644 index d5efdbc..0000000 --- a/doc_source/build-caching.md +++ /dev/null @@ -1,117 +0,0 @@ -# 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\. - -**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\. - -**Topics** -+ [Amazon S3 caching](#caching-s3) -+ [Local caching](#caching-local) - -## 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 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 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\. -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)\. - + 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** -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\. - -### 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: - - ``` - --cache type=LOCAL,mode=[LOCAL_SOURCE_CACHE] - ``` -+ To specify a Docker layer cache: - - ``` - --cache type=LOCAL,mode=[LOCAL_DOCKER_LAYER_CACHE] - ``` -+ To specify a custom cache: - - ``` - --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE] - ``` - -For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. - -### Specify local caching \(console\) - -You specify a cache in the **Artifacts** section of the console\. For **Cache type**, choose **Amazon S3** or **Local**\. If you choose **Local**, choose one or more of the three local cache options\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/local-cache.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 build project \(console\)](create-project-console.md)\. - -### 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`\. - -``` -CodeBuildProject: - Type: AWS::CodeBuild::Project - Properties: - Name: MyProject - ServiceRole: - Artifacts: - Type: S3 - Location: myBucket - Name: myArtifact - EncryptionDisabled: true - OverrideArtifactName: true - Environment: - Type: LINUX_CONTAINER - ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:5.0 - Certificate: bucket/cert.zip - # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE - PrivilegedMode: true - Source: - Type: GITHUB - Location: - InsecureSsl: true - GitCloneDepth: 1 - ReportBuildStatus: false - TimeoutInMinutes: 10 - Cache: - Type: LOCAL - Modes: # You can specify one or more cache mode, - - LOCAL_CUSTOM_CACHE - - LOCAL_DOCKER_LAYER_CACHE - - LOCAL_SOURCE_CACHE -``` - -**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\. - -For more information, see [Create a build project \(AWS CloudFormation\)](create-project-cloud-formation.md)\. \ No newline at end of file diff --git a/doc_source/build-env-ref-available.md b/doc_source/build-env-ref-available.md deleted file mode 100644 index e5547a1..0000000 --- a/doc_source/build-env-ref-available.md +++ /dev/null @@ -1,35 +0,0 @@ -# Docker images provided by CodeBuild - -AWS CodeBuild manages the following Docker images that are available in the CodeBuild and AWS CodePipeline consoles\. - - -| 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: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 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 | - -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-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)\. - -**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-background-tasks.md b/doc_source/build-env-ref-background-tasks.md deleted file mode 100644 index b88b3a1..0000000 --- a/doc_source/build-env-ref-background-tasks.md +++ /dev/null @@ -1,24 +0,0 @@ -# Background tasks in build environments - -You can run background tasks in build environments\. To do this, in your buildspec, use the `nohup` command to run a command as a task in the background, even if the build process exits the shell\. Use the disown command to forcibly stop a running background task\. - -**Examples:** -+ Start a background process and wait for it to complete later: - - ``` - nohup sleep 30 & echo $! > pidfile - … - wait $(cat pidfile) - ``` -+ Start a background process and do not wait for it to ever complete: - - ``` - nohup sleep 30 & disown $! - ``` -+ Start a background process and kill it later: - - ``` - nohup sleep 30 & echo $! > pidfile - … - kill $(cat pidfile) - ``` \ No newline at end of file diff --git a/doc_source/build-env-ref-cmd.md b/doc_source/build-env-ref-cmd.md deleted file mode 100644 index e9119d3..0000000 --- a/doc_source/build-env-ref-cmd.md +++ /dev/null @@ -1,16 +0,0 @@ -# Shells and commands in build environments - -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-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)\. - -You can specify any Shell Command Language \(sh\) command\. In buildspec version 0\.1, CodeBuild runs each Shell command in a separate instance in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use version 0\.1, we recommend the following approaches: -+ Include a shell script in your source code that contains the commands you want to run in a single instance of the default shell\. For example, you could include a file named `my-script.sh` in your source code that contains commands such as `cd MyDir; mkdir -p mySubDir; cd mySubDir; pwd;`\. Then, in your buildspec file, specify the command `./my-script.sh`\. -+ In your buildspec file or on the **Build commands** setting for the `build` phase only, enter a single command that includes all of the commands you want to run in a single instance of the default shell \(for example, `cd MyDir && mkdir -p mySubDir && cd mySubDir && pwd`\)\. - -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 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 deleted file mode 100644 index 8b634bf..0000000 --- a/doc_source/build-env-ref-compute-types.md +++ /dev/null @@ -1,89 +0,0 @@ -# Build environment compute types - -AWS CodeBuild provides build environments with the following available memory, vCPUs, and disk space: - - -| Compute type | Environment computeType value | Environment type value | Memory | vCPUs | Disk space | -| --- | --- | --- | --- | --- | --- | -| 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 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`\. - -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\. - -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)\. - -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\. - -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** -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\. \ No newline at end of file diff --git a/doc_source/build-env-ref-env-vars.md b/doc_source/build-env-ref-env-vars.md deleted file mode 100644 index f760c22..0000000 --- a/doc_source/build-env-ref-env-vars.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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\_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`\. -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 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) -+ [Buildspec reference](build-spec-ref.md) - -To list all of the available environment variables in a build environment, you can run the `printenv` command \(for Linux\-based build environment\) or `"Get-ChildItem Env:"` \(for Windows\-based build environments\) during a build\. Except for those previously listed, environment variables that start with `CODEBUILD_` are for CodeBuild internal use\. They should not be used in your build commands\. - -**Important** -We strongly discourage the use of environment variables to store sensitive values, especially AWS access key IDs and secret access keys\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. -We recommend you store sensitive values in the Amazon EC2 Systems Manager Parameter Store and then retrieve them from your buildspec\. To store sensitive values, 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*\. To retrieve them, see the `parameter-store` mapping in [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. \ No newline at end of file diff --git a/doc_source/build-env-ref.md b/doc_source/build-env-ref.md deleted file mode 100644 index 51956dd..0000000 --- a/doc_source/build-env-ref.md +++ /dev/null @@ -1,19 +0,0 @@ -# Build environment reference for AWS CodeBuild - -When you call AWS CodeBuild to run a build, you must provide information about the build environment\. A *build environment* represents a combination of operating system, programming language runtime, and tools that CodeBuild uses to run a build\. For information about how a build environment works, see [How CodeBuild works](concepts.md#concepts-how-it-works)\. - -A build environment contains a Docker image\. For information, see [the Docker glossary](https://docs.docker.com/glossary/?term=image) on the Docker Docs website\. - -When you provide information to CodeBuild about the build environment, you specify the identifier of a Docker image in a supported repository type\. These include the CodeBuild Docker image repository, publicly available images in Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\) repositories that your AWS account has permissions to access\. -+ We recommend that you use Docker images stored in the CodeBuild Docker image repository, because they are optimized for use with the service\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. -+ To get the identifier of a publicly available Docker image stored in Docker Hub, see [Searching for Repositories](https://docs.docker.com/docker-hub/repos/#searching-for-repositories) on the Docker Docs website\. -+ To learn how to work with Docker images stored in Amazon ECR repositories in your AWS account, see [Amazon ECR sample](sample-ecr.md)\. - -In addition to a Docker image identifier, you also specify a set of computing resources that the build environment uses\. For more information, see [Build environment compute types](build-env-ref-compute-types.md)\. - -**Topics** -+ [Docker images provided by CodeBuild](build-env-ref-available.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) \ No newline at end of file diff --git a/doc_source/build-spec-ref.md b/doc_source/build-spec-ref.md deleted file mode 100644 index 2a287b2..0000000 --- a/doc_source/build-spec-ref.md +++ /dev/null @@ -1,642 +0,0 @@ -# Build specification reference for CodeBuild - -This topic provides important reference information about build specification \(buildspec\) files\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. You can include a buildspec as part of the source code or you can define a buildspec when you create a build project\. For information about how a build spec works, see [How CodeBuild works](concepts.md#concepts-how-it-works)\. - -**Topics** -+ [Buildspec file name and storage location](#build-spec-ref-name-storage) -+ [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 - -If you include a buildspec as part of the source code, by default, the buildspec file must be named `buildspec.yml` and placed in the root of your source directory\. - -You can override the default buildspec file name and location\. For example, you can: -+ Use a different buildspec file for different builds in the same repository, such as `buildspec_debug.yml` and `buildspec_release.yml`\. -+ Store a buildspec file somewhere other than the root of your source directory, such as `config/buildspec.yml` or in an S3 bucket\. The S3 bucket 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`\)\. - -You can specify only one buildspec for a build project, regardless of the buildspec file's name\. - -To override the default buildspec file name, location, or both, do one of the following: -+ Run the AWS CLI `create-project` or `update-project` command, setting the `buildspec` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `create project` operation in the AWS SDKs\. For more information, see [Create a build project](create-project.md) or [Change a build project's settings](change-project.md)\. -+ Run the AWS CLI `start-build` command, setting the `buildspecOverride` value to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. You can also do the equivalent with the `start build` operation in the AWS SDKs\. For more information, see [Run a build](run-build.md)\. -+ In an AWS CloudFormation template, set the `BuildSpec` property of `Source` in a resource of type `AWS::CodeBuild::Project` to the path to the alternate buildspec file relative to the value of the built\-in environment variable `CODEBUILD_SRC_DIR`\. For more information, see the BuildSpec property in [AWS CodeBuild project source](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html) in the *AWS CloudFormation User Guide*\. - -## Buildspec syntax - -Buildspec files must be expressed in [YAML](http://yaml.org/) format\. - -If a command contains a character, or a string of characters, that is not supported by YAML, you must enclose the command in quotation marks \(""\)\. The following command is enclosed in quotation marks because a colon \(:\) followed by a space is not allowed in YAML\. The quotation mark in the command is escaped \(\\"\)\. - -``` -"export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')" -``` - -The buildspec has the following syntax: - -``` -version: 0.2 - -run\-as: Linux-user-name - -env: - shell: shell-tag - variables: - key: "value" - key: "value" - parameter\-store: - key: "value" - key: "value" - exported\-variables: - - variable - - variable - secrets\-manager: - key: secret-id:json-key:version-stage:version-id - git\-credential\-helper: no | yes - -proxy: - 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 - on\-failure: ABORT | CONTINUE - runtime\-versions: - runtime: version - runtime: version - commands: - - command - - command - finally: - - command - - command - pre\_build: - run\-as: Linux-user-name - on\-failure: ABORT | CONTINUE - commands: - - command - - command - finally: - - command - - command - build: - run\-as: Linux-user-name - on\-failure: ABORT | CONTINUE - commands: - - command - - command - finally: - - command - - command - post\_build: - run\-as: Linux-user-name - on\-failure: ABORT | CONTINUE - commands: - - command - - command - finally: - - command - - command -reports: - report-group-name-or-arn: - files: - - location - - location - 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 - 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 - artifactIdentifier: - files: - - location - - location - discard\-paths: no | yes - base\-directory: location -cache: - paths: - - path - - path -``` - -The buildspec contains the following: - -### version - -Required mapping\. Represents the buildspec version\. We recommend that you use `0.2`\. - -**Note** -Although version 0\.1 is still supported, we recommend that you use version 0\.2 whenever possible\. For more information, see [Buildspec versions](#build-spec-ref-versions)\. - -### 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 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 - -Optional sequence\. Represents information for one or more custom environment variables\. - -**Note** - 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 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)\. - -env/**shell** -Optional sequence\. Specifies the supported shell for Linux or Windows operating systems\. -For Linux operating systems, supported shell tags are: -+ `bash` -+ `/bin/sh` -For Windows operating systems, supported shell tags are: -+ `powershell.exe` -+ `cmd.exe` - -env/**variables** -Required if `env` is specified, and you want to define custom environment variables in plain text\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable in plain text\. *key* is the name of the custom environment variable, and *value* is that variable's value\. -We strongly discourage the storing of sensitive values, especially AWS access key IDs and secret access keys, in environment variables\. Environment variables can be displayed in plain text using tools such as the CodeBuild console and the AWS CLI\. For sensitive values, we recommend that you use `parameter-store` or `secrets-manager` mapping instead, as described later in this section\. -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 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 buildspec declaration takes lowest precedence\. - -env/**parameter\-store** -Required if `env` is specified, and you want to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store\. Contains a mapping of *key*/*value* scalars, where each mapping represents a single custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. *key* is the name you use later in your build commands to refer to this custom environment variable, and *value* is the name of the custom environment variable stored in Amazon EC2 Systems Manager Parameter Store\. To store sensitive values, 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*\. -To allow CodeBuild to retrieve custom environment variables stored in Amazon EC2 Systems Manager Parameter Store, you must add the `ssm:GetParameters` action to your CodeBuild service role\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. -Any environment variables you retrieve from Amazon EC2 Systems Manager Parameter Store 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 retrieve 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 retrieve 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 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 buildspec declaration takes lowest precedence\. - -env/**secrets\-manager** -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\. -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 -+ Environment variables that start with `AWS_`\. - -env/**git\-credential\-helper** -Optional mapping\. Used to indicate if CodeBuild uses its Git credential helper to provide Git credentials\. `yes` if it is used\. Otherwise, `no` or not specified\. For more information, see [gitcredentials](https://git-scm.com/docs/gitcredentials) on the Git website\. - `git-credential-helper` is not supported for builds that are triggered by a webhook for a public Git repository\. - -### proxy - -Optional sequence\. Used to represent settings if you run your build in an explicit proxy server\. For more information, see [ Run CodeBuild in an explicit proxy server](use-proxy-server.md#run-codebuild-in-explicit-proxy-server)\. - -proxy/**upload\-artifacts** -Optional mapping\. Set to `yes` if you want your build in an explicit proxy server to upload artifacts\. The default is `no`\. - -proxy/**logs** -Optional mapping\. Set to `yes` for your build in a explicit proxy server to create CloudWatch logs\. The default is `no`\. - -### phases - -Required sequence\. Represents the commands CodeBuild runs during each phase of the build\. - -**Note** -In buildspec version 0\.1, CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. Therefore, by default, you cannot run a single command that relies on the state of any previous commands \(for example, changing directories or setting environment variables\)\. To get around this limitation, we recommend that you use version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend the approaches in [Shells and commands in build environments](build-env-ref-cmd.md)\. - -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** -Optional sequence\. Represents the commands, if any, that CodeBuild runs during installation\. We recommend that you use the `install` phase only for installing packages in the build environment\. For example, you might use this phase to install a code testing framework such as Mocha or RSpec\. -phases/install/**runtime\-versions** -Optional sequence\. A runtime version is supported with the Ubuntu standard image 2\.0 or later and the Amazon Linux 2 standard image 1\.0 or later\. If specified, at least one runtime must be included in this section\. Specify a runtime using a specific version, a major version followed by `.x` to specify that CodeBuild uses that major version with its latest minor version, or `latest` to use the most recent major and minor version \(for example, `java: openjdk11`, `ruby: 2.6`, `nodejs: 12.x`, or `java: latest`\)\. You can specify the runtime using a number or an environment variable\. For example, if you use the Amazon Linux 2 standard image 2\.0, then the following specifies that version 8 of Java, the latest minor version of python version 3, and a version contained in an environment variable of Ruby is installed\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - -``` -phases: - install: - runtime-versions: - java: corretto8 - 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\. -If two specified runtimes conflict, the build fails\. For example, `android: 29` and `java: openjdk11` conflict, so if both are specified, the build fails\. -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** -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/**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** -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** -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 - -**report\-group\-name\-or\-arn** -Optional sequence\. Specifies the report group that the reports are sent to\. A project can have a maximum of five report groups\. Specify the ARN of an existing report group, or the name of a new report group\. If you specify a name, CodeBuild creates a report group using your project name and the name you specify in the format `-`\. For more information, see [Report group naming](test-report-group-naming.md)\. - -reports//**files** -Required sequence\. Represents the locations that contain the raw data of test results generated by the report\. Contains a sequence of scalars, with each scalar representing a separate location where CodeBuild can find test files, relative to the original build location or, if set, the `base-directory`\. Locations can include the following: -+ A single file \(for example, `my-test-report-file.json`\)\. -+ A single file in a subdirectory \(for example, `my-subdirectory/my-test-report-file.json` or `my-parent-subdirectory/my-subdirectory/my-test-report-file.json`\)\. -+ `'**/*'` represents all files recursively\. -+ `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. -+ `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. - -reports//**file\-format** -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\. - -reports//**discard\-paths** -Optional\. Specifies if the report file directories are flattened in the output\. If this is not specified, or contains `no`, report files are output with their directory structure intact\. If this contains `yes`, all of the test files are placed in the same output directory\. For example, if a path to a test result is `com/myapp/mytests/TestResult.xml`, specifying `yes` will place this file in `/TestResult.xml`\. - -### artifacts - -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`\)\. -+ A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. -+ `'**/*'` represents all files recursively\. -+ `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. -+ `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. -When you specify build output artifact locations, CodeBuild can locate the original build location in the build environment\. You do not have to prepend your build artifact output locations with the path to the original build location or specify `./` or similar\. If you want to know the path to this location, you can run a command such as `echo $CODEBUILD_SRC_DIR` during a build\. The location for each build environment might be slightly different\. - -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 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\. - - ``` - 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 -phases: - build: - commands: - - rspec HelloWorld_spec.rb -artifacts: - files: - - '**/*' - name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts -``` - -artifacts/**discard\-paths** -Optional\. Specifies if the build artifact directories are flattened in the output\. If this is not specified, or contains `no`, build artifacts are output with their directory structure intact\. If this contains `yes`, all of the build artifacts are placed in the same output directory\. For example, if a path to a file in the build output artifact is `com/mycompany/app/HelloWorld.java`, specifying `yes` will place this file in `/HelloWorld.java`\. - -artifacts/**base\-directory** -Optional mapping\. Represents one or more top\-level directories, relative to the original build location, that CodeBuild uses to determine which files and subdirectories to include in the build output artifact\. Valid values include: -+ A single top\-level directory \(for example, `my-directory`\)\. -+ `'my-directory*'` represents all top\-level directories with names starting with `my-directory`\. -Matching top\-level directories are not included in the build output artifact, only their files and subdirectories\. -You can use `files` and `discard-paths` to further restrict which files and subdirectories are included\. For example, for the following directory structure: - -``` -. -├── 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-file-3.txt' - base-directory: my-build-2 -``` -The following subdirectory and file would be included in the build output artifact: - -``` -. -└── my-subdirectory - └── my-file-3.txt -``` -While for the following `artifacts` sequence: - -``` -artifacts: - files: - - '**/*' - base-directory: 'my-build*' - discard-paths: yes -``` -The following files would be included in the build output artifact: - -``` -. -├── 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\. -For example, if your project has the following structure: - -``` -{ - "name": "sample-project", - "secondaryArtifacts": [ - { - "type": "S3", - "location": "output-bucket1", - "artifactIdentifier": "artifact1", - "name": "secondary-artifact-name-1" - }, - { - "type": "S3", - "location": "output-bucket2", - "artifactIdentifier": "artifact2", - "name": "secondary-artifact-name-2" - } - ] -} -``` -Then your buildspec looks like the following: - -``` -version: 0.2 - -phases: -build: - commands: - - echo Building... -artifacts: - files: - - '**/*' - secondary-artifacts: - artifact1: - files: - - directory/file1 - name: secondary-artifact-name-1 - artifact2: - files: - - directory/file2 - name: secondary-artifact-name-2 -``` - -### cache - -Optional sequence\. Represents information about where CodeBuild can prepare the files for uploading cache to an S3 cache bucket\. This sequence is not required if the cache type of the project is `No Cache`\. - -cache/**paths** -Required sequence\. Represents the locations of the cache\. 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`\)\. -+ A single file in a subdirectory \(for example, `my-subdirectory/my-file.jar` or `my-parent-subdirectory/my-subdirectory/my-file.jar`\)\. -+ `'**/*'` represents all files recursively\. -+ `my-subdirectory/*` represents all files in a subdirectory named *my\-subdirectory*\. -+ `my-subdirectory/**/*` represents all files recursively starting from a subdirectory named *my\-subdirectory*\. - -**Important** -Because a buildspec declaration must be valid YAML, the spacing in a buildspec declaration is important\. If the number of spaces in your buildspec declaration is invalid, builds might fail immediately\. You can use a YAML validator to test whether your buildspec declarations are valid YAML\. -If you use the AWS CLI, or the AWS SDKs to declare a buildspec when you create or update a build project, the buildspec must be a single string expressed in YAML format, along with required whitespace and newline escape characters\. There is an example in the next section\. -If you use the CodeBuild or AWS CodePipeline consoles instead of a buildspec\.yml file, you can insert commands for the `build` phase only\. Instead of using the preceding syntax, you list, in a single line, all of the commands that you want to run during the build phase\. For multiple commands, separate each command by `&&` \(for example, `mvn test && mvn package`\)\. -You can use the CodeBuild or CodePipeline consoles instead of a buildspec\.yml file to specify the locations of the build output artifacts in the build environment\. Instead of using the preceding syntax, you list, in a single line, all of the locations\. For multiple locations, separate each location with a comma \(for example, `buildspec.yml, target/my-app.jar`\)\. - -## Buildspec example - -Here is an example of a buildspec\.yml file\. - -``` -version: 0.2 - -env: - variables: - JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" - parameter-store: - LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword - -phases: - install: - commands: - - echo Entered the install phase... - - apt-get update -y - - apt-get install -y maven - finally: - - echo This always runs even if the update or install command fails - pre_build: - commands: - - echo Entered the pre_build phase... - - docker login -u User -p $LOGIN_PASSWORD - finally: - - echo This always runs even if the login command fails - build: - commands: - - echo Entered the build phase... - - echo Build started on `date` - - mvn install - finally: - - echo This always runs even if the install command fails - post_build: - commands: - - echo Entered the post_build phase... - - echo Build completed on `date` - -reports: - arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: - files: - - "**/*" - base-directory: 'target/tests/reports' - discard-paths: no - reportGroupCucumberJson: - files: - - 'cucumber/target/cucumber-tests.xml' - discard-paths: yes - file-format: CUCUMBERJSON # default is JUNITXML -artifacts: - files: - - target/messageUtil-1.0.jar - discard-paths: yes - secondary-artifacts: - artifact1: - files: - - target/artifact-1.0.jar - discard-paths: yes - artifact2: - files: - - target/artifact-2.0.jar - discard-paths: yes -cache: - paths: - - '/root/.m2/**/*' -``` - -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/**/*'" -``` - -Here is an example of the commands in the `build` phase, for use with the CodeBuild or CodePipeline consoles\. - -``` -echo Build started on `date` && mvn install -``` - -In these examples: -+ A custom environment variable, in plain text, with the key of `JAVA_HOME` and the value of `/usr/lib/jvm/java-8-openjdk-amd64`, is set\. -+ A custom environment variable named `dockerLoginPassword` you stored in Amazon EC2 Systems Manager Parameter Store is referenced later in build commands by using the key `LOGIN_PASSWORD`\. -+ You cannot change these build phase names\. The commands that are run in this example are `apt-get update -y` and `apt-get install -y maven` \(to install Apache Maven\), `mvn install` \(to compile, test, and package the source code into a build output artifact and to install the build output artifact in its internal repository\), `docker login` \(to sign in to Docker with the password that corresponds to the value of the custom environment variable `dockerLoginPassword` you set in Amazon EC2 Systems Manager Parameter Store\), and several `echo` commands\. The `echo` commands are included here to show how CodeBuild runs commands and the order in which it runs them\. -+ `files` represents the files to upload to the build output location\. In this example, CodeBuild uploads the single file `messageUtil-1.0.jar`\. The `messageUtil-1.0.jar` file can be found in the relative directory named `target` in the build environment\. Because `discard-paths: yes` is specified, `messageUtil-1.0.jar` is uploaded directly \(and not to an intermediate `target` directory\)\. The file name `messageUtil-1.0.jar` and the relative directory name of `target` is based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own scenarios, these file names and directories will be different\. -+ `reports` represents two report groups that generate reports during the build: - + `arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1` specifies the ARN of a report group\. Test results generated by the test framework are in the `target/tests/reports` directory\. The file format is `JunitXml` and the path is not removed from the files that contain test results\. - + `reportGroupCucumberJson` specifies a new report group\. If the name of the project is `my-project`, a report group with the name `my-project-reportGroupCucumberJson` is created when a build is run\. Test results generated by the test framework are in `cucumber/target/cucumber-tests.xml`\. The test file format is `CucumberJson` and the path is removed from the files that contain test results\. - -## Buildspec versions - -The following table lists the buildspec versions and the changes between versions\. - - -| 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\. | \ No newline at end of file diff --git a/doc_source/builds-projects-and-builds.md b/doc_source/builds-projects-and-builds.md deleted file mode 100644 index 1fe8386..0000000 --- a/doc_source/builds-projects-and-builds.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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\. - -**Topics** -+ [Working with build projects](working-with-build-projects.md) -+ [Working with builds in AWS CodeBuild](builds-working.md) \ No newline at end of file diff --git a/doc_source/builds-working.md b/doc_source/builds-working.md deleted file mode 100644 index a3d3545..0000000 --- a/doc_source/builds-working.md +++ /dev/null @@ -1,28 +0,0 @@ -# Working with builds in AWS CodeBuild - -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 [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\. - -You can perform these tasks when working with builds: - -**Topics** -+ [Run a build in AWS CodeBuild](run-build.md) -+ [View build details in AWS CodeBuild](view-build-details.md) -+ [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 deleted file mode 100644 index 580008f..0000000 --- a/doc_source/change-project-cli.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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 deleted file mode 100644 index 67d6018..0000000 --- a/doc_source/change-project-console.md +++ /dev/null @@ -1,364 +0,0 @@ -# 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 deleted file mode 100644 index 88d0cb4..0000000 --- a/doc_source/change-project-sdks.md +++ /dev/null @@ -1,3 +0,0 @@ -# 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 deleted file mode 100644 index a9fb3ec..0000000 --- a/doc_source/change-project.md +++ /dev/null @@ -1,10 +0,0 @@ -# Change a build project's settings in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to change a build project's settings\. - -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.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 deleted file mode 100644 index 6ef2c44..0000000 --- a/doc_source/cloudformation-vpc-template.md +++ /dev/null @@ -1,245 +0,0 @@ -# AWS CloudFormation VPC template - -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\. 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 - across two Availability Zones. It deploys an internet gateway, with a default - route on the public subnets. It deploys a pair of NAT gateways (one in each AZ), - and default routes for them in the private subnets. - -Parameters: - EnvironmentName: - Description: An environment name that is prefixed to resource names - Type: String - - VpcCIDR: - Description: Please enter the IP range (CIDR notation) for this VPC - Type: String - Default: 10.192.0.0/16 - - PublicSubnet1CIDR: - Description: Please enter the IP range (CIDR notation) for the public subnet in the first Availability Zone - Type: String - Default: 10.192.10.0/24 - - PublicSubnet2CIDR: - Description: Please enter the IP range (CIDR notation) for the public subnet in the second Availability Zone - Type: String - Default: 10.192.11.0/24 - - PrivateSubnet1CIDR: - Description: Please enter the IP range (CIDR notation) for the private subnet in the first Availability Zone - Type: String - Default: 10.192.20.0/24 - - PrivateSubnet2CIDR: - Description: Please enter the IP range (CIDR notation) for the private subnet in the second Availability Zone - Type: String - Default: 10.192.21.0/24 - -Resources: - VPC: - Type: AWS::EC2::VPC - Properties: - CidrBlock: !Ref VpcCIDR - EnableDnsSupport: true - EnableDnsHostnames: true - Tags: - - Key: Name - Value: !Ref EnvironmentName - - InternetGateway: - Type: AWS::EC2::InternetGateway - Properties: - Tags: - - Key: Name - Value: !Ref EnvironmentName - - InternetGatewayAttachment: - Type: AWS::EC2::VPCGatewayAttachment - Properties: - InternetGatewayId: !Ref InternetGateway - VpcId: !Ref VPC - - PublicSubnet1: - Type: AWS::EC2::Subnet - Properties: - VpcId: !Ref VPC - AvailabilityZone: !Select [ 0, !GetAZs '' ] - CidrBlock: !Ref PublicSubnet1CIDR - MapPublicIpOnLaunch: true - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Public Subnet (AZ1) - - PublicSubnet2: - Type: AWS::EC2::Subnet - Properties: - VpcId: !Ref VPC - AvailabilityZone: !Select [ 1, !GetAZs '' ] - CidrBlock: !Ref PublicSubnet2CIDR - MapPublicIpOnLaunch: true - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Public Subnet (AZ2) - - PrivateSubnet1: - Type: AWS::EC2::Subnet - Properties: - VpcId: !Ref VPC - AvailabilityZone: !Select [ 0, !GetAZs '' ] - CidrBlock: !Ref PrivateSubnet1CIDR - MapPublicIpOnLaunch: false - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Private Subnet (AZ1) - - PrivateSubnet2: - Type: AWS::EC2::Subnet - Properties: - VpcId: !Ref VPC - AvailabilityZone: !Select [ 1, !GetAZs '' ] - CidrBlock: !Ref PrivateSubnet2CIDR - MapPublicIpOnLaunch: false - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Private Subnet (AZ2) - - NatGateway1EIP: - Type: AWS::EC2::EIP - DependsOn: InternetGatewayAttachment - Properties: - Domain: vpc - - NatGateway2EIP: - Type: AWS::EC2::EIP - DependsOn: InternetGatewayAttachment - Properties: - Domain: vpc - - NatGateway1: - Type: AWS::EC2::NatGateway - Properties: - AllocationId: !GetAtt NatGateway1EIP.AllocationId - SubnetId: !Ref PublicSubnet1 - - NatGateway2: - Type: AWS::EC2::NatGateway - Properties: - AllocationId: !GetAtt NatGateway2EIP.AllocationId - SubnetId: !Ref PublicSubnet2 - - PublicRouteTable: - Type: AWS::EC2::RouteTable - Properties: - VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Public Routes - - DefaultPublicRoute: - Type: AWS::EC2::Route - DependsOn: InternetGatewayAttachment - Properties: - RouteTableId: !Ref PublicRouteTable - DestinationCidrBlock: 0.0.0.0/0 - GatewayId: !Ref InternetGateway - - PublicSubnet1RouteTableAssociation: - Type: AWS::EC2::SubnetRouteTableAssociation - Properties: - RouteTableId: !Ref PublicRouteTable - SubnetId: !Ref PublicSubnet1 - - PublicSubnet2RouteTableAssociation: - Type: AWS::EC2::SubnetRouteTableAssociation - Properties: - RouteTableId: !Ref PublicRouteTable - SubnetId: !Ref PublicSubnet2 - - - PrivateRouteTable1: - Type: AWS::EC2::RouteTable - Properties: - VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Private Routes (AZ1) - - DefaultPrivateRoute1: - Type: AWS::EC2::Route - Properties: - RouteTableId: !Ref PrivateRouteTable1 - DestinationCidrBlock: 0.0.0.0/0 - NatGatewayId: !Ref NatGateway1 - - PrivateSubnet1RouteTableAssociation: - Type: AWS::EC2::SubnetRouteTableAssociation - Properties: - RouteTableId: !Ref PrivateRouteTable1 - SubnetId: !Ref PrivateSubnet1 - - PrivateRouteTable2: - Type: AWS::EC2::RouteTable - Properties: - VpcId: !Ref VPC - Tags: - - Key: Name - Value: !Sub ${EnvironmentName} Private Routes (AZ2) - - DefaultPrivateRoute2: - Type: AWS::EC2::Route - Properties: - RouteTableId: !Ref PrivateRouteTable2 - DestinationCidrBlock: 0.0.0.0/0 - NatGatewayId: !Ref NatGateway2 - - PrivateSubnet2RouteTableAssociation: - Type: AWS::EC2::SubnetRouteTableAssociation - Properties: - RouteTableId: !Ref PrivateRouteTable2 - SubnetId: !Ref PrivateSubnet2 - - NoIngressSecurityGroup: - Type: AWS::EC2::SecurityGroup - Properties: - GroupName: "no-ingress-sg" - GroupDescription: "Security group with no ingress rule" - VpcId: !Ref VPC - -Outputs: - VPC: - Description: A reference to the created VPC - Value: !Ref VPC - - PublicSubnets: - Description: A list of the public subnets - Value: !Join [ ",", [ !Ref PublicSubnet1, !Ref PublicSubnet2 ]] - - PrivateSubnets: - Description: A list of the private subnets - Value: !Join [ ",", [ !Ref PrivateSubnet1, !Ref PrivateSubnet2 ]] - - PublicSubnet1: - Description: A reference to the public subnet in the 1st Availability Zone - Value: !Ref PublicSubnet1 - - PublicSubnet2: - Description: A reference to the public subnet in the 2nd Availability Zone - Value: !Ref PublicSubnet2 - - PrivateSubnet1: - Description: A reference to the private subnet in the 1st Availability Zone - Value: !Ref PrivateSubnet1 - - PrivateSubnet2: - Description: A reference to the private subnet in the 2nd Availability Zone - Value: !Ref PrivateSubnet2 - - NoIngressSecurityGroup: - Description: Security group with no ingress rule - Value: !Ref NoIngressSecurityGroup -``` \ No newline at end of file diff --git a/doc_source/cloudtrail.md b/doc_source/cloudtrail.md deleted file mode 100644 index 838eb4e..0000000 --- a/doc_source/cloudtrail.md +++ /dev/null @@ -1,103 +0,0 @@ -# Logging AWS CodeBuild API calls with AWS CloudTrail - -AWS CodeBuild is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in CodeBuild\. CloudTrail captures all API calls for CodeBuild as events, including calls from the CodeBuild console and from code calls to the CodeBuild APIs\. If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including events for CodeBuild\. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**\. Using the information collected by CloudTrail, you can determine the request that was made to CodeBuild, the IP address from which the request was made, who made the request, when it was made, and additional details\. - -To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)\. - -## AWS CodeBuild information in CloudTrail - -CloudTrail is enabled on your AWS account when you create the account\. When activity occurs in CodeBuild, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**\. You can view, search, and download recent events in your AWS account\. For more information, see [Viewing events with CloudTrail event history](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *AWS CloudTrail User Guide*\. - -For an ongoing record of events in your AWS account, including events for CodeBuild, create a trail\. A trail enables CloudTrail to deliver log files to an S3 bucket\. By default, when you create a trail in the console, the trail applies to all regions\. The trail logs events from all regions in the AWS partition and delivers the log files to the S3 bucket that you specify\. You can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs\. For more information, see: -+ [Overview for creating a trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) -+ [CloudTrail supported services and integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) -+ [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html) -+ [Receiving CloudTrail log files from multiple regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) - -All CodeBuild actions are logged by CloudTrail and are documented in the [CodeBuild API Reference](https://docs.aws.amazon.com/codebuild/latest/APIReference/)\. For example, calls to the `CreateProject` \(in the AWS CLI, `create-project`\), `StartBuild` \(in the AWS CLI, `start-project`\), and `UpdateProject` \(in the AWS CLI, `update-project`\) actions generate entries in the CloudTrail log files\. - -Every event or log entry contains information about who generated the request\. The identity information helps you determine the following: -+ Whether the request was made with root or IAM user credentials\. -+ Whether the request was made with temporary security credentials for a role or federated user\. -+ Whether the request was made by another AWS service\. - -For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)in the *AWS CloudTrail User Guide*\. - -## Understanding AWS CodeBuild log file entries - -A trail is a configuration that enables delivery of events as log files to an S3 bucket that you specify\. CloudTrail log files contain one or more log entries\. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on\. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order\. - -**Note** - 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 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)\. - -The following example shows a CloudTrail log entry that demonstrates creating a build project in CodeBuild\. - -``` -{ - "eventVersion": "1.05", - "userIdentity": { - "type": "FederatedUser", - "principalId": "account-ID:user-name", - "arn": "arn:aws:sts::account-ID:federated-user/user-name", - "accountId": "account-ID", - "accessKeyId": "access-key-ID", - "sessionContext": { - "attributes": { - "mfaAuthenticated": "false", - "creationDate": "2016-09-06T17:59:10Z" - }, - "sessionIssuer": { - "type": "IAMUser", - "principalId": "access-key-ID", - "arn": "arn:aws:iam::account-ID:user/user-name", - "accountId": "account-ID", - "userName": "user-name" - } - } - }, - "eventTime": "2016-09-06T17:59:11Z", - "eventSource": "codebuild.amazonaws.com", - "eventName": "CreateProject", - "awsRegion": "region-ID", - "sourceIPAddress": "127.0.0.1", - "userAgent": "user-agent", - "requestParameters": { - "awsActId": "account-ID" - }, - "responseElements": { - "project": { - "environment": { - "image": "image-ID", - "computeType": "BUILD_GENERAL1_SMALL", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "name": "codebuild-demo-project", - "description": "This is my demo project", - "arn": "arn:aws:codebuild:region-ID:account-ID:project/codebuild-demo-project:project-ID", - "encryptionKey": "arn:aws:kms:region-ID:key-ID", - "timeoutInMinutes": 10, - "artifacts": { - "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket", - "type": "S3", - "packaging": "ZIP", - "outputName": "MyOutputArtifact.zip" - }, - "serviceRole": "arn:aws:iam::account-ID:role/CodeBuildServiceRole", - "lastModified": "Sep 6, 2016 10:59:11 AM", - "source": { - "type": "GITHUB", - "location": "https://github.com/my-repo.git" - }, - "created": "Sep 6, 2016 10:59:11 AM" - } - }, - "requestID": "9d32b228-745b-11e6-98bb-23b67EXAMPLE", - "eventID": "581f7dd1-8d2e-40b0-aeee-0dbf7EXAMPLE", - "eventType": "AwsApiCall", - "recipientAccountId": "account-ID" -} -``` \ No newline at end of file diff --git a/doc_source/cmd-ref.md b/doc_source/cmd-ref.md deleted file mode 100644 index 245df2f..0000000 --- a/doc_source/cmd-ref.md +++ /dev/null @@ -1,35 +0,0 @@ -# Command line reference for AWS CodeBuild - -The AWS CLI provides commands for automating AWS CodeBuild\. Use the information in this topic as a supplement to the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com/cli/latest/userguide/) and the [AWS CLI Reference for AWS CodeBuild](https://docs.aws.amazon.com/cli/latest/reference/codebuild/)\. - -Not what you're looking for? If you want to use the AWS SDKs to call CodeBuild, see the [AWS SDKs and tools reference](sdk-ref.md)\. - -To use the information in this topic, you should have already installed the AWS CLI and configured it for use with CodeBuild, as described in [Install and configure the AWS CLI](setting-up.md#setting-up-cli)\. - - To use the AWS CLI to specify the endpoint for CodeBuild, see [Specify the AWS CodeBuild endpoint \(AWS CLI\)](endpoint-specify.md#endpoint-specify-cli)\. - -Run this command to get a list of CodeBuild commands\. - -``` -aws codebuild help -``` - -Run this command to get information about a CodeBuild command, where *command\-name* is the name of the command\. - -``` -aws codebuild command-name help -``` - -CodeBuild commands include: -+ `batch-delete-builds`: Deletes one or more builds in CodeBuild\. For more information, see [Delete builds \(AWS CLI\)](delete-builds.md#delete-builds-cli)\. -+ `batch-get-builds`: Gets information about multiple builds in CodeBuild\. For more information, see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. -+ `batch-get-projects`: Gets information about one or more specified build projects\. For more information, see [View a build project's details \(AWS CLI\)](view-project-details.md#view-project-details-cli)\. -+ `create-project`: Creates a build project\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. -+ `delete-project`: Deletes a build project\. For more information, see [Delete a build project \(AWS CLI\)](delete-project.md#delete-project-cli)\. -+ `list-builds`: Lists Amazon Resource Names \(ARNs\) for builds in CodeBuild\. For more information, see [View a list of build IDs \(AWS CLI\)](view-build-list.md#view-build-list-cli)\. -+ `list-builds-for-project`: Gets a list of build IDs that are associated with a specified build project\. For more information, see [View a list of build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli)\. -+ `list-curated-environment-images`: Gets a list of Docker images managed by CodeBuild that you can use for your builds\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. -+ `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-cli.md)\. \ No newline at end of file diff --git a/doc_source/code-coverage-report.md b/doc_source/code-coverage-report.md deleted file mode 100644 index e304e18..0000000 --- a/doc_source/code-coverage-report.md +++ /dev/null @@ -1,51 +0,0 @@ -# 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/codebuild-compliance-validation.md b/doc_source/codebuild-compliance-validation.md deleted file mode 100644 index b5a01f1..0000000 --- a/doc_source/codebuild-compliance-validation.md +++ /dev/null @@ -1,14 +0,0 @@ -# Compliance validation for AWS CodeBuild - -Third\-party auditors assess the security and compliance of AWS CodeBuild as part of multiple AWS compliance programs\. These include SOC, PCI, FedRAMP, HIPAA, and others\. - -For a list of AWS services in scope of specific compliance programs, see [AWS services in scope by compliance program](https://aws.amazon.com/compliance/services-in-scope/)\. For general information, see [AWS compliance programs](https://aws.amazon.com/compliance/programs/)\. - -You can download third\-party audit reports using AWS Artifact\. For more information, see [Downloading reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html)\. - -Your compliance responsibility when using CodeBuild is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations\. If your use of CodeBuild is subject to compliance with standards such as HIPAA, PCI, or FedRAMP, AWS provides resources to help: -+ [Security and compliance quick start guides](https://aws.amazon.com/quickstart/?awsf.quickstart-homepage-filter=categories%23security-identity-compliance) – These deployment guides discuss architectural considerations and provide steps for deploying security\- and compliance\-focused baseline environments on AWS\. -+ [Architecting for HIPAA Security and Compliance Whitepaper ](https://d0.awsstatic.com/whitepapers/compliance/AWS_HIPAA_Compliance_Whitepaper.pdf) – This whitepaper describes how companies can use AWS to create HIPAA\-compliant applications\. -+ [AWS compliance resources](https://aws.amazon.com/compliance/resources/) – This collection of workbooks and guides might apply to your industry and location\. -+ [AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) – This AWS service assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations\. -+ [AWS Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) – This AWS service provides a comprehensive view of your security state within AWS that helps you check your compliance with security industry standards and best practices\. \ No newline at end of file diff --git a/doc_source/codebuild-disaster-recovery-resiliency.md b/doc_source/codebuild-disaster-recovery-resiliency.md deleted file mode 100644 index 267921f..0000000 --- a/doc_source/codebuild-disaster-recovery-resiliency.md +++ /dev/null @@ -1,5 +0,0 @@ -# Resilience in AWS CodeBuild - -The AWS global infrastructure is built around AWS Regions and Availability Zones\. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low\-latency, high\-throughput, and highly redundant networking\. With Availability Zones, you can design and operate applications and databases that automatically fail over between Availability Zones without interruption\. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures\. - -For more information about AWS Regions and Availability Zones, see [AWS global infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/)\. \ No newline at end of file diff --git a/doc_source/codecov-integration.md b/doc_source/codecov-integration.md deleted file mode 100644 index aaa06ee..0000000 --- a/doc_source/codecov-integration.md +++ /dev/null @@ -1,108 +0,0 @@ -# Use AWS CodeBuild with Codecov - -Codecov is a tool that measures the test coverage of your code\. Codecov identifies which methods and statements in your code are not tested\. Use the results to determine where to write tests to improve the quality of your code\. Codecov is available for three of the source repositories supported by CodeBuild: GitHub, GitHub Enterprise Server, and Bitbucket\. If your build project uses GitHub Enterprise Server, you must use Codecov Enterprise\. - - When you run a build of a CodeBuild project that is integrated with Codecov, Codecov reports that analyzes code in your repository are uploaded to Codecov\. The build logs include a link to the reports\. This sample shows you how to integrate a Python and a Java build project with Codecov\. For a list of languages supported by Codecov, see [Codecov supported languages](https://docs.codecov.io/docs/supported-languages) on the Codecov website\. - -## Integrate Codecov into a build project - -**To integrate Codecov with your build project** - -1. Go to [https://codecov\.io/signup](https://codecov.io/signup) and sign up for a GitHub or Bitbucket source repository\. If you use GitHub Enterprise, see [Codecov Enterprise](https://codecov.io/enterprise) on the Codecov website\. - -1. In Codecov, add the repository for which you want coverage\. - -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-console.md)\. - -1. Create a text file named `my_script.sh` in your repository\. Enter the following into the file: - - ``` - #/bin/bash - bash <(curl -s https://codecov.io/bash) -t $CODECOV_TOKEN - ``` - -1. Choose the **Python** or **Java** tab, as appropriate for your build project uses, and follow these steps\. - ------- -#### [ Java ] - - 1. Add the following JaCoCo plugin to `pom.xml` in your repository\. - - ``` - - - - org.jacoco - jacoco-maven-plugin - 0.8.2 - - - - prepare-agent - - - - report - test - - report - - - - - - - ``` - - 1. Enter the following commands in your buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - - ``` - build: - - mvn test -f pom.xml -fn - postbuild: - - echo 'Connect to CodeCov' - - bash my_script.sh - ``` - ------- -#### [ Python ] - - Enter the following commands in your buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - - ``` - build: - - pip install coverage - - coverage run -m unittest discover - postbuild: - - echo 'Connect to CodeCov' - - bash my_script.sh - ``` - ------- - -1. Run a build of your build project\. A link to Codecov reports generated for your project appears in your build logs\. Use the link to view the Codecov reports\. For more information, see [Run a build in AWS CodeBuild](run-build.md) and [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md)\. Codecov information in the build logs looks like the following: - - ``` - [Container] 2020/03/09 16:31:04 Running command bash my_script.sh - - _____ _ - / ____| | | - | | ___ __| | ___ ___ _____ __ - | | / _ \ / _` |/ _ \/ __/ _ \ \ / / - | |___| (_) | (_| | __/ (_| (_) \ V / - \_____\___/ \__,_|\___|\___\___/ \_/ - Bash-20200303-bc4d7e6 - - ·[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 - - [Container] 2020/03/09 16:31:07 Phase complete: POST_BUILD State: SUCCEEDED - ``` - - The reports look like the following: -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codecov-report.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 diff --git a/doc_source/concepts.md b/doc_source/concepts.md deleted file mode 100644 index 5596971..0000000 --- a/doc_source/concepts.md +++ /dev/null @@ -1,39 +0,0 @@ -# AWS CodeBuild concepts - -The following concepts are important for understanding how CodeBuild works\. - -**Topics** -+ [How CodeBuild works](#concepts-how-it-works) -+ [Next steps](#concepts-next-steps) - -## 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) - -1. CodeBuild uses the build project to create the build environment\. - -1. CodeBuild downloads the source code into the build environment and then uses the build specification \(buildspec\), as defined in the build project or included directly in the source code\. A *buildspec* is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build\. For more information, see the [Buildspec reference](build-spec-ref.md)\. - -1. If there is any build output, the build environment uploads its output to an S3 bucket\. The build environment can also perform tasks that you specify in the buildspec \(for example, sending build notifications to an Amazon SNS topic\)\. For an example, see [Build notifications sample](sample-build-notifications.md)\. - -1. While the build is running, the build environment sends information to CodeBuild and Amazon CloudWatch Logs\. - -1. While the build is running, you can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to get summarized build information from CodeBuild and detailed build information from Amazon CloudWatch Logs\. If you use AWS CodePipeline to run builds, you can get limited build information from CodePipeline\. - -## Next steps - -Now that you know more about AWS CodeBuild, we recommend these next steps: - -1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting started using the console](getting-started.md)\. - -1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a build](planning.md)\. \ No newline at end of file diff --git a/doc_source/console-resources.md b/doc_source/console-resources.md deleted file mode 100644 index 89a8fb8..0000000 --- a/doc_source/console-resources.md +++ /dev/null @@ -1,15 +0,0 @@ -# Viewing resources in the console - -The AWS CodeBuild console requires the `ListRepositories` permission to display a list of repositories for your AWS account in the AWS Region where you are signed in\. The console also includes a **Go to resource** function to quickly perform a case insensitive search for resources\. This search is performed in your AWS account in the AWS Region where you are signed in\. The following resources are displayed across the following services: -+ AWS CodeBuild: Build projects -+ AWS CodeCommit: Repositories -+ AWS CodeDeploy: Applications -+ AWS CodePipeline: Pipelines - -To perform this search across resources in all services, you must have the following permissions: -+ CodeBuild: `ListProjects` -+ CodeCommit: `ListRepositories` -+ CodeDeploy: `ListApplications` -+ CodePipeline: `ListPipelines` - -Results are not returned for a service's resources if you do not have permissions for that service\. Even if you have permissions for viewing resources, some resources are not returned if there is an explicit `Deny` to view those resources\. \ No newline at end of file diff --git a/doc_source/create-project-cli.md b/doc_source/create-project-cli.md deleted file mode 100644 index 3f0dec7..0000000 --- a/doc_source/create-project-cli.md +++ /dev/null @@ -1,513 +0,0 @@ -# Create a build project \(AWS CLI\) - -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/`\. -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 `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\. - -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=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)\. - -If your source code is stored in a GitHub repository, and you want CodeBuild to rebuild the source code every time a code change is pushed to the repository, see [Start running builds automatically \(AWS CLI\)](run-build-cli-auto-start.md)\. \ No newline at end of file diff --git a/doc_source/create-project-cloud-formation.md b/doc_source/create-project-cloud-formation.md deleted file mode 100644 index 44ef2eb..0000000 --- a/doc_source/create-project-cloud-formation.md +++ /dev/null @@ -1,3 +0,0 @@ -# Create a build project \(AWS CloudFormation\) - -For information about using AWS CodeBuild with AWS CloudFormation, see [the AWS CloudFormation template for CodeBuild](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-project.html) in the *AWS CloudFormation User Guide*\. \ No newline at end of file diff --git a/doc_source/create-project-console.md b/doc_source/create-project-console.md deleted file mode 100644 index 65c48e2..0000000 --- a/doc_source/create-project-console.md +++ /dev/null @@ -1,324 +0,0 @@ -# Create a build project \(console\) - -Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - - 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**\. - -Choose **Create build project**\. - -Fill in the following sections\. Once complete, choose **Create build project** at the bottom of the page\. - -**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) - -## Project configuration - -**Project name** -Enter a name for this build project\. Build project names must be unique across each AWS account\. - -**Description** -Enter an optional description of the build project to help other users understand what this project is used for\. - -**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\. - -**Enable concurrent build limit** -\(Optional\) 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\. - -**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\. - ------- -#### [ 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 - -**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\. - -**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=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 - -**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\. -**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 - -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-sdks.md b/doc_source/create-project-sdks.md deleted file mode 100644 index 7154f72..0000000 --- a/doc_source/create-project-sdks.md +++ /dev/null @@ -1,3 +0,0 @@ -# Create a build project \(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/create-project.md b/doc_source/create-project.md deleted file mode 100644 index c5195a1..0000000 --- a/doc_source/create-project.md +++ /dev/null @@ -1,14 +0,0 @@ -# Create a build project in AWS CodeBuild - -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) \ No newline at end of file diff --git a/doc_source/data-protection.md b/doc_source/data-protection.md deleted file mode 100644 index 836f7b5..0000000 --- a/doc_source/data-protection.md +++ /dev/null @@ -1,25 +0,0 @@ -# Data protection in AWS CodeBuild - -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\)\. 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 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 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 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 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*\. - -**Topics** -+ [Data encryption](security-encryption.md) -+ [Key management](security-key-management.md) -+ [Traffic privacy](security-traffic-privacy.md) \ No newline at end of file diff --git a/doc_source/delete-builds.md b/doc_source/delete-builds.md deleted file mode 100644 index 6666922..0000000 --- a/doc_source/delete-builds.md +++ /dev/null @@ -1,44 +0,0 @@ -# Delete builds in AWS CodeBuild - -You can use the AWS CLI or the AWS SDKs to delete builds in AWS CodeBuild\. - -## Delete builds \(AWS CLI\) - -Run the `batch-delete-builds` command: - -``` -aws codebuild batch-delete-builds --ids ids -``` - -In the preceding command, replace the following placeholder: -+ *ids*: Required string\. The IDs of the builds to delete\. To specify multiple builds, separate each build ID with a space\. 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 build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) - -If successful, a `buildsDeleted` array appears in the output, containing the Amazon Resource Name \(ARN\) of each build that was successfully deleted\. Information about builds that were not successfully deleted appears in output within a `buildsNotDeleted` array\. - -For example, if you run this command: - -``` -aws codebuild batch-delete-builds --ids my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX -``` - -Information similar to the following appears in the output: - -``` -{ - "buildsNotDeleted": [ - { - "id": "arn:aws:codebuild:us-west-2:123456789012:build/my-demo-build-project:f8b888d2-5e1e-4032-8645-b115195648EX", - "statusCode": "BUILD_IN_PROGRESS" - } - ], - "buildsDeleted": [ - "arn:aws:codebuild:us-west-2:123456789012:build/my-other-demo-build-project:a18bc6ee-e499-4887-b36a-8c90349c7eEX" - ] -} -``` - -## Delete builds \(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/delete-project.md b/doc_source/delete-project.md deleted file mode 100644 index dca3946..0000000 --- a/doc_source/delete-project.md +++ /dev/null @@ -1,42 +0,0 @@ -# Delete a build project in AWS CodeBuild - -You can use the CodeBuild console, AWS CLI, or AWS SDKs to delete a build project in CodeBuild\. If you delete a project, its builds are not deleted\. - -**Warning** -You cannot delete a project that has builds and a resource policy\. To delete a project with a resource policy and builds, you must first remove the resource policy and delete its builds\. - -**Topics** -+ [Delete a build project \(console\)](#delete-project-console) -+ [Delete a build project \(AWS CLI\)](#delete-project-cli) -+ [Delete a build project \(AWS SDKs\)](#delete-project-sdks) - -## Delete 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)\. - -1. In the navigation pane, choose **Build projects**\. - -1. Do one of the following: - + Choose the radio button next to the build project you want to delete, and then choose **Delete**\. - + Choose the link for the build project you want to delete, and then choose **Delete**\. -**Note** -By default, only the most recent 10 build projects are displayed\. To view more build projects, choose a different value for **Projects per page** or use the back and forward arrows for viewing projects\. - -## Delete a build project \(AWS CLI\) - -1. Run the `delete-project` command: - - ``` - aws codebuild delete-project --name name - ``` - - Replace the following placeholder: - + *name*: Required string\. The name of the build project to delete\. To get a list of available build projects, run the `list-projects` command\. For more information, see [View a list of build project names \(AWS CLI\)](view-project-list.md#view-project-list-cli)\. - -1. If successful, no data and no errors appear in the output\. - -For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. - -## Delete 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/endpoint-specify.md b/doc_source/endpoint-specify.md deleted file mode 100644 index 227d36b..0000000 --- a/doc_source/endpoint-specify.md +++ /dev/null @@ -1,82 +0,0 @@ -# Specify the AWS CodeBuild endpoint - - You can use the AWS Command Line Interface \(AWS CLI\) or one of the AWS SDKs to specify the endpoint used by AWS CodeBuild\. There is an endpoint for each region in which CodeBuild is available\. In addition to a regional endpoint, four regions also have a Federal Information Processing Standards \(FIPS\) endpoint\. For more information about FIPS endpoints, see [FIPS 140\-2 overview](https://aws.amazon.com/compliance/fips/)\. - - Specifying an endpoint is optional\. If you don't explicitly tell CodeBuild which endpoint to use, the service uses the endpoint associated with the region your AWS account uses\. CodeBuild never defaults to a FIPS endpoint\. If you want to use a FIPS endpoint, you must associate CodeBuild with it using one of the following methods\. - -**Note** - You can use an alias or region name to specify an endpoint using an AWS SDK\. If you use the AWS CLI, then you must use the full endpoint name\. - - For endpoints that can be used with CodeBuild, see [CodeBuild regions and endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region)\. - -**Topics** -+ [Specify the AWS CodeBuild endpoint \(AWS CLI\)](#endpoint-specify-cli) -+ [Specify the AWS CodeBuild endpoint \(AWS SDK\)](#endpoint-specify-sdk) - -## Specify the AWS CodeBuild endpoint \(AWS CLI\) - - You can use the AWS CLI to specify the endpoint through which AWS CodeBuild is accessed by using the `--endpoint-url` argument in any CodeBuild command\. For example, run this command to get a list of project build names using the Federal Information Processing Standards \(FIPS\) endpoint in the US East \(N\. Virginia\) Region: - -``` -aws codebuild list-projects --endpoint-url https://codebuild-fips.us-east-1.amazonaws.com -``` - -Include the `https://` at the begining of the endpoint\. - - The `--endpoint-url` AWS CLI argument is available to all AWS services\. For more information about this and other AWS CLI arguments, see [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/)\. - -## Specify the AWS CodeBuild endpoint \(AWS SDK\) - - You can use an AWS SDK to specify the endpoint through which AWS CodeBuild is accessed\. Although this example uses the [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/), you can specify the endpoint with the other AWS SDKs\. - - Use the `withEndpointConfiguration` method when constructing the AWSCodeBuild client\. Here is format to use: - -``` -AWSCodeBuild awsCodeBuild = AWSCodeBuildClientBuilder.standard(). - withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("endpoint", "region")). - withCredentials(new AWSStaticCredentialsProvider(sessionCredentials)). - build(); -``` - - 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/latest/developer-guide/credentials.html)\. - - Do not include `https://` at the begining of the endpoint\. - - If you want to specify a non\-FIPS endpoint, you can use the region instead of the actual endpoint\. For example, to specify the endpoint in the US East \(N\. Virginia\) region, you can use `us-east-1` instead of the full endpoint name, `codebuild.us-east-1.amazonaws.com`\. - -If you want to specify a FIPS endpoint, you can use an alias to simplify your code\. Only FIPS endpoints have an alias\. Other endpoints must be specified using their region or full name\. - -The following table lists the alias for each of the four available FIPS endpoints: - - -**** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/endpoint-specify.html) - - To specify use of the FIPS endpoint in the US West \(Oregon\) region using an alias: - -``` -AWSCodeBuild awsCodeBuild = AWSCodeBuildClientBuilder.standard(). - withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("us-west-2-fips", "us-west-2")). - withCredentials(new AWSStaticCredentialsProvider(sessionCredentials)). - build(); -``` - - To specify use of the non\-FIPS endpoint in the US East \(N\. Virginia\) region: - -``` -AWSCodeBuild awsCodeBuild = AWSCodeBuildClientBuilder.standard(). - withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("us-east-1", "us-east-1")). - withCredentials(new AWSStaticCredentialsProvider(sessionCredentials)). - build(); -``` - - To specify use of the non\-FIPS endpoint in the Asia Pacific \(Mumbai\) region: - -``` -AWSCodeBuild awsCodeBuild = AWSCodeBuildClientBuilder.standard(). - withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration("ap-south-1", "ap-south-1")). - withCredentials(new AWSStaticCredentialsProvider(sessionCredentials)). - build(); -``` \ No newline at end of file diff --git a/doc_source/getting-started-build-log-console.md b/doc_source/getting-started-build-log-console.md deleted file mode 100644 index 7f81e96..0000000 --- a/doc_source/getting-started-build-log-console.md +++ /dev/null @@ -1,23 +0,0 @@ -# Step 8: View detailed build information - -\(Previous step: [Step 7: View summarized build information](getting-started-monitor-build-console.md)\) - -In this step, you view detailed information about your build in CloudWatch Logs\. - -**Note** - 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 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)\. - -**To view detailed build information** - -1. With the build details page still displayed from the previous step, the last 10,000 lines of the build log are displayed in **Build logs**\. To see the entire build log in CloudWatch Logs, choose the **View entire log** link\. - -1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. - -1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and pattern syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. - -## Next step - -[Step 9: Get the build output artifact](getting-started-output-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-clean-up-console.md b/doc_source/getting-started-clean-up-console.md deleted file mode 100644 index 673bc6e..0000000 --- a/doc_source/getting-started-clean-up-console.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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 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 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\. - -``` -{ - "Version": "2012-10-17", - "Id": "...", - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Effect": "Allow", - "Action": [ - "s3:DeleteBucket", - "s3:DeleteObject" - ], - "Resource": "*" - } - ### END ADDING STATEMENT HERE ### - ] -} -``` - -## Next step - -[Wrapping up](getting-started-next-steps-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-build-log.md b/doc_source/getting-started-cli-build-log.md deleted file mode 100644 index 6f8c691..0000000 --- a/doc_source/getting-started-cli-build-log.md +++ /dev/null @@ -1,76 +0,0 @@ -# Step 8: View detailed build information - -\(Previous step: [Step 7: View summarized build information](getting-started-cli-monitor-build.md)\) - -In this step, you view detailed information about your build in CloudWatch Logs\. - -**Note** - 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 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)\. - -**To view detailed build information** - -1. Use your web browser to go to the `deepLink` location that appeared in the output in the previous step \(for example, `https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE`\)\. - -1. In the CloudWatch Logs log stream, you can browse the log events\. By default, only the last set of log events is displayed\. To see earlier log events, scroll to the beginning of the list\. - -1. In this tutorial, most of the log events contain verbose information about CodeBuild downloading and installing build dependency files into its build environment, which you probably don't care about\. You can use the **Filter events** box to reduce the information displayed\. For example, if you enter `"[INFO]"` in **Filter events**, only those events that contain `[INFO]` are displayed\. For more information, see [Filter and pattern syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html) in the *Amazon CloudWatch User Guide*\. - -These portions of a CloudWatch Logs log stream pertain to this tutorial\. - -``` -... -[Container] 2016/04/15 17:49:42 Entering phase PRE_BUILD -[Container] 2016/04/15 17:49:42 Running command echo Entering pre_build phase... -[Container] 2016/04/15 17:49:42 Entering pre_build phase... -[Container] 2016/04/15 17:49:42 Phase complete: PRE_BUILD Success: true -[Container] 2016/04/15 17:49:42 Entering phase BUILD -[Container] 2016/04/15 17:49:42 Running command echo Entering build phase... -[Container] 2016/04/15 17:49:42 Entering build phase... -[Container] 2016/04/15 17:49:42 Running command mvn install -[Container] 2016/04/15 17:49:44 [INFO] Scanning for projects... -[Container] 2016/04/15 17:49:44 [INFO] -[Container] 2016/04/15 17:49:44 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:44 [INFO] Building Message Utility Java Sample App 1.0 -[Container] 2016/04/15 17:49:44 [INFO] ------------------------------------------------------------------------ -... -[Container] 2016/04/15 17:49:55 ------------------------------------------------------- -[Container] 2016/04/15 17:49:55 T E S T S -[Container] 2016/04/15 17:49:55 ------------------------------------------------------- -[Container] 2016/04/15 17:49:55 Running TestMessageUtil -[Container] 2016/04/15 17:49:55 Inside testSalutationMessage() -[Container] 2016/04/15 17:49:55 Hi!Robert -[Container] 2016/04/15 17:49:55 Inside testPrintMessage() -[Container] 2016/04/15 17:49:55 Robert -[Container] 2016/04/15 17:49:55 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.018 sec -[Container] 2016/04/15 17:49:55 -[Container] 2016/04/15 17:49:55 Results : -[Container] 2016/04/15 17:49:55 -[Container] 2016/04/15 17:49:55 Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 -... -[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:56 [INFO] BUILD SUCCESS -[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:56 [INFO] Total time: 11.845 s -[Container] 2016/04/15 17:49:56 [INFO] Finished at: 2016-04-15T17:49:56+00:00 -[Container] 2016/04/15 17:49:56 [INFO] Final Memory: 18M/216M -[Container] 2016/04/15 17:49:56 [INFO] ------------------------------------------------------------------------ -[Container] 2016/04/15 17:49:56 Phase complete: BUILD Success: true -[Container] 2016/04/15 17:49:56 Entering phase POST_BUILD -[Container] 2016/04/15 17:49:56 Running command echo Entering post_build phase... -[Container] 2016/04/15 17:49:56 Entering post_build phase... -[Container] 2016/04/15 17:49:56 Phase complete: POST_BUILD Success: true -[Container] 2016/04/15 17:49:57 Preparing to copy artifacts -[Container] 2016/04/15 17:49:57 Assembling file list -[Container] 2016/04/15 17:49:57 Expanding target/messageUtil-1.0.jar -[Container] 2016/04/15 17:49:57 Found target/messageUtil-1.0.jar -[Container] 2016/04/15 17:49:57 Creating zip artifact -``` - -In this example, CodeBuild successfully completed the pre\-build, build, and post\-build build phases\. It ran the unit tests and successfully built the `messageUtil-1.0.jar` file\. - -## Next step - -[Step 9: Get the build output artifact](getting-started-cli-output.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-clean-up.md b/doc_source/getting-started-cli-clean-up.md deleted file mode 100644 index 58fb3a6..0000000 --- a/doc_source/getting-started-cli-clean-up.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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 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 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\. - -``` -{ - "Version": "2012-10-17", - "Id": "...", - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Effect": "Allow", - "Action": [ - "s3:DeleteBucket", - "s3:DeleteObject" - ], - "Resource": "*" - } - ### END ADDING STATEMENT HERE ### - ] -} -``` - -## Next step - -[Wrapping up](getting-started-cli-next-steps.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-project.md b/doc_source/getting-started-cli-create-build-project.md deleted file mode 100644 index 43a6ab1..0000000 --- a/doc_source/getting-started-cli-create-build-project.md +++ /dev/null @@ -1,112 +0,0 @@ -# Step 5: Create the build project - -\(Previous step: [Step 4: Upload the source code and the buildspec file](getting-started-cli-upload-source-code.md)\) - -In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker overview](https://docs.docker.com/get-started/overview/) on the Docker Docs website\. - -For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. - -**To create the build project** - -1. Use the AWS CLI to 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 named `create-project.json` in a location on the local computer or instance where the AWS CLI is installed\. If you choose to use a different file name, be sure to use it throughout this tutorial\. - - Modify the copied data to follow this format, and then save your results: - - ``` - { - "name": "codebuild-demo-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "artifacts": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "BUILD_GENERAL1_SMALL" - }, - "serviceRole": "serviceIAMRole" - } - ``` - - Replace *serviceIAMRole* with the Amazon Resource Name \(ARN\) of a CodeBuild service role \(for example, `arn:aws:iam::account-ID:role/role-name`\)\. To create one, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. - - In this data: - + `name` represents a required identifier for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across all build projects in your account\. - + For `source`, `type` is a required value that represents the source code's repository type \(in this example, `S3` for an Amazon S3 bucket\)\. - + 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 \(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`\)\. -**Note** -Other available values in the original JSON\-formatted data, such as `description`, `buildspec`, `auth` \(including `type` and `resource`\), `path`, `namespaceType`, `name` \(for `artifacts`\), `packaging`, `environmentVariables` \(including `name` and `value`\), `timeoutInMinutes`, `encryptionKey`, and `tags` \(including `key` and `value`\) are optional\. They are not used in this tutorial, so they are not shown here\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. - -1. Switch to the directory that contains the file you just saved, and then run the create\-project command again\. - - ``` - aws codebuild create-project --cli-input-json file://create-project.json - ``` - - If successful, data similar to this appears in the output\. - - ``` - { - "project": { - "name": "codebuild-demo-project", - "serviceRole": "serviceIAMRole", - "tags": [], - "artifacts": { - "packaging": "NONE", - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket", - "name": "message-util.zip" - }, - "lastModified": 1472661575.244, - "timeoutInMinutes": 60, - "created": 1472661575.244, - "environment": { - "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:4.0", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "encryptionKey": "arn:aws:kms:region-ID:account-ID:alias/aws/s3", - "arn": "arn:aws:codebuild:region-ID:account-ID:project/codebuild-demo-project" - } - } - ``` - + `project` represents information about this build project\. - + `tags` represents any tags that were declared\. - + `packaging` represents how the build output artifact is stored in the output bucket\. `NONE` means that a folder is created in the output bucket\. The build output artifact is stored in that folder\. - + `lastModified` represents the time, in Unix time format, when information about the build project was last changed\. - + `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 customer managed key that CodeBuild used to encrypt the build output artifact\. - + `arn` represents the ARN of the build project\. - -**Note** -After you run the create\-project command, an error message similar to the following might be output: **User: *user\-ARN* is not authorized to perform: codebuild:CreateProject**\. This is most likely because you configured the AWS CLI with the credentials of an IAM user who does not have sufficient permissions to use CodeBuild to create build projects\. To fix this, configure the AWS CLI with credentials belonging to one of the following IAM entities: -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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS managed \(predefined\) policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. - -## Next step - -[Step 6: Run the build](getting-started-cli-run-build.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli-create-build-spec.md b/doc_source/getting-started-cli-create-build-spec.md deleted file mode 100644 index 1260cc3..0000000 --- a/doc_source/getting-started-cli-create-build-spec.md +++ /dev/null @@ -1,63 +0,0 @@ -# Step 2: Create the buildspec file - -\(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\. - -Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. - -``` -version: 0.2 - -phases: - install: - runtime-versions: - java: corretto11 - pre_build: - commands: - - echo Nothing to do in the pre_build phase... - build: - commands: - - echo Build started on `date` - - mvn install - post_build: - commands: - - echo Build completed on `date` -artifacts: - files: - - target/messageUtil-1.0.jar -``` - -**Important** -Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. - -**Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - -In this build spec declaration: -+ `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. -+ `phases` represents the build phases during which you can instruct CodeBuild to run commands\. These build phases are listed here as `install`, `pre_build`, `build`, and `post_build`\. You cannot change the spelling of these build phase names, and you cannot create more build phase names\. - - In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. -+ `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. - -For more information, see the [Buildspec reference](build-spec-ref.md)\. - -At this point, your directory structure should look like this\. - -``` -(root directory name) - |-- pom.xml - |-- buildspec.yml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -## Next step - -[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 deleted file mode 100644 index 23e9d08..0000000 --- a/doc_source/getting-started-cli-create-source-code.md +++ /dev/null @@ -1,122 +0,0 @@ -# Step 1: Create the source code - -\(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\. - -1. In an empty directory on your local computer or instance, create this directory structure\. - - ``` - (root directory name) - `-- src - |-- main - | `-- java - `-- test - `-- java - ``` - -1. Using a text editor of your choice, create this file, name it `MessageUtil.java`, and then save it in the `src/main/java` directory\. - - ``` - public class MessageUtil { - private String message; - - public MessageUtil(String message) { - this.message = message; - } - - public String printMessage() { - System.out.println(message); - return message; - } - - public String salutationMessage() { - message = "Hi!" + message; - System.out.println(message); - return message; - } - } - ``` - - This class file creates as output the string of characters passed into it\. The `MessageUtil` constructor sets the string of characters\. The `printMessage` method creates the output\. The `salutationMessage` method outputs `Hi!` followed by the string of characters\. - -1. Create this file, name it `TestMessageUtil.java`, and then save it in the `/src/test/java` directory\. - - ``` - import org.junit.Test; - import org.junit.Ignore; - import static org.junit.Assert.assertEquals; - - public class TestMessageUtil { - - String message = "Robert"; - MessageUtil messageUtil = new MessageUtil(message); - - @Test - public void testPrintMessage() { - System.out.println("Inside testPrintMessage()"); - assertEquals(message,messageUtil.printMessage()); - } - - @Test - public void testSalutationMessage() { - System.out.println("Inside testSalutationMessage()"); - message = "Hi!" + "Robert"; - assertEquals(message,messageUtil.salutationMessage()); - } - } - ``` - - This class file sets the `message` variable in the `MessageUtil` class to `Robert`\. It then tests to see if the `message` variable was successfully set by checking whether the strings `Robert` and `Hi!Robert` appear in the output\. - -1. Create this file, name it `pom.xml`, and then save it in the root \(top level\) directory\. - - ``` - - 4.0.0 - org.example - messageUtil - 1.0 - jar - Message Utility Java Sample App - - - junit - junit - 4.11 - test - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.8.0 - - - - - ``` - - Apache Maven uses the instructions in this file to convert the `MessageUtil.java` and `TestMessageUtil.java` files into a file named `messageUtil-1.0.jar` and then run the specified tests\. - -At this point, your directory structure should look like this\. - -``` -(root directory name) - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -## Next step - -[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 deleted file mode 100644 index dc57f3d..0000000 --- a/doc_source/getting-started-cli-input-bucket.md +++ /dev/null @@ -1,20 +0,0 @@ -# Step 3: Create two S3 buckets - -\(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\. -+ The other bucket \(the *output bucket*\) stores the build output\. In this tutorial, the name of this output bucket is `codebuild-region-ID-account-ID-output-bucket`\. - -If you chose different names for these buckets, be sure to use them throughout this tutorial\. - -These two buckets must be in the same AWS Region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, these buckets must also be in the US East \(Ohio\) Region\. - -For more information, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon Simple Storage Service User Guide*\. - -**Note** -Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a build](planning.md)\. - -## 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 diff --git a/doc_source/getting-started-cli-monitor-build.md b/doc_source/getting-started-cli-monitor-build.md deleted file mode 100644 index bf3c6ee..0000000 --- a/doc_source/getting-started-cli-monitor-build.md +++ /dev/null @@ -1,87 +0,0 @@ -# Step 7: View summarized build information - -\(Previous step: [Step 6: Run the build](getting-started-cli-run-build.md)\) - -In this step, you view summarized information about the status of your build\. - -## To view summarized build information - -Use the AWS CLI to run the batch\-get\-builds command\. - -``` -aws codebuild batch-get-builds --ids id -``` - -Replace *id* with the `id` value that appeared in the output of the previous step\. - -If successful, data similar to this appears in the output\. - -``` -{ - "buildsNotFound": [], - "builds": [ - { - "buildComplete": true, - "phases": [ - { - "phaseStatus": "SUCCEEDED", - "endTime": 1472848788.525, - "phaseType": "SUBMITTED", - "durationInSeconds": 0, - "startTime": 1472848787.882 - }, - ... The full list of build phases has been omitted for brevity ... - { - "phaseType": "COMPLETED", - "startTime": 1472848878.079 - } - ], - "logs": { - "groupName": "/aws/codebuild/codebuild-demo-project", - "deepLink": "https://console.aws.amazon.com/cloudwatch/home?region=region-ID#logEvent:group=/aws/codebuild/codebuild-demo-project;stream=38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE", - "streamName": "38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE" - }, - "artifacts": { - "md5sum": "MD5-hash", - "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip", - "sha256sum": "SHA-256-hash" - }, - "projectName": "codebuild-demo-project", - "timeoutInMinutes": 60, - "initiator": "user-name", - "buildStatus": "SUCCEEDED", - "environment": { - "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:4.0", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "currentPhase": "COMPLETED", - "startTime": 1472848787.882, - "endTime": 1472848878.079, - "id": "codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE", - "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:38ca1c4a-e9ca-4dbc-bef1-d52bfEXAMPLE" - } - ] -} -``` -+ `buildsNotFound` represents the build IDs for any builds where information is not available\. In this example, it should be empty\. -+ `builds` represents information about each build where information is available\. In this example, information about only one build appears in the output\. - + `phases` represents the set of build phases CodeBuild runs during the build process\. Information about each build phase is listed separately as `startTime`, `endTime`, and `durationInSeconds` \(when the build phase started and ended, expressed in Unix time format, and how long it lasted, in seconds\), and `phaseType` such as \(`SUBMITTED`, `PROVISIONING`, `DOWNLOAD_SOURCE`, `INSTALL`, `PRE_BUILD`, `BUILD`, `POST_BUILD`, `UPLOAD_ARTIFACTS`, `FINALIZING`, or `COMPLETED`\) and `phaseStatus` \(such as `SUCCEEDED`, `FAILED`, `FAULT`, `TIMED_OUT`, `IN_PROGRESS`, or `STOPPED`\)\. The first time you run the batch\-get\-builds command, there might not be many \(or any\) phases\. After subsequent runs of the batch\-get\-builds command with the same build ID, more build phases should appear in the output\. - + `logs` represents information in Amazon CloudWatch Logs about the build's logs\. - + `md5sum` and `sha256sum` represent MD5 and SHA\-256 hashes of the build's output artifact\. These appear in the output only if the build project's `packaging` value is set to `ZIP`\. \(You did not set this value in this tutorial\.\) You can use these hashes along with a checksum tool to confirm file integrity and authenticity\. -**Note** -You can also use the Amazon S3 console to view these hashes\. Select the box next to the build output artifact, choose **Actions**, and then choose **Properties**\. In the **Properties** pane, expand **Metadata**, and view the values for **x\-amz\-meta\-codebuild\-content\-md5** and **x\-amz\-meta\-codebuild\-content\-sha256**\. \(In the Amazon S3 console, the build output artifact's **ETag** value should not be interpreted to be either the MD5 or SHA\-256 hash\.\) -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 deleted file mode 100644 index e8f4161..0000000 --- a/doc_source/getting-started-cli-next-steps.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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 deleted file mode 100644 index edc86d9..0000000 --- a/doc_source/getting-started-cli-output.md +++ /dev/null @@ -1,31 +0,0 @@ -# Step 9: Get the build output artifact - -\(Previous step: [Step 8: View detailed build information](getting-started-cli-build-log.md)\) - -In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. - -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\. -**Note** -If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\. - -1. The link to the Amazon S3 folder is under the **Artifacts upload location**\. This link opens the folder in Amazon S3 where you find the `messageUtil-1.0.jar` build output artifact file\. - -**To get the build output artifact \(Amazon S3 console\)** - -1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. - -1. Open `codebuild-region-ID-account-ID-output-bucket`\. - -1. Open the `codebuild-demo-project` folder\. - -1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. - -## Next step - -[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-run-build.md b/doc_source/getting-started-cli-run-build.md deleted file mode 100644 index 00fe214..0000000 --- a/doc_source/getting-started-cli-run-build.md +++ /dev/null @@ -1,62 +0,0 @@ -# Step 6: Run the build - -\(Previous step: [Step 5: Create the build project](getting-started-cli-create-build-project.md)\) - -In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. - -**To run the build** - -1. Use the AWS CLI to run the start\-build command: - - ``` - aws codebuild start-build --project-name project-name - ``` - - Replace *project\-name* with your build project name from the previous step \(for example, `codebuild-demo-project`\)\. - -1. If successful, data similar to the following appears in the output: - - ``` - { - "build": { - "buildComplete": false, - "initiator": "user-name", - "artifacts": { - "location": "arn:aws:s3:::codebuild-region-ID-account-ID-output-bucket/message-util.zip" - }, - "projectName": "codebuild-demo-project", - "timeoutInMinutes": 60, - "buildStatus": "IN_PROGRESS", - "environment": { - "computeType": "BUILD_GENERAL1_SMALL", - "image": "aws/codebuild/standard:4.0", - "type": "LINUX_CONTAINER", - "environmentVariables": [] - }, - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/MessageUtil.zip" - }, - "currentPhase": "SUBMITTED", - "startTime": 1472848787.882, - "id": "codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE", - "arn": "arn:aws:codebuild:region-ID:account-ID:build/codebuild-demo-project:0cfbb6ec-3db9-4e8c-992b-1ab28EXAMPLE" - } - } - ``` - + `build` represents information about this build\. - + `buildComplete` represents whether the build was completed \(`true`\)\. Otherwise, `false`\. - + `initiator` represents the entity that started the build\. - + `artifacts` represents information about the build output, including its location\. - + `projectName` represents the name of the build project\. - + `buildStatus` represents the current build status when the start\-build command was run\. - + `currentPhase` represents the current build phase when the start\-build command was run\. - + `startTime` represents the time, in Unix time format, when the build process started\. - + `id` represents the ID of the build\. - + `arn` represents the ARN of the build\. - - Make a note of the `id` value\. You need it in the next step\. - -## Next step - -[Step 7: View summarized build information](getting-started-cli-monitor-build.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 deleted file mode 100644 index adfc66f..0000000 --- a/doc_source/getting-started-cli-upload-source-code.md +++ /dev/null @@ -1,36 +0,0 @@ -# Step 4: Upload the source code and the buildspec file - -\(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\. - -Using your operating system's zip utility, create a file named `MessageUtil.zip` that includes `MessageUtil.java`, `TestMessageUtil.java`, `pom.xml`, and `buildspec.yml`\. - -The `MessageUtil.zip` file's directory structure must look like this\. - -``` -MessageUtil.zip - |-- pom.xml - |-- buildspec.yml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -**Important** -Do not include the `(root directory name)` directory, only the directories and files in the `(root directory name)` directory\. - -Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID-account-ID-input-bucket`\. - -**Important** -For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. -For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. - -## Next step - -[Step 5: Create the build project](getting-started-cli-create-build-project.md) \ No newline at end of file diff --git a/doc_source/getting-started-cli.md b/doc_source/getting-started-cli.md deleted file mode 100644 index 81e613e..0000000 --- a/doc_source/getting-started-cli.md +++ /dev/null @@ -1,21 +0,0 @@ -# Getting started with AWS CodeBuild using the AWS CLI - -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 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 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 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-project-console.md b/doc_source/getting-started-create-build-project-console.md deleted file mode 100644 index d348586..0000000 --- a/doc_source/getting-started-create-build-project-console.md +++ /dev/null @@ -1,52 +0,0 @@ -# Step 5: Create the build project - -\(Previous step: [Step 4: Upload the source code and the buildspec file](getting-started-upload-source-code-console.md)\) - -In this step, you create a build project that AWS CodeBuild uses to run the build\. 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\. The build environment is expressed as a Docker image\. For more information, see [Docker overview](https://docs.docker.com/get-started/overview/) on the Docker Docs website\. - -For this build environment, you instruct CodeBuild to use a Docker image that contains a version of the Java Development Kit \(JDK\) and Apache Maven\. - -**To create the build project** - -1. Sign in to the AWS Management Console and open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. For more information, see [AWS CodeBuild endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the *Amazon Web Services General Reference*\. - -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**, for **Project name**, enter a name for this build project \(in this example, `codebuild-demo-project`\)\. Build project names must be unique across each AWS account\. If you use a different name, be sure to use it throughout this tutorial\. -**Note** -On the **Create build project** page, you might see an error message similar to the following: **You are not authorized to perform this operation\.**\. This is most likely because you signed in to the AWS Management Console as an IAM user who does not have permissions to create a build project\.\. To fix this, sign out of the AWS Management Console, and then sign back in with credentials belonging to one of the following IAM entities: -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 the `AWSCodeBuildAdminAccess`, `AmazonS3ReadOnlyAccess`, and `IAMFullAccess` managed policies attached to that IAM user or to an IAM group that the IAM user belongs to\. If you do not have an IAM user or group in your AWS account with these permissions, and you cannot add these permissions to your IAM user or group, contact your AWS account administrator for assistance\. For more information, see [AWS managed \(predefined\) policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md#managed-policies)\. -Both options include administrator permissions that allow you to create a build project so you can complete this tutorial\. We recommend that you always use the minimum permissions required to accomplish your task\. For more information, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. - -1. In **Source**, for **Source provider**, choose **Amazon S3**\. - -1. For **Bucket**, choose **codebuild\-*region\-ID*\-*account\-ID*\-input\-bucket**\. - -1. For **S3 object key**, enter **MessageUtil\.zip**\. - -1. In **Environment**, for **Environment image**, leave **Managed image** selected\. - -1. For **Operating system**, choose **Amazon Linux 2**\. - -1. For **Runtime\(s\)**, choose **Standard**\. - -1. For **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. - -1. In **Service role**, leave **New service role** selected, and leave **Role name** unchanged\. - -1. For **Buildspec**, leave **Use a buildspec file** selected\. - -1. In **Artifacts**, for **Type**, choose **Amazon S3**\. - -1. For **Bucket name**, choose **codebuild\-*region\-ID*\-*account\-ID*\-output\-bucket**\. - -1. Leave **Name** and **Path** blank\. - -1. Choose **Create build project**\. - -## Next step - -[Step 6: Run the build](getting-started-run-build-console.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 deleted file mode 100644 index 6480b38..0000000 --- a/doc_source/getting-started-create-build-spec-console.md +++ /dev/null @@ -1,63 +0,0 @@ -# Step 2: Create the buildspec file - -\(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\. - -Create this file, name it `buildspec.yml`, and then save it in the root \(top level\) directory\. - -``` -version: 0.2 - -phases: - install: - runtime-versions: - java: corretto11 - pre_build: - commands: - - echo Nothing to do in the pre_build phase... - build: - commands: - - echo Build started on `date` - - mvn install - post_build: - commands: - - echo Build completed on `date` -artifacts: - files: - - target/messageUtil-1.0.jar -``` - -**Important** -Because a build spec declaration must be valid YAML, the spacing in a build spec declaration is important\. If the number of spaces in your build spec declaration does not match this one, the build might fail immediately\. You can use a YAML validator to test whether your build spec declaration is valid YAML\. - -**Note** -Instead of including a build spec file in your source code, you can declare build commands separately when you create a build project\. This is helpful if you want to build your source code with different build commands without updating your source code's repository each time\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - -In this build spec declaration: -+ `version` represents the version of the build spec standard being used\. This build spec declaration uses the latest version, `0.2`\. -+ `phases` represents the build phases during which you can instruct CodeBuild to run commands\. These build phases are listed here as `install`, `pre_build`, `build`, and `post_build`\. You cannot change the spelling of these build phase names, and you cannot create more build phase names\. - - In this example, during the `build` phase, CodeBuild runs the `mvn install` command\. This command instructs Apache Maven to compile, test, and package the compiled Java class files into a build output artifact\. For completeness, a few `echo` commands are placed in each build phase in this example\. When you view detailed build information later in this tutorial, the output of these `echo` commands can help you better understand how CodeBuild runs commands and in which order\. \(Although all build phases are included in this example, you are not required to include a build phase if you do not plan to run any commands during that phase\.\) For each build phase, CodeBuild runs each specified command, one at a time, in the order listed, from beginning to end\. -+ `artifacts` represents the set of build output artifacts that CodeBuild uploads to the output bucket\. `files` represents the files to include in the build output\. CodeBuild uploads the single `messageUtil-1.0.jar` file found in the `target` relative directory in the build environment\. The file name `messageUtil-1.0.jar` and the directory name `target` are based on the way Apache Maven creates and stores build output artifacts for this example only\. In your own builds, these file names and directories are different\. - -For more information, see the [Buildspec reference](build-spec-ref.md)\. - -At this point, your directory structure should look like this\. - -``` -(root directory name) - |-- pom.xml - |-- buildspec.yml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -## Next step - -[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 deleted file mode 100644 index ef4a02d..0000000 --- a/doc_source/getting-started-create-source-code-console.md +++ /dev/null @@ -1,122 +0,0 @@ -# Step 1: Create the source code - -\(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\. - -1. In an empty directory on your local computer or instance, create this directory structure\. - - ``` - (root directory name) - `-- src - |-- main - | `-- java - `-- test - `-- java - ``` - -1. Using a text editor of your choice, create this file, name it `MessageUtil.java`, and then save it in the `src/main/java` directory\. - - ``` - public class MessageUtil { - private String message; - - public MessageUtil(String message) { - this.message = message; - } - - public String printMessage() { - System.out.println(message); - return message; - } - - public String salutationMessage() { - message = "Hi!" + message; - System.out.println(message); - return message; - } - } - ``` - - This class file creates as output the string of characters passed into it\. The `MessageUtil` constructor sets the string of characters\. The `printMessage` method creates the output\. The `salutationMessage` method outputs `Hi!` followed by the string of characters\. - -1. Create this file, name it `TestMessageUtil.java`, and then save it in the `/src/test/java` directory\. - - ``` - import org.junit.Test; - import org.junit.Ignore; - import static org.junit.Assert.assertEquals; - - public class TestMessageUtil { - - String message = "Robert"; - MessageUtil messageUtil = new MessageUtil(message); - - @Test - public void testPrintMessage() { - System.out.println("Inside testPrintMessage()"); - assertEquals(message,messageUtil.printMessage()); - } - - @Test - public void testSalutationMessage() { - System.out.println("Inside testSalutationMessage()"); - message = "Hi!" + "Robert"; - assertEquals(message,messageUtil.salutationMessage()); - } - } - ``` - - This class file sets the `message` variable in the `MessageUtil` class to `Robert`\. It then tests to see if the `message` variable was successfully set by checking whether the strings `Robert` and `Hi!Robert` appear in the output\. - -1. Create this file, name it `pom.xml`, and then save it in the root \(top level\) directory\. - - ``` - - 4.0.0 - org.example - messageUtil - 1.0 - jar - Message Utility Java Sample App - - - junit - junit - 4.11 - test - - - - - - org.apache.maven.plugins - maven-compiler-plugin - 3.8.0 - - - - - ``` - - Apache Maven uses the instructions in this file to convert the `MessageUtil.java` and `TestMessageUtil.java` files into a file named `messageUtil-1.0.jar` and then run the specified tests\. - -At this point, your directory structure should look like this\. - -``` -(root directory name) - |-- pom.xml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -## Next step - -[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 deleted file mode 100644 index 64b9f1c..0000000 --- a/doc_source/getting-started-input-bucket-console.md +++ /dev/null @@ -1,20 +0,0 @@ -# Step 3: Create two S3 buckets - -\(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\. -+ The other bucket \(the *output bucket*\) stores the build output\. In this tutorial, the name of this output bucket is `codebuild-region-ID-account-ID-output-bucket`\. - -If you chose different names for these buckets, be sure to use them throughout this tutorial\. - -These two buckets must be in the same AWS Region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, these buckets must also be in the US East \(Ohio\) Region\. - -For more information, see [Creating a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) in the *Amazon Simple Storage Service User Guide*\. - -**Note** -Although CodeBuild also supports build input stored in CodeCommit, GitHub, and Bitbucket repositories, this tutorial does not show you how to use them\. For more information, see [Plan a build](planning.md)\. - -## 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 diff --git a/doc_source/getting-started-monitor-build-console.md b/doc_source/getting-started-monitor-build-console.md deleted file mode 100644 index b97aa70..0000000 --- a/doc_source/getting-started-monitor-build-console.md +++ /dev/null @@ -1,32 +0,0 @@ -# Step 7: View summarized build information - -\(Previous step: [Step 6: Run the build](getting-started-run-build-console.md)\) - -In this step, you view summarized information about the status of your build\. - -## To view summarized build information - -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 status** page, in **Phase details**, the following build phases should be displayed, with **Succeeded** in the **Status** column: - + **SUBMITTED** - + **QUEUED** - + **PROVISIONING** - + **DOWNLOAD\_SOURCE** - + **INSTALL** - + **PRE\_BUILD** - + **BUILD** - + **POST\_BUILD** - + **UPLOAD\_ARTIFACTS** - + **FINALIZING** - + **COMPLETED** - - In **Build Status**, **Succeeded** should be displayed\. - - If you see **In Progress** instead, choose the refresh button\. - -1. Next to each build phase, the **Duration** value indicates how long the build phase lasted\. The **End time** value indicates when that build phase ended\. - -## Next step - -[Step 8: View detailed build information](getting-started-build-log-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-next-steps-console.md b/doc_source/getting-started-next-steps-console.md deleted file mode 100644 index 192314b..0000000 --- a/doc_source/getting-started-next-steps-console.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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 deleted file mode 100644 index b92c297..0000000 --- a/doc_source/getting-started-output-console.md +++ /dev/null @@ -1,31 +0,0 @@ -# Step 9: Get the build output artifact - -\(Previous step: [Step 8: View detailed build information](getting-started-build-log-console.md)\) - -In this step, you get the `messageUtil-1.0.jar` file that CodeBuild built and uploaded to the output bucket\. - -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\. -**Note** -If the build details page is not displayed, in the navigation bar, choose **Build history**, and then choose the **Build run** link\. - -1. The link to the Amazon S3 folder is under the **Artifacts upload location**\. This link opens the folder in Amazon S3 where you find the `messageUtil-1.0.jar` build output artifact file\. - -**To get the build output artifact \(Amazon S3 console\)** - -1. Open the Amazon S3 console at [https://console\.aws\.amazon\.com/s3/](https://console.aws.amazon.com/s3/)\. - -1. Open `codebuild-region-ID-account-ID-output-bucket`\. - -1. Open the `codebuild-demo-project` folder\. - -1. Open the `target` folder, where you find the `messageUtil-1.0.jar` build output artifact file\. - -## Next step - -[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-overview.md b/doc_source/getting-started-overview.md deleted file mode 100644 index 5ee0384..0000000 --- a/doc_source/getting-started-overview.md +++ /dev/null @@ -1,8 +0,0 @@ -# Getting started with CodeBuild - -In the following tutorials, you use AWS CodeBuild to build a collection of sample source code input files into a deployable version of the source code\. - -Both tutorials have the same input and results, but one uses the AWS CodeBuild console and the other uses the AWS CLI\. - -**Important** -We do not recommend that you use your AWS root account to complete this tutorial\. \ 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 deleted file mode 100644 index acd11ef..0000000 --- a/doc_source/getting-started-run-build-console.md +++ /dev/null @@ -1,17 +0,0 @@ -# Step 6: Run the build - -\(Previous step: [Step 5: Create the build project](getting-started-create-build-project-console.md)\) - -In this step, you instruct AWS CodeBuild to run the build with the settings in the build project\. - -**To run the build** - -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. In the list of build projects, choose **codebuild\-demo\-project**, and then choose **Start build**\. The build starts immediately\. - -## Next step - -[Step 7: View summarized build information](getting-started-monitor-build-console.md) \ No newline at end of file diff --git a/doc_source/getting-started-upload-source-code-console.md b/doc_source/getting-started-upload-source-code-console.md deleted file mode 100644 index e17b19a..0000000 --- a/doc_source/getting-started-upload-source-code-console.md +++ /dev/null @@ -1,36 +0,0 @@ -# Step 4: Upload the source code and the buildspec file - -\(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\. - -Using your operating system's zip utility, create a file named `MessageUtil.zip` that includes `MessageUtil.java`, `TestMessageUtil.java`, `pom.xml`, and `buildspec.yml`\. - -The `MessageUtil.zip` file's directory structure must look like this\. - -``` -MessageUtil.zip - |-- pom.xml - |-- buildspec.yml - `-- src - |-- main - | `-- java - | `-- MessageUtil.java - `-- test - `-- java - `-- TestMessageUtil.java -``` - -**Important** -Do not include the `(root directory name)` directory, only the directories and files in the `(root directory name)` directory\. - -Upload the `MessageUtil.zip` file to the input bucket named `codebuild-region-ID-account-ID-input-bucket`\. - -**Important** -For CodeCommit, GitHub, and Bitbucket repositories, by convention, you must store a build spec file named `buildspec.yml` in the root \(top level\) of each repository or include the build spec declaration as part of the build project definition\. Do not create a ZIP file that contains the repository's source code and build spec file\. -For build input stored in S3 buckets only, you must create a ZIP file that contains the source code and, by convention, a build spec file named `buildspec.yml` at the root \(top level\) or include the build spec declaration as part of the build project definition\. -If you want to use a different name for your build spec file, or you want to reference a build spec in a location other than the root, you can specify a build spec override as part of the build project definition\. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage)\. - -## Next step - -[Step 5: Create the build project](getting-started-create-build-project-console.md) \ No newline at end of file diff --git a/doc_source/getting-started.md b/doc_source/getting-started.md deleted file mode 100644 index 8292576..0000000 --- a/doc_source/getting-started.md +++ /dev/null @@ -1,21 +0,0 @@ -# Getting started with AWS CodeBuild using the console - -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 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 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 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 deleted file mode 100644 index 0b47374..0000000 --- a/doc_source/github-webhook.md +++ /dev/null @@ -1,246 +0,0 @@ -# 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/glossary.md b/doc_source/glossary.md deleted file mode 100644 index 0fccc48..0000000 --- a/doc_source/glossary.md +++ /dev/null @@ -1,3 +0,0 @@ -# AWS glossary - -For the latest AWS terminology, see the [AWS glossary](https://docs.aws.amazon.com/general/latest/gr/glos-chap.html) in the *AWS General Reference*\. \ No newline at end of file diff --git a/doc_source/history.md b/doc_source/history.md deleted file mode 100644 index a402310..0000000 --- a/doc_source/history.md +++ /dev/null @@ -1,103 +0,0 @@ -# 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:** 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 | -| [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 | -| [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) | 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/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 | -| [Updated topic](#history) | CodeBuild now supports using an access token to connect to GitHub \(with a personal access token\) and Bitbucket \(with an app password\) repositories\. For more information, see [Create a build project \(console\)](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html#create-project-console) and [Use access tokens with your source provider](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-access-tokens.html)\. | December 6, 2018 | -| [Updated topic](#history) | CodeBuild now supports new build metrics that measure the duration of each phase in a build\. For more information, see [ CodeBuild CloudWatch metrics](https://docs.aws.amazon.com/codebuild/latest/userguide/monitoring-builds.html#cloudwatch_metrics-codebuild)\. | November 15, 2018 | -| [VPC endpoint policy topic](#history) | Amazon VPC endpoints for CodeBuild now support policies\. For more information, see [ Create a VPC endpoint policy for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/use-vpc-endpoints-with-codebuild.html#creating-vpc-endpoint-policy)\. | November 9, 2018 | -| [Updated content](#history) | Topics have been updated to reflect the new console experience\. | October 30, 2018 | -| [Amazon EFS sample](#history) | CodeBuild can mount an Amazon EFS file system during a build using commands in a project's buildspec file\. For more information, see [Amazon EFS sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-efs.html)\. | October 26, 2018 | -| [Bitbucket webhooks](#history) | CodeBuild now supports webhooks when you use Bitbucket for your repository\. For more information, see [Bitbucket pull request sample for CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-bitbucket-pull-request.html)\. | October 2, 2018 | -| [S3 logs](#history) | CodeBuild now supports build logs in an S3 bucket\. Previously, you could only build logs using CloudWatch Logs\. For more information, see [Create project](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html)\. | September 17, 2018 | -| [Multiple inpout sources and multiple output artifacts](#history) | CodeBuild now supports projects that use more than one input source and publish more than one set of artifacts\. For more information, see [ Multiple input sources and input artifacts sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-multi-in-out.html) and [CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-pipeline-multi-input-output.html)\. | August 30, 2018 | -| [Semantic versioning sample](#history) | The CodeBuild User Guide now has a use case\-based sample that demonstrates how to use semantic versioning to create artifact names at build time\. For more information, see [ Use semantic versioning to name build artifacts sample](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-buildspec-artifact-naming.html)\. | August 14, 2018 | -| [New static website sample](#history) | The CodeBuild User Guide now has a use case\-based sample that demonstrates how to host build output in an S3 bucket\. The sample takes advantage of the recent support of unencrypted build artifacts\. For more information, see [Create a static website with build output hosted in an S3 bucket](https://docs.aws.amazon.com/codebuild/latest/userguide/sample-disable-artifact-encryption.html)\. | August 14, 2018 | -| [Support for overriding an artifact name with semantic versioning](#history) | You can now use semantic versioning to specify a format that CodeBuild uses to name build artifacts\. This is useful because a build artifact with a hard\-coded name overwrites previous build artifacts that use the same hard\-coded name\. For example, if a build is triggered multiple times a day, you can now add a timestamp to its artifact name\. Each build artifact name is unique and does not overwrite the artifacts of previous builds\. | August 7, 2018 | -| [Support of unencrypted build artifacts](#history) | CodeBuild now supports builds with unencrypted build artifacts\. For more information, see [Create a build project \(console\)](https://docs.aws.amazon.com/codebuild/latest/userguide/create-project.html#create-project-console)\. | July 26, 2018 | -| [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 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 - -The following table describes important changes in each release of the *AWS CodeBuild User Guide* before June 2018\. - - -| 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 | -| 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 | -| 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-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 deleted file mode 100644 index 9acb71e..0000000 --- a/doc_source/how-to-create-pipeline-add-test.md +++ /dev/null @@ -1,84 +0,0 @@ -# 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 deleted file mode 100644 index 1624ed7..0000000 --- a/doc_source/how-to-create-pipeline-add.md +++ /dev/null @@ -1,100 +0,0 @@ -# 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 deleted file mode 100644 index 6e2909d..0000000 --- a/doc_source/how-to-create-pipeline-cli.md +++ /dev/null @@ -1,150 +0,0 @@ -# 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 deleted file mode 100644 index 2e3d869..0000000 --- a/doc_source/how-to-create-pipeline-console.md +++ /dev/null @@ -1,106 +0,0 @@ -# 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 deleted file mode 100644 index 0efa474..0000000 --- a/doc_source/how-to-create-pipeline.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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\. - -The following table lists tasks and the methods available for performing them\. Using the AWS SDKs to accomplish these tasks is outside the scope of this topic\. - - -**** - -| Task | Available approaches | Approaches described in this topic | -| --- | --- | --- | -| 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) | - -## Prerequisites - -1. Answer the questions in [Plan a build](planning.md)\. - -1. If you are using an IAM user to access CodePipeline instead of an AWS root account or an administrator IAM user, attach the managed policy named `AWSCodePipelineFullAccess` to the user \(or to the IAM group to which the user belongs\)\. Using an AWS root account is not recommended\. This policy grants the user permission to create the pipeline in CodePipeline\. For more information, see [Attaching managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#attach-managed-policy-console) in the *IAM User Guide*\. -**Note** -The IAM entity that attaches the policy to the user \(or to the IAM group to which the user belongs\) must have permission in IAM to attach policies\. For more information, see [Delegating permissions to administer IAM users, groups, and credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_delegate-permissions.html) in the *IAM User Guide*\. - -1. Create a CodePipeline service role, if you do not already have one available in your AWS account\. CodePipeline uses this service role to interact with other AWS services, including AWS CodeBuild, on your behalf\. For example, to use the AWS CLI to create a CodePipeline service role, run the IAM `create-role` command: - - For Linux, macOS, or Unix: - - ``` - aws iam create-role --role-name AWS-CodePipeline-CodeBuild-Service-Role --assume-role-policy-document '{"Version":"2012-10-17","Statement":{"Effect":"Allow","Principal":{"Service":"codepipeline.amazonaws.com"},"Action":"sts:AssumeRole"}}' - ``` - - For Windows: - - ``` - aws iam create-role --role-name AWS-CodePipeline-CodeBuild-Service-Role --assume-role-policy-document "{\"Version\":\"2012-10-17\",\"Statement\":{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"codepipeline.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}}" - ``` -**Note** -The IAM entity that creates this CodePipeline service role must have permission in IAM to create service roles\. - -1. After you create a CodePipeline service role or identify an existing one, you must add the default CodePipeline service role policy to the service role as described in [Review the default CodePipeline service role policy](https://docs.aws.amazon.com/codepipeline/latest/userguide/iam-identity-based-access-control.html#how-to-custom-role) in the *AWS CodePipeline User Guide*, if it isn't already a part of the policy for the role\. -**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, 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*\. - -**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 deleted file mode 100644 index a321a2b..0000000 --- a/doc_source/how-to-integrate-config.md +++ /dev/null @@ -1,46 +0,0 @@ -# Use AWS Config with CodeBuild sample - -AWS Config provides an inventory of your AWS resources and a history of configuration changes to these resources\. AWS Config now supports AWS CodeBuild as an AWS resource, which means the service can track your CodeBuild projects\. For more information about AWS Config, see [What is AWS Config?](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) in the *AWS Config Developer Guide*\. - -You can see the following information about CodeBuild resources on the **Resource Inventory** page in the AWS Config console: -+ A timeline of your CodeBuild configuration changes\. -+ Configuration details for each CodeBuild project\. -+ Relationships with other AWS resources\. -+ A list of changes to your CodeBuild projects\. - -The procedures in this topic show you how to set up AWS Config and look up and view CodeBuild projects\. - -**Topics** -+ [Prerequisites](#how-to-create-a-build-project) -+ [Set up AWS Config](#setup-config) -+ [Look up AWS CodeBuild projects](#lookup-projects) -+ [Viewing AWS CodeBuild configuration details in the AWS Config console](#viewing-config-details) - -## Prerequisites - -Create your AWS CodeBuild project\. For instructions, see [Create a build project](create-project.md)\. - -## Set up AWS Config -+ [Setting up AWS Config \(console\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-console.html) -+ [Setting up AWS Config \(AWS CLI\)](https://docs.aws.amazon.com/config/latest/developerguide/gs-cli.html) - -**Note** -After you complete setup, it might take up to 10 minutes before you can see AWS CodeBuild projects in the AWS Config console\. - -## Look up AWS CodeBuild projects - -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, select **AWS CodeBuild Project** under **Resource type**\. Scroll down and select the **CodeBuild project** check box\. - -1. Choose **Look up**\. - -1. After the list of CodeBuild projects is added, choose the CodeBuild project name link in the **Config timeline** column\. - -## Viewing AWS CodeBuild configuration details in the AWS Config console - -When you look up resources on the **Resource inventory** page, you can choose the AWS Config timeline to view details about your CodeBuild project\. The details page for a resource provides information about the configuration, relationships, and number of changes made to that resource\. - -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*\. \ No newline at end of file diff --git a/doc_source/how-to-run.md b/doc_source/how-to-run.md deleted file mode 100644 index 1598318..0000000 --- a/doc_source/how-to-run.md +++ /dev/null @@ -1,21 +0,0 @@ -# Run AWS CodeBuild directly - -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 CodePipeline with CodeBuild](how-to-create-pipeline.md)\. - -**Topics** -+ [Prerequisites](#how-to-run-prerequisites) -+ [Run AWS CodeBuild directly](#how-to-run-console) - -## Prerequisites - -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)\. 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)\. 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)\. 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-add.md b/doc_source/how-to-tag-project-add.md deleted file mode 100644 index cc2c6b5..0000000 --- a/doc_source/how-to-tag-project-add.md +++ /dev/null @@ -1,38 +0,0 @@ -# Add a tag to a project - -Adding tags to a project can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a project\. Keep in mind that there are limits on the number of tags you can have on a project\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the project based on these tags\. You can use the CodeBuild console or the AWS CLI to add tags to a project\. - -**Important** -Before you add a tag to a project, make sure to review any IAM policies that might use tags to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -For more information about adding tags to a project when you create it, see [Add a tag to a project \(console\)](#how-to-tag-project-add-console)\. - -**Topics** -+ [Add a tag to a project \(console\)](#how-to-tag-project-add-console) -+ [Add a tag to a project \(AWS CLI\)](#how-to-tag-project-add-cli) - -## Add a tag to a project \(console\) - -You can use the CodeBuild console to add one or more tags to a CodeBuild project\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Build projects**, choose the name of the project where you want to add tags\. - -1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. - -1. If no tags have been added to the project, choose **Add tag**\. Otherwise, choose **Edit**, and then choose **Add tag**\. - -1. In **Key**, enter a name for the tag\. You can add an optional value for the tag in **Value**\. - -1. \(Optional\) To add another tag, choose **Add tag** again\. - -1. When you have finished adding tags, choose **Submit**\. - -## Add a tag to a project \(AWS CLI\) - -To add a tag to a project when you create it, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. In `create-project.json`, add your tags\. - -In these steps, we assume that you have already installed a recent version of the AWS CLI or updated to the current version\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)\. - -If successful, this command returns nothing\. \ 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 deleted file mode 100644 index bbecfc6..0000000 --- a/doc_source/how-to-tag-project-delete.md +++ /dev/null @@ -1,33 +0,0 @@ -# Remove a tag from a project - -You can remove one or more tags associated with a project\. Removing a tag does not delete the tag from other AWS resources that are associated with that tag\. - -**Important** -Removing tags for a project can impact access to that project\. Before you remove a tag from a project, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -## Remove a tag from a project \(console\) - -You can use the CodeBuild console to remove the association between a tag and a CodeBuild project\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Build projects**, choose the name of the project where you want to remove tags\. - -1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. - -1. Choose **Edit**\. - -1. Find the tag you want to remove, and then choose **Remove tag**\. - -1. When you have finished removing tags, choose **Submit**\. - -## 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-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: []" -``` - -**Note** -If you delete a CodeBuild build project, all tag associations are removed from the deleted build project\. You do not have to remove tags before you delete a build project\. \ No newline at end of file diff --git a/doc_source/how-to-tag-project-list.md b/doc_source/how-to-tag-project-list.md deleted file mode 100644 index 118d73c..0000000 --- a/doc_source/how-to-tag-project-list.md +++ /dev/null @@ -1,38 +0,0 @@ -# View tags for a project - -Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -## View tags for a project \(console\) - -You can use the CodeBuild console to view the tags associated with a CodeBuild project\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Build projects**, choose the name of the project where you want to view tags\. - -1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. - -## View tags for a project \(AWS CLI\) - -To view tags for a build project, run the following command\. Use the name of your project for the `--names` parameter\. - -``` -aws codebuild batch-get-projects --names your-project-name -``` - -If successful, this command returns JSON\-formatted information about your build project that includes something like the following: - -``` -{ - "tags": { - "Status": "Secret", - "Team": "JanesProject" - } -} -``` - -If the project does not have tags, the `tags` section is empty: - -``` -"tags": [] -``` \ No newline at end of file diff --git a/doc_source/how-to-tag-project-update.md b/doc_source/how-to-tag-project-update.md deleted file mode 100644 index 5c054c7..0000000 --- a/doc_source/how-to-tag-project-update.md +++ /dev/null @@ -1,28 +0,0 @@ -# Edit tags for a project - -You can change the value for a tag associated with a project\. You can also change the name of the key, which is equivalent to removing the current tag and adding a different one with the new name and the same value as the other key\. Keep in mind that there are limits on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. - -**Important** -Editing tags for a project can impact access to that project\. Before you edit the name \(key\) or value of a tag for a project, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as build projects\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -## Edit a tag for a project \(console\) - -You can use the CodeBuild console to edit the tags associated with a CodeBuild project\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Build projects**, choose the name of the project where you want to edit tags\. - -1. In the navigation pane, choose **Settings**\. Choose **Build project tags**\. - -1. Choose **Edit**\. - -1. Do one of the following: - + To change the tag, enter a new name in **Key**\. Changing the name of the tag is the equivalent of removing a tag and adding a new tag with the new key name\. - + To change the value of a tag, enter a new value\. If you want to change the value to nothing, delete the current value and leave the field blank\. - -1. When you have finished editing tags, choose **Submit**\. - -## 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-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/how-to-tag-project.md b/doc_source/how-to-tag-project.md deleted file mode 100644 index fc9344e..0000000 --- a/doc_source/how-to-tag-project.md +++ /dev/null @@ -1,17 +0,0 @@ -# Tagging projects in AWS CodeBuild - -A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Each AWS tag has two parts: -+ A *tag key* \(for example, `CostCenter`, `Environment`, `Project`, or `Secret`\)\. Tag keys are case sensitive\. -+ An optional field known as a *tag value* \(for example, `111122223333`, `Production`, or a team name\)\. Omitting the tag value is the same as using an empty string\. Like tag keys, tag values are case sensitive\. - -Together these are known as key\-value pairs\. For information about the number of tags you can have on a project and restrictions on tag keys and values, see [Tags](limits.md#tag-limits)\. - -Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild project that you assign to an S3 bucket\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. - -In CodeBuild, the primary resources are the project and the report group\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a project\. In addition to identifying, organizing, and tracking your project with tags, you can use tags in IAM policies to help control who can view and interact with your project\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -**Topics** -+ [Add a tag to a project](how-to-tag-project-add.md) -+ [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) \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-add.md b/doc_source/how-to-tag-report-group-add.md deleted file mode 100644 index 4d33edc..0000000 --- a/doc_source/how-to-tag-report-group-add.md +++ /dev/null @@ -1,38 +0,0 @@ -# Add a tag to a report group - -Adding tags to a report group can help you identify and organize your AWS resources and manage access to them\. First, you add one or more tags \(key\-value pairs\) to a report group\. Keep in mind that there are limits on the number of tags you can have on a report group\. There are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. After you have tags, you can create IAM policies to manage access to the report group based on these tags\. You can use the CodeBuild console or the AWS CLI to add tags to a report group\. - -**Important** -Adding tags to a report group can impact access to that report group\. Before you add a tag to a report group, make sure to review any IAM policies that might use tags to control access to resources such as report groups\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -For more information about adding tags to a report group when you create it, see [Create a report group \(console\)](test-report-group-create-console.md)\. - -**Topics** -+ [Add a tag to a report group \(console\)](#how-to-tag-report-group-add-console) -+ [Add a tag to a report group \(AWS CLI\)](#how-to-tag-report-group-add-cli) - -## Add a tag to a report group \(console\) - -You can use the CodeBuild console to add one or more tags to a CodeBuild report group\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Report groups**, choose the name of the report group where you want to add tags\. - -1. In the navigation pane, choose **Settings**\. - -1. If no tags have been added to the report group, choose **Add tag**\. You can also choose **Edit**, and then choose **Add tag**\. - -1. In **Key**, enter a name for the tag\. You can add an optional value for the tag in **Value**\. - -1. \(Optional\) To add another tag, choose **Add tag** again\. - -1. When you have finished adding tags, choose **Submit**\. - -## Add a tag to a report group \(AWS CLI\) - -To add a tag to a report group when you create it, see [Create a report group \(CLI\)](test-report-group-create-cli.md)\. In `CreateReportGroup.json`, add your tags\. - - To add tags to an existing report group, see [Update a report group \(CLI\)](update-report-group-cli.md) and add your tags in `UpdateReportGroupInput.json`\. - -In these steps, we assume that you have already installed a recent version of the AWS CLI or updated to the current version\. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)\. \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-delete.md b/doc_source/how-to-tag-report-group-delete.md deleted file mode 100644 index e766925..0000000 --- a/doc_source/how-to-tag-report-group-delete.md +++ /dev/null @@ -1,35 +0,0 @@ -# Remove a tag from a report group - -You can remove one or more tags associated with a report group\. Removing a tag does not delete the tag from other AWS resources that are associated with that tag\. - -**Important** -Removing tags for a report group can impact access to that report group\. Before you remove a tag from a report group, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as report groups\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -## Remove a tag from a report group \(console\) - -You can use the CodeBuild console to remove the association between a tag and a CodeBuild report group\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Report groups**, choose the name of the report group where you want to remove tags\. - -1. In the navigation pane, choose **Settings**\. - -1. Choose **Edit**\. - -1. Find the tag you want to remove, and then choose **Remove tag**\. - -1. When you have finished removing tags, choose **Submit**\. - -## Remove a tag from a report group \(AWS CLI\) - -Follow these steps to use the AWS CLI to remove a tag from a CodeBuild report group\. Removing a tag does not delete it, but simply removes the association between the tag and the report group\. - -**Note** -If you delete a CodeBuild report group, all tag associations are removed from the deleted report group\. You do not have to remove tags before you delete a report group\. - - To delete one or more tags from a report group, see [Edit tags for a report group \(AWS CLI\)](how-to-tag-report-group-update.md#how-to-tag-report-group-update-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: - -``` -"tags: []" -``` \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-list.md b/doc_source/how-to-tag-report-group-list.md deleted file mode 100644 index 124ffbe..0000000 --- a/doc_source/how-to-tag-report-group-list.md +++ /dev/null @@ -1,72 +0,0 @@ -# View tags for a report group - -Tags can help you identify and organize your AWS resources and manage access to them\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. - -## View tags for a report group \(console\) - -You can use the CodeBuild console to view the tags associated with a CodeBuild report group\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Report groups**, choose the name of the report group where you want to view tags\. - -1. In the navigation pane, choose **Settings**\. - -## View tags for a report group \(AWS CLI\) - -Follow these steps to use the AWS CLI to view the AWS tags for a report group\. If no tags have been added, the returned tags list is empty\. - -1. Use the console or the AWS CLI to locate the ARN of your report group\. Make a note of it\. - ------- -#### [ AWS CLI ] - - Run the following command\. - - ``` - aws list-report-groups - ``` - - This command returns JSON\-formatted information similar to the following: - - ``` - { - "reportGroups": [ - "arn:aws:codebuild:region:123456789012:report-group/report-group-1", - "arn:aws:codebuild:region:123456789012:report-group/report-group-2", - "arn:aws:codebuild:region:123456789012:report-group/report-group-3" - ] - } - ``` - - A report group ARN ends with its name, which you can use to identify the ARN for your report group\. - ------- -#### [ Console ] - - 1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - - 1. In **Report groups**, choose the name of your report group with the tags you want to view\. - - 1. In **Configuration** locate your report group's ARN\. - ------- - -1. Run the following command\. Use the ARN you made a note of for the `--report-group-arns` parameter\. - - ``` - aws codebuild batch-get-report-groups --report-group-arns arn:aws:codebuild:region:123456789012:report-group/report-group-name - ``` - - If successful, this command returns JSON\-formatted information that contains a `tags` section similar to the following: - - ``` - { - ... - "tags": { - "Status": "Secret", - "Project": "TestBuild" - } - ... - } - ``` \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group-update.md b/doc_source/how-to-tag-report-group-update.md deleted file mode 100644 index c8c898a..0000000 --- a/doc_source/how-to-tag-report-group-update.md +++ /dev/null @@ -1,28 +0,0 @@ -# Edit tags for a report group - -You can change the value for a tag associated with a report group\. You can also change the name of the key, which is equivalent to removing the current tag and adding a different one with the new name and the same value as the other key\. Keep in mind that there are restrictions on the characters you can use in the key and value fields\. For more information, see [Tags](limits.md#tag-limits)\. - -**Important** -Editing tags for a report group can impact access to that report group\. Before you edit the name \(key\) or value of a tag for a report group, make sure to review any IAM policies that might use the key or value for a tag to control access to resources such as report groups\. For examples of tag\-based access policies, see [Deny or allow actions on report groups based on resource tags](auth-and-access-control-using-tags.md#report-group-tag-policy-example)\. - -## Edit a tag for a report group \(console\) - -You can use the CodeBuild console to edit the tags associated with a CodeBuild report group\. - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In **Report groups**, choose the name of the report group where you want to edit tags\. - -1. In the navigation pane, choose **Settings**\. - -1. Choose **Edit**\. - -1. Do one of the following: - + To change the tag, enter a new name in **Key**\. Changing the name of the tag is the equivalent of removing a tag and adding a new tag with the new key name\. - + To change the value of a tag, enter a new value\. If you want to change the value to nothing, delete the current value and leave the field blank\. - -1. When you have finished editing tags, choose **Submit**\. - -## Edit tags for a report group \(AWS CLI\) - - To add, change, or delete tags from a report group, see [Update a report group \(CLI\)](update-report-group-cli.md)\. Update the tags in `UpdateReportGroupInput.json`\. \ No newline at end of file diff --git a/doc_source/how-to-tag-report-group.md b/doc_source/how-to-tag-report-group.md deleted file mode 100644 index d41d1c7..0000000 --- a/doc_source/how-to-tag-report-group.md +++ /dev/null @@ -1,17 +0,0 @@ -# Tagging report groups in AWS CodeBuild - -A *tag* is a custom attribute label that you or AWS assigns to an AWS resource\. Each AWS tag has two parts: -+ A *tag key* \(for example, `CostCenter`, `Environment`, `Project`, or `Secret`\)\. Tag keys are case sensitive\. -+ An optional field known as a *tag value* \(for example, `111122223333`, `Production`, or a team name\)\. Omitting the tag value is the same as using an empty string\. Like tag keys, tag values are case sensitive\. - -Together these are known as key\-value pairs\. For limits on the number of tags you can have on a report group and restrictions on tag keys and values, see [Tags](limits.md#tag-limits)\. - -Tags help you identify and organize your AWS resources\. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related\. For example, you can assign the same tag to a CodeBuild report group that you assign to an Amazon S3 bucket\. For more information about using tags, see the [Tagging best practices](https://d1.awsstatic.com/whitepapers/aws-tagging-best-practices.pdf) whitepaper\. - -In CodeBuild, the primary resources are the report group and the project\. You can use the CodeBuild console, the AWS CLI, CodeBuild APIs, or AWS SDKs to add, manage, and remove tags for a report group\. In addition to identifying, organizing, and tracking your report group with tags, you can use tags in IAM policies to help control who can view and interact with your report group\. For examples of tag\-based access policies, see [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md)\. - -**Topics** -+ [Add a tag to a report group](how-to-tag-report-group-add.md) -+ [View tags for a report group](how-to-tag-report-group-list.md) -+ [Edit tags for a report group](how-to-tag-report-group-update.md) -+ [Remove a tag from a report group](how-to-tag-report-group-delete.md) \ No newline at end of file diff --git a/doc_source/index.md b/doc_source/index.md deleted file mode 100644 index 6c66743..0000000 --- a/doc_source/index.md +++ /dev/null @@ -1,197 +0,0 @@ -# AWS CodeBuild User Guide - ------ -*****Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.***** - ------ -Amazon's trademarks and trade dress may not be used in - connection with any product or service that is not Amazon's, - in any manner that is likely to cause confusion among customers, - or in any manner that disparages or discredits Amazon. All other - trademarks not owned by Amazon are the property of their respective - owners, who may or may not be affiliated with, connected to, or - sponsored by Amazon. - ------ -## Contents -+ [What is AWS CodeBuild?](welcome.md) - + [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 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 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 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 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) - + [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) - + [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) - + [Create a test report in CodeBuild using the AWS CLI sample](sample-test-report-cli.md) - + [Docker in custom image sample for CodeBuild](sample-docker-custom-image.md) - + [Docker sample for CodeBuild](sample-docker.md) - + [GitHub Enterprise Server sample for CodeBuild](sample-github-enterprise.md) - + [GitHub pull request and webhook filter sample for CodeBuild](sample-github-pull-request.md) - + [Create a static website with build output hosted in an S3 bucket](sample-disable-artifact-encryption.md) - + [Runtime versions in buildspec file sample for CodeBuild](sample-runtime-versions.md) - + [Source version sample with AWS CodeBuild](sample-source-version.md) - + [Private registry with AWS Secrets Manager sample for CodeBuild](sample-private-registry.md) - + [Multiple input sources and output artifacts sample](sample-multi-in-out.md) - + [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) - + [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) -+ [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) - + [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) - + [Create a notification rule](notification-rule-create.md) - + [View a list of build project names in AWS CodeBuild](view-project-list.md) - + [View a build project's details in AWS CodeBuild](view-project-details.md) - + [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) - + [Add a tag to a project](how-to-tag-project-add.md) - + [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) - + [View build details in AWS CodeBuild](view-build-details.md) - + [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) - + [Create a test report](report-create.md) - + [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 (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) - + [Update a report group (CLI)](update-report-group-cli.md) - + [Specify test files](report-group-test-cases.md) - + [Specify test commands](report-group-test-case-commands.md) - + [Report group naming](test-report-group-naming.md) - + [Tagging report groups in AWS CodeBuild](how-to-tag-report-group.md) - + [Add a tag to a report group](how-to-tag-report-group-add.md) - + [View tags for a report group](how-to-tag-report-group-list.md) - + [Edit tags for a report group](how-to-tag-report-group-update.md) - + [Remove a tag from a report group](how-to-tag-report-group-delete.md) - + [Working with shared report groups](report-groups-sharing.md) - + [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) - + [Set up test reporting with Jasmine](test-report-jasmine.md) - + [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) - + [Monitoring CodeBuild metrics](monitoring-metrics.md) - + [Monitoring CodeBuild resource utilization metrics](monitoring-utilization-metrics.md) - + [Monitoring builds with CloudWatch alarms](monitoring-alarms.md) -+ [Security in AWS CodeBuild](security.md) - + [Data protection in AWS CodeBuild](data-protection.md) - + [Data encryption](security-encryption.md) - + [Key management](security-key-management.md) - + [Traffic privacy](security-traffic-privacy.md) - + [Identity and access management in AWS CodeBuild](auth-and-access-control.md) - + [Overview of managing access permissions to your AWS CodeBuild resources](auth-and-access-control-iam-access-control-identity-based.md) - + [Using identity-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md) - + [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md) - + [Using tags to control access to AWS CodeBuild resources](auth-and-access-control-using-tags.md) - + [Viewing resources in the console](console-resources.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) - + [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) -+ [AWS CodeBuild User Guide document history](history.md) -+ [AWS glossary](glossary.md) \ No newline at end of file diff --git a/doc_source/infrastructure-security.md b/doc_source/infrastructure-security.md deleted file mode 100644 index 45786b0..0000000 --- a/doc_source/infrastructure-security.md +++ /dev/null @@ -1,7 +0,0 @@ -# Infrastructure security in AWS CodeBuild - -As a managed service, AWS CodeBuild is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of security processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper\. - -You use AWS published API calls to access CodeBuild through the network\. Clients must support Transport Layer Security \(TLS\) 1\.0 or later\. We recommend TLS 1\.2 or later\. Clients must also support cipher suites with perfect forward secrecy \(PFS\) such as Ephemeral Diffie\-Hellman \(DHE\) or Elliptic Curve Ephemeral Diffie\-Hellman \(ECDHE\)\. Most modern systems such as Java 7 and later support these modes\. - -Requests must be signed by using an access key ID and a secret access key that is associated with an IAM principal\. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) \(AWS STS\) to generate temporary security credentials to sign requests\. \ No newline at end of file diff --git a/doc_source/jenkins-plugin.md b/doc_source/jenkins-plugin.md deleted file mode 100644 index d6d1413..0000000 --- a/doc_source/jenkins-plugin.md +++ /dev/null @@ -1,81 +0,0 @@ -# Use AWS CodeBuild with Jenkins - -You can use the Jenkins plugin for AWS CodeBuild to integrate CodeBuild with your Jenkins build jobs\. Instead of sending your build jobs to Jenkins build nodes, you use the plugin to send your build jobs to CodeBuild\. This eliminates the need for you to provision, configure, and manage Jenkins build nodes\. - -## Setting up Jenkins - -For information about setting up Jenkins with the AWS CodeBuild plugin, and to download the plugin source code, see [ https://github\.com/awslabs/aws\-codebuild\-jenkins\-plugin](https://github.com/awslabs/aws-codebuild-jenkins-plugin)\. - -## Installing the plugin - -If you already have a Jenkins server set up and would like to only install the AWS CodeBuild plugin, on your Jenkins instance, in the Plugin Manager, search for **CodeBuild Plugin for Jenkins**\. - -## Using the plugin - -**To use AWS CodeBuild with sources from outside of a VPC** - -1. Create a project in the CodeBuild console\. For more information, see [Create a build project \(console\)](create-project-console.md)\. - + Choose the AWS Region where you want to run the build\. - + \(Optional\) Set the Amazon VPC configuration to allow the CodeBuild build container to access resources in your VPC\. - + Write down the name of your project\. You need it in step 3\. - + \(Optional\) If your source repository is not natively supported by CodeBuild, you can set Amazon S3 as the input source type for your project\. - -1. In the IAMconsole, create an IAM user to be used by the Jenkins plugin\. - + When you create credentials for the user, choose **Programmatic Access**\. - + Create a policy similar to the following and then attach the policy to your user\. - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Resource": ["arn:aws:logs:{{region}}:{{awsAccountId}}:log-group:/aws/codebuild/{{projectName}}:*"], - "Action": ["logs:GetLogEvents"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:s3:::{{inputBucket}}"], - "Action": ["s3:GetBucketVersioning"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:s3:::{{inputBucket}}/{{inputObject}}"], - "Action": ["s3:PutObject"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:s3:::{{outputBucket}}/*"], - "Action": ["s3:GetObject"] - }, - { - "Effect": "Allow", - "Resource": ["arn:aws:codebuild:{{region}}:{{awsAccountId}}:project/{{projectName}}"], - "Action": ["codebuild:StartBuild", - "codebuild:BatchGetBuilds", - "codebuild:BatchGetProjects"] - } - ] - } - ``` - -1. Create a freestyle project in Jenkins\. - + On the **Configure** page, choose **Add build step**, and then choose **Run build on CodeBuild**\. - + Configure your build step\. - + Provide values for **Region**, **Credentials**, and **Project Name**\. - + Choose **Use Project source**\. - + Save the configuration and run a build from Jenkins\. - -1. For **Source Code Management**, choose how you want to retrieve your source\. You might need to install the GitHub plugin \(or the Jenkins plugin for your source repository provider\) on your Jenkins server\. - + On the **Configure** page, choose **Add build step**, and then choose **Run build on AWS CodeBuild**\. - + Configure your build step\. - + Provide values for **Region**, **Credentials**, and **Project Name**\. - + Choose **Use Jenkins source**\. - + Save the configuration and run a build from Jenkins\. - -**To use the AWS CodeBuild plugin with the Jenkins pipeline plugin** -+ On your Jenkins pipeline project page, use the snippet generator to generate a pipeline script that adds CodeBuild as a step in your pipeline\. It should generate a script similar to this: - - ``` - awsCodeBuild projectName: 'project', credentialsType: 'keys', region: 'us-west-2', sourceControlType: 'jenkins' - ``` \ No newline at end of file diff --git a/doc_source/limits.md b/doc_source/limits.md deleted file mode 100644 index 5ddb5c5..0000000 --- a/doc_source/limits.md +++ /dev/null @@ -1,62 +0,0 @@ -# Quotas for AWS CodeBuild - -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\. - -## 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 - - -**** - -| Resource | Default | -| --- | --- | -| Allowed characters in a build project description | Any | -| 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 reports you can add to a project | 5 | -| Number of minutes you can specify in a build project for the build timeout of all related builds | 5 to 480 \(8 hours\) | - -### Builds - - -**** - -| Resource | Default | -| --- | --- | -| 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\) | - -### Reports - - -**** - -| Resource | Default | -| --- | --- | -| Maximum duration a test report is available after it is created | 30 days | -| 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 - -Tag limits apply to tags on CodeBuild build projects and CodeBuild report group resources\. - - -**** - -| Resource | Default | -| --- | --- | -| 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/logging-monitoring.md b/doc_source/logging-monitoring.md deleted file mode 100644 index 5991e0b..0000000 --- a/doc_source/logging-monitoring.md +++ /dev/null @@ -1,7 +0,0 @@ -# Logging and monitoring in AWS CodeBuild - - Monitoring is an important part of maintaining the reliability, availability, and performance of AWS CodeBuild and your AWS solutions\. You should collect monitoring data from all of the parts of your AWS solution so that you can more easily debug a multi\-point failure, if one occurs\. AWS provides the following tools for monitoring your CodeBuild resources and builds and for responding to potential incidents\. - -**Topics** -+ [Logging AWS CodeBuild API calls with AWS CloudTrail](cloudtrail.md) -+ [Monitoring AWS CodeBuild](monitoring-builds.md) \ No newline at end of file diff --git a/doc_source/monitoring-alarms.md b/doc_source/monitoring-alarms.md deleted file mode 100644 index 2bd8d02..0000000 --- a/doc_source/monitoring-alarms.md +++ /dev/null @@ -1,21 +0,0 @@ -# Monitoring builds with CloudWatch alarms - - You can create a CloudWatch alarm for your builds\. An alarm watches a single metric over a period of time that you specify and performs one or more actions based on the value of the metric relative to a specified threshold over a number of time periods\. Using native CloudWatch alarm functionality, you can specify any of the actions supported by CloudWatch when a threshold is exceeded\. For example, you can specify that an Amazon SNS notification is sent when more than three builds in your account fail within fifteen minutes\. - -**To create a CloudWatch alarm for a CodeBuild metric** - -1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. - -1. In the navigation pane, choose **Alarms**\. - -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**\. - -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**\. - -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*\. - -1. Choose **Create Alarm**\. \ No newline at end of file diff --git a/doc_source/monitoring-builds.md b/doc_source/monitoring-builds.md deleted file mode 100644 index 8cef7f1..0000000 --- a/doc_source/monitoring-builds.md +++ /dev/null @@ -1,162 +0,0 @@ -# Monitoring AWS CodeBuild - -You can use Amazon CloudWatch to watch your builds, report when something is wrong, and take automatic actions when appropriate\. You can monitor your builds at two levels: - -Project level -These metrics are for all builds in the specified project\. To see metrics for a project, specify `ProjectName` for the dimension in CloudWatch\. - -AWS account level -These metrics are for all builds in an account\. To see metrics at the AWS account level, do not enter a dimension in CloudWatch\. Build resource utilization metrics are not available at the AWS account level\. - -CloudWatch metrics show the behavior of your builds over time\. For example, you can monitor: -+ 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 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)\. - -## CodeBuild CloudWatch metrics - - The following metrics can be tracked per AWS account or build project\. - -BuildDuration -Measures the duration of the build's `BUILD` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -Builds - Measures the number of builds triggered\. - Units: Count - Valid CloudWatch statistics: Sum - -DownloadSourceDuration -Measures the duration of the build's `DOWNLOAD_SOURCE` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -Duration - Measures the duration of all builds over time\. - Units: Seconds - Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -FailedBuilds - Measures the number of builds that failed because of client error or a timeout\. - Units: Count - Valid CloudWatch statistics: Sum - -FinalizingDuration -Measures the duration of the build's `FINALIZING` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -InstallDuration -Measures the duration of the build's `INSTALL` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -PostBuildDuration -Measures the duration of the build's `POST_BUILD` phase -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -PreBuildDuration -Measures the duration of the build's `PRE_BUILD` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -ProvisioningDuration -Measures the duration of the build's `PROVISIONING` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -QueuedDuration -Measures the duration of the build's `QUEUED` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -SubmittedDuration -Measures the duration of the build's `SUBMITTED` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -SucceededBuilds - Measures the number of successful builds\. - Units: Count - Valid CloudWatch statistics: Sum - -UploadArtifactsDuration -Measures the duration of the build's `UPLOAD_ARTIFACTS` phase\. -Units: Seconds -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -## CodeBuild CloudWatch resource utilization metrics - -**Note** -CodeBuild resource utilization metrics are only available in the following regions: -Asia Pacific \(Tokyo\) Region -Asia Pacific \(Seoul\) Region -Asia Pacific \(Mumbai\) Region -Asia Pacific \(Singapore\) Region -Asia Pacific \(Sydney\) Region -Canada \(Central\) Region -Europe \(Frankfurt\) Region -Europe \(Ireland\) Region -Europe \(London\) Region -Europe \(Paris\) Region -South America \(São Paulo\) Region -US East \(N\. Virginia\) Region -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 -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -CPUUtilizedPercent -The percentage of allocated processing used by the build container\. -Units: Percent -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -MemoryUtilized -The number of megabytes of memory used by the build container\. -Units: Megabytes -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -MemoryUtilizedPercent -The percentage of allocated memory used by the build container\. -Units: Percent -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -StorageReadBytes -The storage read speed used by the build container\. -Units: Bytes/second -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -StorageWriteBytes -The storage write speed used by the build container\. -Units: Bytes/second -Valid CloudWatch statistics: Average \(recommended\), Maximum, Minimum - -## CodeBuild CloudWatch dimensions - -CodeBuild provides the following CloudWatch metric dimensions\. If none of these are specified, the metrics are for the current AWS account\. - -BuildId, BuildNumber, ProjectName -Metrics are provided for a build identifier, build number, and project name\. - -ProjectName -Metrics are provided for a project name\. - -## CodeBuild CloudWatch alarms - - You can use the CloudWatch console to create alarms based on CodeBuild metrics so you can react if something goes wrong with your builds\. The two metrics that are most useful with alarms are: -+ `FailedBuild`\. You can create an alarm that is triggered when a certain number of failed builds are detected within a predetermined number of seconds\. In CloudWatch, you specify the number of seconds and how many failed builds trigger an alarm\. -+ `Duration`\. You can create an alarm that is triggered when a build takes longer than expected\. You specify how many seconds must elapse after a build is started and before a build is completed before the alarm is triggered\. - - For information about how to create alarms for CodeBuild metrics, see [Monitoring builds with CloudWatch alarms](monitoring-alarms.md)\. For more information about alarms, see [Creating Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/monitoring-metrics.md b/doc_source/monitoring-metrics.md deleted file mode 100644 index 54c47c0..0000000 --- a/doc_source/monitoring-metrics.md +++ /dev/null @@ -1,72 +0,0 @@ -# Monitoring CodeBuild metrics - - AWS CodeBuild monitors functions on your behalf and reports metrics through Amazon CloudWatch\. These metrics include the number of total builds, failed builds, successful builds, and the duration of builds\. - - You can use the CodeBuild console or the CloudWatch console to monitor metrics for CodeBuild\. The following procedures show you how to access metrics\. - -**Topics** -+ [Access build metrics \(CodeBuild console\)](#metrics-in-codebuild-console) -+ [Access build metrics \(Amazon CloudWatch console\)](#metrics-in-cloudwatch-console) - -## Access build metrics \(CodeBuild console\) - -**Note** -You can't customize the metrics or the graphs used to display them in the CodeBuild console\. If you want to customize the display, use the Amazon CloudWatch console to view your build metrics\. - -### Account\-level metrics - -**To access AWS account\-level metrics** - -1. Sign in to the AWS Management Console and 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 **Account metrics**\. - -### Project\-level metrics - -**To access project\-level metrics** - -1. Sign in to the AWS Management Console and 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. In the list of build projects, in the **Name** column, choose the project where you want to view metrics\. - -1. Choose the **Metrics** tab\. - -## Access build metrics \(Amazon CloudWatch console\) - -You can customize the metrics and the graphs used to display them with the CloudWatch console\. - -### Account\-level metrics - -**To access account\-level metrics** - -1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. - -1. In the navigation pane, choose **Metrics**\. - -1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-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 **Account Metrics**\. - -1. Choose one or more projects and metrics\. For each project, you can choose the **SucceededBuilds**, **FailedBuilds**, **Builds**, and **Duration** metrics\. All selected project and metric combinations are displayed in the graph on the page\. - -### Project\-level metrics - -**To access project\-level metrics** - -1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. - -1. In the navigation pane, choose **Metrics**\. - -1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-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 **By Project**\. - -1. Choose one or more project and metric combinations\. For each project, you can choose the **SucceededBuilds**, **FailedBuilds**, **Builds**, and **Duration** metrics\. All selected project and metric combinations are displayed in the graph on the page\. - -1. \(Optional\) You can customize your metrics and graphs\. For example, from the drop\-down list in the **Statistic** column, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. - - For more information, see [Graph metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [View available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/monitoring-utilization-metrics.md b/doc_source/monitoring-utilization-metrics.md deleted file mode 100644 index 461eb5c..0000000 --- a/doc_source/monitoring-utilization-metrics.md +++ /dev/null @@ -1,107 +0,0 @@ -# Monitoring CodeBuild resource utilization metrics - -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\. - -**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: -Asia Pacific \(Tokyo\) Region -Asia Pacific \(Seoul\) Region -Asia Pacific \(Mumbai\) Region -Asia Pacific \(Singapore\) Region -Asia Pacific \(Sydney\) Region -Canada \(Central\) Region -Europe \(Frankfurt\) Region -Europe \(Ireland\) Region -Europe \(London\) Region -Europe \(Paris\) Region -South America \(São Paulo\) Region -US East \(N\. Virginia\) Region -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) - -## Access resource utilization metrics \(CodeBuild console\) - -**Note** -You can't customize the metrics or the graphs used to display them in the CodeBuild console\. If you want to customize the display, use the Amazon CloudWatch console to view your build metrics\. - -### Project\-level resource utilization metrics - -**To access project\-level resource utilization metrics** - -1. Sign in to the AWS Management Console and 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. In the list of build projects, in the **Name** column, choose the project you want to view the utilization metrics for\. - -1. Choose the **Metrics** tab\. The resource utilization metrics are displayed in the **Resource utilization metrics** section\. - -1. To view the project\-level resource utilization metrics in the CloudWatch console, choose **View in CloudWatch** in the **Resource utilization metrics** section\. - -### Build\-level resource utilization metrics - -**To access build\-level resource utilization metrics** - -1. Sign in to the AWS Management Console and 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 history**\. - -1. In the list of builds, in the **Build run** column, choose the build you want to view the utilization metrics for\. - -1. Choose the **Resource utilization** tab\. - -1. To view the build\-level resource utilization metrics in the CloudWatch console, choose **View in CloudWatch** in the **Resource utilization metrics** section\. - -## Access resource utilization metrics \(Amazon CloudWatch console\) - -The Amazon CloudWatch console can be used to access CodeBuild resource utilization metrics\. - -### Project\-level resource utilization metrics - -**To access project\-level resource utilization metrics** - -1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. - -1. In the navigation pane, choose **Metrics**\. - -1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. Choose **By Project**\. - -1. Choose one or more project and metric combinations to add to the graph\. All selected project and metric combinations are displayed in the graph on the page\. - -1. \(Optional\) You can customize your metrics and graphs from the **Graphed metrics** tab\. For example, from the drop\-down list in the **Statistic** column, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. - - For more information, see [Graphing metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [Viewing available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. - -### Build\-level resource utilization metrics - -**To access build\-level resource utilization metrics** - -1. Sign in to the AWS Management Console and open the CloudWatch console at [https://console\.aws\.amazon\.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)\. - -1. In the navigation pane, choose **Metrics**\. - -1. On the **All metrics** tab, choose **CodeBuild**\. -![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-metrics-in-cw.png)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Console screenshot showing the CodeBuild option located on the All metrics tab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. Choose **BuildId, BuildNumber, ProjectName**\. - -1. Choose one or more build and metric combinations to add to the graph\. All selected build and metric combinations are displayed in the graph on the page\. - -1. \(Optional\) You can customize your metrics and graphs from the **Graphed metrics** tab\. For example, from the drop\-down list in the **Statistic** column, you can choose a different statistic to display\. Or from the drop\-down menu in the **Period** column, you can choose a different time period to use to monitor the metrics\. - - For more information, see [Graphing metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph_metrics.html) and [Viewing available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the *Amazon CloudWatch User Guide*\. \ No newline at end of file diff --git a/doc_source/notice.md b/doc_source/notice.md deleted file mode 100644 index 30b657e..0000000 --- a/doc_source/notice.md +++ /dev/null @@ -1,389 +0,0 @@ -# Third party notices for AWS CodeBuild for Windows - -When you use CodeBuild for Windows builds, you have the option to use some third party packages and modules to enable your built application to run on Microsoft Windows operating systems and to interoperate with some third party products\. The following list contains the applicable third\-party legal terms that govern your use of the specified third\-party packages and modules\. - -**Topics** -+ [1\) base Docker image—windowsservercore](#base-docker-image) -+ [2\) windows\-base Docker image—choco](#3-windows-base-docker-image) -+ [3\) windows\-base Docker image—git \-\-version 2\.16\.2](#4-windows-base-docker-image-2-16-2) -+ [4\) windows\-base Docker image—microsoft\-build\-tools \-\-version 15\.0\.26320\.2](#5-windows-base-docker-image-15-x) -+ [5\) windows\-base Docker image—nuget\.commandline \-\-version 4\.5\.1](#6-windows-base-docker-image-4-5-1) -+ [7\) windows\-base Docker image—netfx\-4\.6\.2\-devpack](#7-windows-base-docker-image-4-6-2) -+ [8\) windows\-base Docker image—visualfsharptools, v 4\.0](#8-windows-base-docker-image-visualfsharptools) -+ [9\) windows\-base Docker image—netfx\-pcl\-reference\-assemblies\-4\.6](#9-windows-base-docker-image) -+ [10\) windows\-base Docker image—visualcppbuildtools v 14\.0\.25420\.1](#10-windows-base-docker-image) -+ [11\) windows\-base Docker image—microsoft\-windows\-netfx3\-ondemand\-package\.cab](#11-windows-base-docker-image) -+ [12\) windows\-base Docker image—dotnet\-sdk](#12-windows-base-docker-image) - -## 1\) base Docker image—windowsservercore - -\(license terms available at: [https://hub\.docker\.com/r/microsoft/windowsservercore/\)](https://hub.docker.com/r/microsoft/windowsservercore/) - -License: By requesting and using this Container OS Image for Windows containers, you acknowledge, understand, and consent to the following Supplemental License Terms: - -MICROSOFT SOFTWARE SUPPLEMENTAL LICENSE TERMS - -CONTAINER OS IMAGE - -Microsoft Corporation \(or based on where you live, one of its affiliates\) \(referenced as "us," "we," or "Microsoft"\) licenses this Container OS Image supplement to you \("Supplement"\)\. You are licensed to use this Supplement in conjunction with the underlying host operating system software \("Host Software"\) solely to assist running the containers feature in the Host Software\. The Host Software license terms apply to your use of the Supplement\. You may not use it if you do not have a license for the Host Software\. You may use this Supplement with each validly licensed copy of the Host Software\. - -ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS - -Your use of the Supplement as specified in the preceding paragraph may result in the creation or modification of a container image \("Container Image"\) that includes certain Supplement components\. For clarity, a Container Image is separate and distinct from a virtual machine or virtual appliance image\. Pursuant to these license terms, we grant you a restricted right to redistribute such Supplement components under the following conditions: - -\(i\) you may use the Supplement components only as used in, and as a part of your Container Image, - -\(ii\) you may use such Supplement components in your Container Image as long as you have significant primary functionality in your Container Image that is materially separate and distinct from the Supplement; and - -\(iii\) you agree to include these license terms \(or similar terms required by us or a hoster\) with your Container Image to properly license the possible use of the Supplement components by your end\-users\. - -We reserve all other rights not expressly granted herein\. - -By using this Supplement, you accept these terms\. If you do not accept them, do not use this Supplement\. - -As part of the Supplemental License Terms for this Container OS Image for Windows containers, you are also subject to the underlying Windows Server host software license terms, which are located at: [https://www\.microsoft\.com/en\-us/useterms\.](https://www.microsoft.com/en-us/useterms) - -## 2\) windows\-base Docker image—choco - -\(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 - -Licensed under the Apache License, version 2\.0 \(the "License"\); you may not use these files except in compliance with the License\. You may obtain a copy of the License at - -[http://www\.apache\.org/licenses/LICENSE\-2\.0](http://www.apache.org/licenses/LICENSE-2.0) - -Unless required by applicable law or as agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\. See the License for the specific language governing permissions and limitations under the License\. - -## 3\) windows\-base Docker image—git \-\-version 2\.16\.2 - -\(license terms available at: [https://chocolatey\.org/packages/git/2\.16\.2](https://chocolatey.org/packages/git/2.16.2)\) - -Licensed under GNU General Public License, version 2, available at: [https://www\.gnu\.org/licenses/old\-licenses/gpl\-2\.0\.html](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html)\. - -## 4\) windows\-base Docker image—microsoft\-build\-tools \-\-version 15\.0\.26320\.2 - -\(license terms available at: [https://www\.visualstudio\.com/license\-terms/mt171552/](https://www.visualstudio.com/license-terms/mt171552/)\) - -MICROSOFT VISUAL STUDIO 2015 EXTENSIONS, VISUAL STUDIO SHELLS and C\+\+ REDISTRIBUTABLE - -\-\-\-\-\- - -These license terms are an agreement between Microsoft Corporation \(or based on where you live, one of its affiliates\) and you\. They apply to the software named above\. The terms also apply to any Microsoft services or updates for the software, except to the extent those have additional terms\. - -\-\-\-\-\- - -IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW\. - -1. **INSTALLATION AND USE RIGHTS**\. You may install and use any number of copies of the software\. - -1. **TERMS FOR SPECIFIC COMPONENTS**\. - - 1. **Utilities**\. The software may contain some items on the Utilities List at [https://docs\.microsoft\.com/en\-us/visualstudio/productinfo/2015\-redistribution\-vs](https://docs.microsoft.com/en-us/visualstudio/productinfo/2015-redistribution-vs)\. You may copy and install those items, if included with the software, on to yours or other third party machines, to debug and deploy your applications and databases you developed with the software\. Please note that Utilities are designed for temporary use, that Microsoft may not be able to patch or update Utilities separately from the rest of the software, and that some Utilities by their nature may make it possible for others to access machines on which they are installed\. As a result, you should delete all Utilities you have installed after you finish debugging or deploying your applications and databases\. Microsoft is not responsible for any third party use or access of Utilities you install on any machine\. - - 1. **Microsoft Platforms**\. The software may include components from Microsoft Windows; Microsoft Windows Server; Microsoft SQL Server; Microsoft Exchange; Microsoft Office; and Microsoft SharePoint\. These components are governed by separate agreements and their own product support policies, as described in the license terms found in the installation directory for that component or in the "Licenses" folder accompanying the software\. - - 1. **Third Party Components**\. The software may include third party components with separate legal notices or governed by other agreements, as described in the ThirdPartyNotices file accompanying the software\. Even if such components are governed by other agreements, the disclaimers and the limitations on and exclusions of damages below also apply\. The software may also include components licensed under open source licenses with source code availability obligations\. Copies of those licenses, if applicable, are included in the ThirdPartyNotices file\. You may obtain this source code from us, if and as required under the relevant open source licenses, by sending a money order or check for $5\.00 to: Source Code Compliance Team, Microsoft Corporation, 1 Microsoft Way, Redmond, WA 98052\. Please write source code for one or more of the components listed below in the memo line of your payment: - + Remote Tools for Visual Studio 2015; - + Standalone Profiler for Visual Studio 2015; - + IntelliTraceCollector for Visual Studio 2015; - + Microsoft VC\+\+ Redistributable 2015; - + Multibyte MFC Library for Visual Studio 2015; - + Microsoft Build Tools 2015; - + Feedback Client; - + Visual Studio 2015 Integrated Shell; or - + Visual Studio 2015 Isolated Shell\. - - We may also make a copy of the source code available at [http://thirdpartysource\.microsoft\.com](http://thirdpartysource.microsoft.com)\. - -1. **DATA**\. The software may collect information about you and your use of the software, and send that to Microsoft\. Microsoft may use this information to provide services and improve our products and services\. You may opt\-out of many of these scenarios, but not all, as described in the product documentation\. There are also some features in the software that may enable you to collect data from users of your applications\. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications\. You can learn more about data collection and use in the help documentation and the privacy statement at [https://privacy\.microsoft\.com/en\-us/privacystatement](https://privacy.microsoft.com/en-us/privacystatement)\. Your use of the software operates as your consent to these practices\. - -1. **SCOPE OF LICENSE**\. The software is licensed, not sold\. This agreement only gives you some rights to use the software\. Microsoft reserves all other rights\. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement\. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways\. You may not - + work around any technical limitations in the software; - + reverse engineer, decompile or disassemble the software, or attempt to do so, except and only to the extent required by third party licensing terms governing the use of certain open\-source components that may be included with the software; - + remove, minimize, block or modify any notices of Microsoft or its suppliers in the software; - + use the software in any way that is against the law; or - + share, publish, rent or lease the software, or provide the software as a stand\-alone hosted as solution for others to use\. - -1. **EXPORT RESTRICTIONS**\. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use\. For further information on export restrictions, visit \(aka\.ms/exporting\)\. - -1. **SUPPORT SERVICES**\. Because this software is "as is," we may not provide support services for it\. - -1. **ENTIRE AGREEMENT**\. This agreement, and the terms for supplements, updates, Internet\-based services and support services that you use, are the entire agreement for the software and support services\. - -1. **APPLICABLE LAW**\. If you acquired the software in the United States, Washington law applies to interpretation of and claims for breach of this agreement, and the laws of the state where you live apply to all other claims\. If you acquired the software in any other country, its laws apply\. - -1. **CONSUMER RIGHTS; REGIONAL VARIATIONS**\. This agreement describes certain legal rights\. You may have other rights, including consumer rights, under the laws of your state or country\. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software\. This agreement does not change those other rights if the laws of your state or country do not permit it to do so\. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you: - - 1. **Australia**\. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights\. - - 1. **Canada**\. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet \(if and when you re\-connect to the Internet, however, the software will resume checking for and installing updates\), or uninstalling the software\. The product documentation, if any, may also specify how to turn off updates for your specific device or software\. - - 1. **Germany and Austria**\. - - 1. **Warranty**\. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software\. However, Microsoft gives no contractual guarantee in relation to the licensed software\. - - 1. **Limitation of Liability**\. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law\.Subject to the foregoing clause \(ii\), Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in \(so\-called "cardinal obligations"\)\. In other cases of slight negligence, Microsoft will not be liable for slight negligence\. - -1. **DISCLAIMER OF WARRANTY\. THE SOFTWARE IS LICENSED “AS\-IS\.” YOU BEAR THE RISK OF USING IT\. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES OR CONDITIONS\. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT EXCLUDES THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON\-INFRINGEMENT\.** - -1. **LIMITATION ON AND EXCLUSION OF DAMAGES\. YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U\.S\. $5\.00\. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES\.** This limitation applies to \(a\) anything related to the software, services, content \(including code\) on third party Internet sites, or third party applications; and \(b\) claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law\. - - It also applies even if Microsoft knew or should have known about the possibility of the damages\. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages\. - -EULA ID: VS2015\_Update3\_ShellsRedist\_ - -## 5\) windows\-base Docker image—nuget\.commandline \-\-version 4\.5\.1 - -\(license terms available at: [https://github\.com/NuGet/Home/blob/dev/LICENSE\.txt](https://github.com/NuGet/Home/blob/dev/LICENSE.txt)\) - -Copyright \(c\) \.NET Foundation\. All rights reserved\. - -Licensed under the Apache License, version 2\.0 \(the "License"\); you may not use these files except in compliance with the License\. You may obtain a copy of the License at - -[http://www\.apache\.org/licenses/LICENSE\-2\.0](http://www.apache.org/licenses/LICENSE-2.0) - -Unless required by applicable law or as agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\. See the License for the specific language governing permissions and limitations under the License\. - -## 7\) windows\-base Docker image—netfx\-4\.6\.2\-devpack - -**MICROSOFT SOFTWARE SUPPLEMENTAL LICENSE TERMS** - -**\.NET FRAMEWORK AND ASSOCIATED LANGUAGE PACKS FOR MICROSOFT WINDOWS OPERATING SYSTEM** - -\-\-\-\-\- - -Microsoft Corporation \(or based on where you live, one of its affiliates\) licenses this supplement to you\. If you are licensed to use Microsoft Windows operating system software \(the "software"\), you may use this supplement\. You may not use it if you do not have a license for the software\. You may use this supplement with each validly licensed copy of the software\. - -The following license terms describe additional use terms for this supplement\. These terms and the license terms for the software apply to your use of the supplement\. If there is a conflict, these supplemental license terms apply\. - -**BY USING THIS SUPPLEMENT, YOU ACCEPT THESE TERMS\. IF YOU DO NOT ACCEPT THEM, DO NOT USE THIS SUPPLEMENT\.** - -\-\-\-\-\- - -**If you comply with these license terms, you have the rights below\.** - -1. **DISTRIBUTABLE CODE\. ** The supplement is comprised of Distributable Code\. "Distributable Code" is code that you are permitted to distribute in programs you develop if you comply with the terms below\. - - 1. **Right to Use and Distribute**\. - + You may copy and distribute the object code form of the supplement\. - + *Third Party Distribution\.* You may permit distributors of your programs to copy and distribute the Distributable Code as part of those programs\. - - 1. **Distribution Requirements\. For any Distributable Code you distribute, you must** - + add significant primary functionality to it in your programs; - + for any Distributable Code having a filename extension of \.lib, distribute only the results of running such Distributable Code through a linker with your program; - + distribute Distributable Code included in a setup program only as part of that setup program without modification; - + require distributors and external end users to agree to terms that protect it at least as much as this agreement; - + display your valid copyright notice on your programs; and - + indemnify, defend, and hold harmless Microsoft from any claims, including attorneys' fees, related to the distribution or use of your programs\. - - 1. **Distribution Restrictions\. You may not** - + alter any copyright, trademark or patent notice in the Distributable Code; - + use Microsoft's trademarks in your programs' names or in a way that suggests your programs come from or are endorsed by Microsoft; - + distribute Distributable Code to run on a platform other than the Windows platform; - + include Distributable Code in malicious, deceptive or unlawful programs; or - + modify or distribute the source code of any Distributable Code so that any part of it becomes subject to an Excluded License\. An Excluded License is one that requires, as a condition of use, modification or distribution, that - + the code be disclosed or distributed in source code form; or - + others have the right to modify it\. - -1. **SUPPORT SERVICES FOR SUPPLEMENT**\. Microsoft provides support services for this software as described at [www\.support\.microsoft\.com/common/international\.aspx](http://www.support.microsoft.com/common/international.aspx)\. - -## 8\) windows\-base Docker image—visualfsharptools, v 4\.0 - -\(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\. - -Licensed under the Apache License, version 2\.0 \(the "License"\); you may not use these files except in compliance with the License\. You may obtain a copy of the License at - -[http://www\.apache\.org/licenses/LICENSE\-2\.0](http://www.apache.org/licenses/LICENSE-2.0) - -Unless required by applicable law or as agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied\. See the License for the specific language governing permissions and limitations under the License\. - -## 9\) windows\-base Docker image—netfx\-pcl\-reference\-assemblies\-4\.6 - -**MICROSOFT SOFTWARE LICENSE TERMS** - -**MICROSOFT \.NET PORTABLE CLASS LIBRARY REFERENCE ASSEMBLIES – 4\.6** - -\-\-\-\-\- - -These license terms are an agreement between Microsoft Corporation \(or based on where you live, one of its affiliates\) and you\. Please read them\. They apply to the software named above\. The terms also apply to any Microsoft -+ updates, -+ supplements, -+ Internet\-based services, and -+ support services - -for this software, unless other terms accompany those items\. If so, those terms apply\. - -**BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS\. IF YOU DO NOT ACCEPT THEM, DO NOT USE THE SOFTWARE\.** - -\-\-\-\-\- - -**IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE PERPETUAL RIGHTS BELOW\.** - -1. **INSTALLATION AND USE RIGHTS**\. You may install and use any number of copies of the software to design, develop and test your programs\. - -1. **ADDITIONAL LICENSING REQUIREMENTS AND/OR USE RIGHTS**\. - - 1. **Distributable Code**\. You may distribute the software in developer tool programs you develop, to enable customers of your programs to develop portable libraries for use with any device or operating system, if you comply with the terms below\. - - 1. **Right to Use and Distribute\. The software is "Distributable Code\."** - + *Distributable Code\.* You may copy and distribute the object code form of the software\. - + *Third Party Distribution\.* You may permit distributors of your programs to copy and distribute the Distributable Code as part of those programs\. - - 1. **Distribution Requirements\. For any Distributable Code you distribute, you must** - + add significant primary functionality to it in your programs; - + require distributors and your customers to agree to terms that protect it at least as much as this agreement; - + display your valid copyright notice on your programs; and - + indemnify, defend, and hold harmless Microsoft from any claims, including attorneys' fees, related to the distribution or use of your programs\. - - 1. **Distribution Restrictions\. You may not** - + alter any copyright, trademark or patent notice in the Distributable Code; - + use Microsoft's trademarks in your programs' names or in a way that suggests your programs come from or are endorsed by Microsoft; - + include Distributable Code in malicious, deceptive or unlawful programs; or - + modify or distribute the Distributable Code so that any part of it becomes subject to an Excluded License\. An Excluded License is one that requires, as a condition of use, modification or distribution, that - + the code be disclosed or distributed in source code form; or - + others have the right to modify it\. - -1. **SCOPE OF LICENSE**\. The software is licensed, not sold\. This agreement only gives you some rights to use the software\. Microsoft reserves all other rights\. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement\. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways\. You may not - + work around any technical limitations in the software; - + reverse engineer, decompile or disassemble the software, except and only to the extent that applicable law expressly permits, despite this limitation; - + publish the software for others to copy; or - + rent, lease or lend the software\. - -1. **FEEDBACK**\. You may provide feedback about the software\. If you give feedback about the software to Microsoft, you give to Microsoft, without charge, the right to use, share and commercialize your feedback in any way and for any purpose\. You also give to third parties, without charge, any patent rights needed for their products, technologies and services to use or interface with any specific parts of a Microsoft software or service that includes the feedback\. You will not give feedback that is subject to a license that requires Microsoft to license its software or documentation to third parties because we include your feedback in them\. These rights survive this agreement\. - -1. **TRANSFER TO A THIRD PARTY**\. The first user of the software may transfer it, and this agreement, directly to a third party\. Before the transfer, that party must agree that this agreement applies to the transfer and use of the software\. The first user must uninstall the software before transferring it separately from the device\. The first user may not retain any copies\. - -1. **EXPORT RESTRICTIONS**\. The software is subject to United States export laws and regulations\. You must comply with all domestic and international export laws and regulations that apply to the software\. These laws include restrictions on destinations, end users and end use\. For additional information, see [www\.microsoft\.com/exporting](http://www.microsoft.com/exporting)\. - -1. **SUPPORT SERVICES**\. Because this software is "as is," we may not provide support services for it\. - -1. **ENTIRE AGREEMENT**\. This agreement, and the terms for supplements, updates, Internet\-based services and support services that you use, are the entire agreement for the software and any support services we provide\. - -1. **APPLICABLE LAW**\. - - 1. **United States**\. If you acquired the software in the United States, Washington state law governs the interpretation of this agreement and applies to claims for breach of it, regardless of conflict of laws principles\. The laws of the state where you live govern all other claims, including claims under state consumer protection laws, unfair competition laws, and in tort\. - - 1. **Outside the United States**\. If you acquired the software in any other country, the laws of that country apply\. - -1. **LEGAL EFFECT**\. This agreement describes certain legal rights\. You may have other rights under the laws of your country\. You may also have rights with respect to the party from whom you acquired the software\. This agreement does not change your rights under the laws of your country if the laws of your country do not permit it to do so\. - -1. **DISCLAIMER OF WARRANTY\. THE SOFTWARE IS LICENSED "AS\-IS\." YOU BEAR THE RISK OF USING IT\. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES OR CONDITIONS\. YOU MAY HAVE ADDITIONAL CONSUMER RIGHTS OR STATUTORY GUARANTEES UNDER YOUR LOCAL LAWS WHICH THIS AGREEMENT CANNOT CHANGE\. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT EXCLUDES THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON\-INFRINGEMENT\.** - - **FOR AUSTRALIA—YOU HAVE STATUTORY GUARANTEES UNDER THE AUSTRALIAN CONSUMER LAW AND NOTHING IN THESE TERMS IS INTENDED TO AFFECT THOSE RIGHTS\.** - -1. **LIMITATION ON AND EXCLUSION OF REMEDIES AND DAMAGES\. YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U\.S\. $5\.00\. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES\.** - - This limitation applies to - + anything related to the software, services, content \(including code\) on third party Internet sites, or third party programs; and - + claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law\. - - It also applies even if Microsoft knew or should have known about the possibility of the damages\. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages\. - -## 10\) windows\-base Docker image—visualcppbuildtools v 14\.0\.25420\.1 - -\(license terms available at: [https://www\.visualstudio\.com/license\-terms/mt644918/](https://www.visualstudio.com/license-terms/mt644918/)\) - -MICROSOFT VISUAL C\+\+ BUILD TOOLS - -**MICROSOFT SOFTWARE LICENSE TERMS** - -**MICROSOFT VISUAL C\+\+ BUILD TOOLS** - -\-\-\-\-\- - -These license terms are an agreement between Microsoft Corporation \(or based on where you live, one of its affiliates\) and you\. They apply to the software named above\. The terms also apply to any Microsoft services or updates for the software, except to the extent those have different terms\. - -\-\-\-\-\- - -**IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW\.** - -1. **INSTALLATION AND USE RIGHTS**\. - - 1. One user may use copies of the software to develop and test their applications\. - -1. **DATA**\. The software may collect information about you and your use of the software, and send that to Microsoft\. Microsoft may use this information to provide services and improve our products and services\. You may opt\-out of many of these scenarios, but not all, as described in the product documentation\. There are also some features in the software that may enable you to collect data from users of your applications\. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications\. You can learn more about data collection and use in the help documentation and the privacy statement at [http://go\.microsoft\.com/fwlink/?LinkID=528096](http://go.microsoft.com/fwlink/?LinkID=528096)\. Your use of the software operates as your consent to these practices\. - -1. **TERMS FOR SPECIFIC COMPONENTS**\. - - 1. **Build Server**\. The software may contain some Build Server components listed in BuildServer\.TXT files, and/or any files listed on the BuildeServer list located following this Microsoft Software License Terms\. You may copy and install those items, if included in the software, onto your build machines\. You and others in your organization may use these items on your build machines solely for the purpose of compiling, building, verifying and archiving your applications or running quality or performance tests as part of the build process\. - - 1. **Microsoft Platforms**\. The software may include components from Microsoft Windows; Microsoft Windows Server; Microsoft SQL Server; Microsoft Exchange; Microsoft Office; and Microsoft SharePoint\. These components are governed by separate agreements and their own product support policies, as described in the license terms found in the installation directory for that component or in the "Licenses" folder accompanying the software\. - - 1. **Third Party Components**\. The software may include third party components with separate legal notices or governed by other agreements, as described in the ThirdPartyNotices file accompanying the software\. Even if such components are governed by other agreements, the disclaimers and the limitations on and exclusions of damages below also apply\. - - 1. **Package Managers**\. The software may include package managers, like Nuget, that give you the option to download other Microsoft and third party software packages to use with your application\. Those packages are under their own licenses, and not this agreement\. Microsoft does not distribute, license or provide any warranties for any of the third party packages\. - -1. **SCOPE OF LICENSE**\. The software is licensed, not sold\. This agreement only gives you some rights to use the software\. Microsoft reserves all other rights\. Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this agreement\. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways\. For more information, see [https://docs\.microsoft\.com/en\-us/legal/information\-protection/software\-license\-terms\#1\-installation\-and\-use\-rights](https://docs.microsoft.com/en-us/legal/information-protection/software-license-terms#1-installation-and-use-rights)\. You may not - + work around any technical limitations in the software; - + reverse engineer, decompile or disassemble the software, or attempt to do so, except and only to the extent required by third party licensing terms governing use of certain open source components that may be included with the software; - + remove, minimize, block or modify any notices of Microsoft or its suppliers; - + use the software in any way that is against the law; or - + share, publish, rent or lease the software, or provide the software as a stand\-alone hosted as solution for others to use\. - -1. **EXPORT RESTRICTIONS**\. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users and end use\. For further information on export restrictions, visit \([aka\.ms/exporting](http://aka.ms/exporting)\)\. - -1. **SUPPORT SERVICES**\. Because this software is "as is," we may not provide support services for it\. - -1. **ENTIRE AGREEMENT**\. This agreement, and the terms for supplements, updates, Internet\-based services and support services that you use, are the entire agreement for the software and support services\. - -1. **APPLICABLE LAW**\. If you acquired the software in the United States, Washington law applies to interpretation of and claims for breach of this agreement, and the laws of the state where you live apply to all other claims\. If you acquired the software in any other country, its laws apply\. - -1. **CONSUMER RIGHTS; REGIONAL VARIATIONS**\. This agreement describes certain legal rights\. You may have other rights, including consumer rights, under the laws of your state or country\. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software\. This agreement does not change those other rights if the laws of your state or country do not permit it to do so\. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you: - + **Australia**\. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights\. - + **Canada**\. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet \(if and when you re\-connect to the Internet, however, the software will resume checking for and installing updates\), or uninstalling the software\. The product documentation, if any, may also specify how to turn off updates for your specific device or software\. - + **Germany and Austria**\. - + **Warranty**\. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software\. However, Microsoft gives no contractual guarantee in relation to the licensed software\. - + *Limitation of Liability*\. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law\. - - Subject to the foregoing clause \(ii\), Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in \(so\-called "cardinal obligations"\)\. In other cases of slight negligence, Microsoft will not be liable for slight negligence\. - -1. **LEGAL EFFECT**\. This agreement describes certain legal rights\. You may have other rights under the laws of your state or country\. This agreement does not change your rights under the laws of your state or country if the laws of your state or country do not permit it to do so\. Without limitation of the foregoing, for Australia, **YOU HAVE STATUTORY GUARANTEES UNDER THE AUSTRALIAN CONSUMER LAW AND NOTHING IN THESE TERMS IS INTENDED TO AFFECT THOSE RIGHTS** - -1. **DISCLAIMER OF WARRANTY\. THE SOFTWARE IS LICENSED "AS\-IS\." YOU BEAR THE RISK OF USING IT\. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES OR CONDITIONS\. TO THE EXTENT PERMITTED UNDER YOUR LOCAL LAWS, MICROSOFT EXCLUDES THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON\-INFRINGEMENT\.** - -1. **LIMITATION ON AND EXCLUSION OF DAMAGES\. YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U\.S\. $5\.00\. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES\.** - - This limitation applies to \(a\) anything related to the software, services, content \(including code\) on third party Internet sites, or third party applications; and \(b\) claims for breach of contract, breach of warranty, guarantee or condition, strict liability, negligence, or other tort to the extent permitted by applicable law\. - - It also applies even if Microsoft knew or should have known about the possibility of the damages\. The above limitation or exclusion may not apply to you because your country may not allow the exclusion or limitation of incidental, consequential or other damages\. - -## 11\) windows\-base Docker image—microsoft\-windows\-netfx3\-ondemand\-package\.cab - -**MICROSOFT SOFTWARE SUPPLEMENTAL LICENSE TERMS** - -**MICROSOFT \.NET FRAMEWORK 3\.5 SP1 FOR MICROSOFT WINDOWS OPERATING SYSTEM** - -\-\-\-\-\- - -Microsoft Corporation \(or based on where you live, one of its affiliates\) licenses this supplement to you\. If you are licensed to use Microsoft Windows operating system software \(for which this supplement is applicable\) \(the "software"\), you may use this supplement\. You may not use it if you do not have a license for the software\. You may use a copy of this supplement with each validly licensed copy of the software\. - -The following license terms describe additional use terms for this supplement\. These terms and the license terms for the software apply to your use of the supplement\. If there is a conflict, these supplemental license terms apply\. - -**BY USING THIS SUPPLEMENT, YOU ACCEPT THESE TERMS\. IF YOU DO NOT ACCEPT THEM, DO NOT USE THIS SUPPLEMENT\.** - -\-\-\-\-\- - -**If you comply with these license terms, you have the rights below\.** - -1. **SUPPORT SERVICES FOR SUPPLEMENT**\. Microsoft provides support services for this software as described at [www\.support\.microsoft\.com/common/international\.aspx](http://www.support.microsoft.com/common/international.aspx)\. - -1. **MICROSOFT \.NET BENCHMARK TESTING**\. The software includes the \.NET Framework, Windows Communication Foundation, Windows Presentation Foundation, and Windows Workflow Foundation components of the Windows operating systems \(\.NET Components\)\. You may conduct internal benchmark testing of the \.NET Components\. You may disclose the results of any benchmark test of the \.NET Components, provided that you comply with the conditions set forth at [http://go\.microsoft\.com/fwlink/?LinkID=66406](http://go.microsoft.com/fwlink/?LinkID=66406)\. - - Notwithstanding any other agreement you may have with Microsoft, if you disclose such benchmark test results, Microsoft shall have the right to disclose the results of benchmark tests it conducts of your products that compete with the applicable \.NET Component, provided it complies with the same conditions set forth at [http://go\.microsoft\.com/fwlink/?LinkID=66406](http://go.microsoft.com/fwlink/?LinkID=66406)\. - -## 12\) windows\-base Docker image—dotnet\-sdk - -\(available at [https://github\.com/dotnet/core/blob/main/LICENSE\.TXT](https://github.com/dotnet/core/blob/main/LICENSE.TXT)\) - -The MIT License \(MIT\) - -Copyright \(c\) Microsoft Corporation - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files \(the "Software"\), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software\. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT\. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE\. \ No newline at end of file diff --git a/doc_source/notification-rule-create.md b/doc_source/notification-rule-create.md deleted file mode 100644 index 10bfa16..0000000 --- a/doc_source/notification-rule-create.md +++ /dev/null @@ -1,81 +0,0 @@ -# Create a notification rule - -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\) - -1. Sign in to the AWS Management Console and open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. Choose **Build**, choose **Build projects**, and then choose a build project where you want to add notifications\. - -1. On the build project page, choose **Notify**, and then choose **Create notification rule**\. You can also go to the **Settings** page for the build project and choose **Create notification rule**\. - -1. In **Notification name**, enter a name for the rule\. - -1. In **Detail type**, choose **Basic** if you want only the information provided to Amazon EventBridge included in the notification\. Choose **Full** if you want to include information provided to Amazon EventBridge and information that might be supplied by the CodeBuild or the notification manager\. - - For more information, see [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. - -1. In **Events that trigger notifications**, select the events for which you want to send notifications\. For more information, see [ Events for Notification Rules on Build Projects](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/concepts.html#events-ref-buildproject)\. - -1. In **Targets**, do one of the following: - + If you have already configured a resource to use with notifications, in **Choose target type**, choose either **AWS Chatbot \(Slack\)** or **SNS topic**\. In **Choose target**, choose the name of the client \(for a Slack client configured in AWS Chatbot\) or the Amazon Resource Name \(ARN\) of the Amazon SNS topic \(for Amazon SNS topics already configured with the policy required for notifications\)\. - + If you have not configured a resource to use with notifications, choose **Create target**, and then choose **SNS topic**\. Provide a name for the topic after **codestar\-notifications\-**, and then choose **Create**\. -**Note** -If you create the Amazon SNS topic as part of creating the notification rule, the policy that allows the notifications feature to publish events to the topic is applied for you\. Using a topic created for notification rules helps ensure that you subscribe only those users that you want to receive notifications about this resource\. -You cannot create an AWS Chatbot client as part of creating a notification rule\. If you choose AWS Chatbot \(Slack\), you will see a button directing you to configure a client in AWS Chatbot\. Choosing that option opens the AWS Chatbot console\. For more information, see [ Configure Integrations Between Notifications and AWS Chatbot](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/notifications-chatbot.html)\. -If you want to use an existing Amazon SNS topic as a target, you must add the required policy for AWS CodeStar Notifications in addition to any other policies that might exist for that topic\. For more information, see [Configure Amazon SNS Topics for Notifications ](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/set-up-sns.html) and [Understanding Notification Contents and Security](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/security.html#security-notifications)\. - -1. To finish creating the rule, choose **Submit**\. - -1. You must subscribe users to the Amazon SNS topic for the rule before they can receive notifications\. For more information, see [Subscribe Users to Amazon SNS Topics That Are Targets](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/subscribe-users-sns.html)\. You can also set up integration between notifications and AWS Chatbot to send notifications to Amazon Chime chatrooms\. For more information, see [Configure Integration Between Notifications and AWS Chatbot](https://docs.aws.amazon.com/codestar-notifications/latest/userguide/notifications-chatbot.html)\. - -# To create a notification rule \(AWS CLI\) - -1. At a terminal or command prompt, run the create\-notification rule command to generate the JSON skeleton: - - ``` - aws codestarnotifications create-notification-rule --generate-cli-skeleton > rule.json - ``` - - You can name the file anything you want\. In this example, the file is named *rule\.json*\. - -1. Open the JSON file in a plain\-text editor and edit it to include the resource, event types, and target you want for the rule\. The following example shows a notification rule named **MyNotificationRule** for a build project named *MyBuildProject* in an AWS acccount with the ID *123456789012*\. Notifications are sent with the full detail type to an Amazon SNS topic named *codestar\-notifications\-MyNotificationTopic* when builds are successful: - - ``` - { - "Name": "MyNotificationRule", - "EventTypeIds": [ - "codebuild-project-build-state-succeeded" - ], - "Resource": "arn:aws:codebuild:us-east-2:123456789012:MyBuildProject", - "Targets": [ - { - "TargetType": "SNS", - "TargetAddress": "arn:aws:sns:us-east-2:123456789012:codestar-notifications-MyNotificationTopic" - } - ], - "Status": "ENABLED", - "DetailType": "FULL" - } - ``` - - Save the file\. - -1. Using the file you just edited, at the terminal or command line, run the create\-notification\-rule command again to create the notification rule: - - ``` - aws codestarnotifications create-notification-rule --cli-input-json file://rule.json - ``` - -1. If successful, the command returns the ARN of the notification rule, similar to the following: - - ``` - { - "Arn": "arn:aws:codestar-notifications:us-east-1:123456789012:notificationrule/dc82df7a-EXAMPLE" - } - ``` \ No newline at end of file diff --git a/doc_source/planning.md b/doc_source/planning.md deleted file mode 100644 index bff9632..0000000 --- a/doc_source/planning.md +++ /dev/null @@ -1,23 +0,0 @@ -# Plan a build in AWS CodeBuild - -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\. - - -**** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/planning.html) - -1. **Which build commands do you need to run and in what order?** By default, CodeBuild downloads the build input from the provider you specify and uploads the build output to the bucket you specify\. You use the buildspec to instruct how to turn the downloaded build input into the expected build output\. For more information, see the [Buildspec reference](build-spec-ref.md)\. - -1. **Which runtimes and tools do you need to run the build?** For example, are you building for Java, Ruby, Python, or Node\.js? Does the build need Maven or Ant or a compiler for Java, Ruby, or Python? Does the build need Git, the AWS CLI, or other tools? - - CodeBuild runs builds in build environments that use Docker images\. These Docker images must be stored in a repository type supported by CodeBuild\. These include the CodeBuild Docker image repository, Docker Hub, and Amazon Elastic Container Registry \(Amazon ECR\)\. For more information about the CodeBuild Docker image repository, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - -1. **Do you need AWS resources that aren't provided automatically by CodeBuild? If so, which security policies do those resources need?** For example, you might need to modify the CodeBuild service role to allow CodeBuild to work with those resources\. - -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 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 deleted file mode 100644 index e2f1267..0000000 --- a/doc_source/project-sharing.md +++ /dev/null @@ -1,186 +0,0 @@ -# Working with shared projects - -Project sharing allows project owners to share their AWS CodeBuild projects with other AWS accounts or users\. In this model, the account that owns the project \(owner\) shares a project with other accounts \(consumers\)\. A consumer cannot edit or run a project\. - -**Topics** -+ [Prerequisites for sharing projects](#project-sharing-prereqs) -+ [Prerequisites for accessing shared projects](#project-sharing-access-prereqs) -+ [Related services](#project-sharing-related) -+ [Sharing a project](#project-sharing-share) -+ [Unsharing a shared project](#project-sharing-unshare) -+ [Identifying a shared project](#project-sharing-identify) -+ [Shared project permissions](#project-sharing-perms) - -## Prerequisites for sharing projects - -To share a project, your AWS account must own it\. You cannot share a project that has been shared with you\. - -## Prerequisites for accessing shared projects shared with you - -To access a shared project, a consumer's IAM role requires the `BatchGetProjects` permission\. You can attach the following policy to their IAM role: - -``` -{ - "Effect": "Allow", - "Resource": [ - "*" - ], - "Action": [ - "codebuild:BatchGetProjects" - ] -} -``` - - For more information, see [Using identity\-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. - -## Related services - -Project sharing integrates with AWS Resource Access Manager \(AWS RAM\), a service that makes it possible for you to share your AWS resources with any AWS account or through AWS Organizations\. With AWS RAM, you share resources by creating a *resource share* that specifies the resources and the consumers to share them with\. Consumers can be individual AWS accounts, organizational units in AWS Organizations, or an entire organization in AWS Organizations\. - -For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*\. - -## Sharing a project - -The consumer can use both the AWS CLI and AWS CodeBuild console to view the project and builds you've shared\. The consumer cannot edit or run the project\. - -You can add a project to an existing resource share or you can create one in the [AWS RAM console](https://console.aws.amazon.com/ram)\. - -**Note** -You cannot delete a project with builds that has been added to a resource share\. - -To share a project with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. - -You can use the AWS CodeBuild console, AWS RAM console, or the AWS CLI to share a project that you own\. - -**To share a project that you own \(CodeBuild 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**\. -**Note** -By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. - -1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a resource share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. - -**To share a project that you own \(AWS RAM console\)** -See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. - -**To share a project that you own \(AWS RAM command\)** -Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. - -**To share a project that you own \(CodeBuild command\)** - -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\. - - ``` - { - "Version":"2012-10-17", - "Statement":[{ - "Effect":"Allow", - "Principal":{ - "AWS":"" - }, - "Action":[ - "codebuild:BatchGetProjects", - "codebuild:BatchGetBuilds", - "codebuild:ListBuildsForProject"], - "Resource":"" - }] - } - ``` - -1. Update `policy.json` with the project ARN and identifiers to share it with\. The following example grants read\-only access to the root user for the AWS account identified by 123456789012\. - - ``` - { - "Version":"2012-10-17", - "Statement":[{ - "Effect":"Allow", - "Principal":{ - "AWS": [ - "123456789012" - ] - }, - "Action":[ - "codebuild:BatchGetProjects", - "codebuild:BatchGetBuilds", - "codebuild:ListBuildsForProject"], - "Resource":"arn:aws:codebuild:us-west-2:123456789012:project/my-project" - }] - } - ``` - -1. Run the [put\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/put-resource-policy.html) command\. - - ``` - aws codebuild put-resource-policy --resource-arn --policy file://policy.json - ``` - -1. Get the AWS RAM resource share ARN\. - - ``` - aws ram list-resources --resource-owner SELF --resource-arns - ``` - - This will return a response similar to this: - - ``` - { - "resources": [ - { - "arn": "", - "type": "", - "resourceShareArn": "", - "creationTime": "", - "lastUpdatedTime": "" - } - ] - } - ``` - - From the response, copy the ** value to use in the next step\. - -1. Run the AWS RAM [promote\-resource\-share\-created\-from\-policy](https://docs.aws.amazon.com/cli/latest/reference/ram/promote-resource-share-created-from-policy.html) command\. - - ``` - aws ram promote-resource-share-created-from-policy --resource-share-arn - ``` - -## Unsharing a shared project - -An unshared project, including its builds, can be accessed only by its owner\. If you unshare a project, any AWS account or user you previously shared it with cannot access the project or its builds\. - -To unshare a shared project that you own, you must remove it from the resource share\. You can use the AWS CodeBuild console, AWS RAM console, or AWS CLI to do this\. - -**To unshare a shared project that you own \(AWS RAM console\)** -See [Updating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. - -**To unshare a shared project that you own \(AWS CLI\)** -Use the [disassociate\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command\. - - ** To unshare project that you own \(CodeBuild command\)** - -Run the [delete\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/delete-resource-policy.html) command and specify the ARN of the project you want to unshare: - -``` -aws codebuild delete-resource-policy --resource-arn project-arn -``` - -## Identifying a shared project - -Owners and consumers can use the AWS CLI to identify shared projects\. - -**To identify projects shared with your AWS account or user \(AWS CLI\)** -Use the [list\-shared\-projects](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-shared-projects.html) command to return the projects that are shared with you\. - -## Shared project permissions - -### Permissions for owners - -A project owner can edit the project and use it to run builds\. - -### Permissions for consumers - -A project consumer can view a project and its builds, but cannot edit a project or use it to run builds\. \ No newline at end of file diff --git a/doc_source/public-builds.md b/doc_source/public-builds.md deleted file mode 100644 index f6ed29c..0000000 --- a/doc_source/public-builds.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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 deleted file mode 100644 index e2b0c71..0000000 --- a/doc_source/report-create.md +++ /dev/null @@ -1,37 +0,0 @@ -# Create a test report - - To create a test report, you run a build project that is configured with one to five report groups in its buildspec file\. A test report is created during the run\. It contains the results of the test cases that are specified for the report groups\. 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 informaton: - - 1. Add a `reports:` section and specify either the ARN of an existing report group, or the name of a report group\. - - 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)\. - - 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 diff --git a/doc_source/report-group-create.md b/doc_source/report-group-create.md deleted file mode 100644 index 43756c0..0000000 --- a/doc_source/report-group-create.md +++ /dev/null @@ -1,9 +0,0 @@ -# Create a report group - - You can use the CodeBuild console, the AWS CLI, or a buildspec file to create a report group\. Your IAM role must have the permissions required to create a report group\. For more information, see [Working with test report permissions](test-permissions.md)\. - -**Topics** -+ [Create a report group \(buildspec\)](test-report-group-create-buildspec.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 deleted file mode 100644 index 9918839..0000000 --- a/doc_source/report-group-export-settings.md +++ /dev/null @@ -1,18 +0,0 @@ -# Update a report group - - 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: - + 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)\. - -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)\. - -**Note** -The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. - -**Topics** -+ [Update a report group \(console\)](update-report-group-console.md) -+ [Update a report group \(CLI\)](update-report-group-cli.md) \ No newline at end of file diff --git a/doc_source/report-group-test-case-commands.md b/doc_source/report-group-test-case-commands.md deleted file mode 100644 index 36c6de4..0000000 --- a/doc_source/report-group-test-case-commands.md +++ /dev/null @@ -1,12 +0,0 @@ -# Specify test commands - - You specify the commands that run your test cases in the `commands` section of your buildspec file\. These commands run the test cases specified for your report groups in the `reports` section of your buildspec file\. The following is a sample `commands` section that includes commands to run the tests in test files: - -``` -commands: - - echo Running tests for surefire junit - - mvn test -f surefire/pom.xml -fn - - echo - - echo Running tests for cucumber with json plugin - - mvn test -Dcucumber.options="--plugin json:target/cucumber-json-report.json" -f cucumber-json/pom.xml -fn -``` \ No newline at end of file diff --git a/doc_source/report-group-test-cases.md b/doc_source/report-group-test-cases.md deleted file mode 100644 index 66b76d5..0000000 --- a/doc_source/report-group-test-cases.md +++ /dev/null @@ -1,19 +0,0 @@ -# Specify test files - - You specify the test result files and their location for each report group in the `reports` section of your build project's buildspec file\. For more information, see [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. - - The following is a sample `reports` section that specifies two report groups for a build project\. One is specified with its ARN, the other with a name\. The `files` section specifies the files that contain the test case results\. The optional `base-directory` section specifies the directory where the test case files are located\. The optional `discard-paths` section specifies whether paths to test result files uploaded to an Amazon S3 bucket are discarded\. - -``` -reports: - arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: #surefire junit reports - files: - - '**/*' - base-directory: 'surefire/target/surefire-reports' - discard-paths: false - - sampleReportGroup: #Cucumber reports from json plugin - files: - - 'cucumber-json/target/cucumber-json-report.json' - 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 deleted file mode 100644 index 182f100..0000000 --- a/doc_source/report-groups-sharing.md +++ /dev/null @@ -1,200 +0,0 @@ -# Working with shared report groups - -Report group sharing allows multiple AWS accounts or users to view a report group, its unexpired reports, and the test results of its reports\. In this model, the account that owns the report group \(owner\) shares a report group with other accounts \(consumers\)\. A consumer cannot edit a report group\. A report expires 30 days after it is created\. - -**Topics** -+ [Prerequisites for sharing report groups](#report-groups-sharing-prereqs) -+ [Prerequisites for accessing report groups shared with you](#report-groups-sharing-access-prereqs) -+ [Related services](#report-groups-sharing-related) -+ [Sharing a report group](#report-groups-sharing-share) -+ [Unsharing a shared report group](#report-groups-sharing-unshare) -+ [Identifying a shared report group](#report-groups-sharing-identify) -+ [Shared report group permissions](#report-groups-sharing-perms) - -## Prerequisites for sharing report groups - - To share a report group, your AWS account must own it\. You cannot share a report group that has been shared with you\. - -## Prerequisites for accessing report groups shared with you - -To access a shared report group, a consumer's IAM role requires the `BatchGetReportGroups` permission\. You can attach the following policy to their IAM role: - -``` -{ - "Effect": "Allow", - "Resource": [ - "*" - ], - "Action": [ - "codebuild:BatchGetReportGroups" - ] -} -``` - - For more information, see [Using identity\-based policies for AWS CodeBuild](auth-and-access-control-iam-identity-based-access-control.md)\. - -## Related services - -Report group sharing integrates with AWS Resource Access Manager \(AWS RAM\), a service that makes it possible for you to share your AWS resources with any AWS account or through AWS Organizations\. With AWS RAM, you share resources that you own by creating a *resource share* that specifies the resources and the consumers to share them with\. Consumers can be individual AWS accounts, organizational units in AWS Organizations, or an entire organization in AWS Organizations\. - -For more information, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*\. - -## Sharing a report group - - When you share a report group, the consumer is granted read\-only access to the report group and its reports\. The consumer can use the AWS CLI to view the report group, its reports, and the test case results for each report\. The consumer cannot: -+ View a shared report group or its reports in the CodeBuild console\. -+ Edit a shared report group\. -+ Use the ARN of the shared report group in a project to run a report\. A project build that specifies a shared report group fails\. - -You can use the CodeBuild console to add a report group to an existing resource share\. If you want to add the report group to a new resource share, you must first create it in the [AWS RAM console](https://console.aws.amazon.com/ram)\. - -To share a report group with organizational units or an entire organization, you must enable sharing with AWS Organizations\. For more information, see [Enable sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the *AWS RAM User Guide*\. - -You can use the CodeBuild console, AWS RAM console, or AWS CLI to share report groups that you own\. - -**To share a report group that you own \(CodeBuild 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 **Report groups**\. - -1. Choose the project you want to share, and then choose **Share**\. For more information, see [Create a resource share](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-create) in the *AWS RAM User Guide*\. - -**To share report groups that you own \(AWS RAM console\)** -See [Creating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-create) in the *AWS RAM User Guide*\. - -**To share report groups that you own \(AWS RAM command\)** -Use the [create\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command\. - - **To share a report group that you own \(CodeBuild command\)** - -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\. - - ``` - { - "Version":"2012-10-17", - "Statement":[{ - "Effect":"Allow", - "Principal":{ - "AWS":"consumer-aws-account-id-or-user" - }, - "Action":[ - "codebuild:BatchGetReportGroups", - "codebuild:BatchGetReports", - "codebuild:ListReportsForReportGroup", - "codebuild:DescribeTestCases"], - "Resource":"arn-of-report-group-to-share" - }] - } - ``` - -1. Update `policy.json` with the report group ARN and identifiers to share it with\. The following example grants read\-only access to the report group with the ARN `arn:aws:codebuild:us-west-2:123456789012:report-group/my-report-group` to Alice and the root user for the AWS account identified by 123456789012\. - - ``` - { - "Version":"2012-10-17", - "Statement":[{ - "Effect":"Allow", - "Principal":{ - "AWS": [ - "arn:aws:iam::123456789012:user/Alice", - "123456789012" - ] - }, - "Action":[ - "codebuild:BatchGetReportGroups", - "codebuild:BatchGetReports", - "codebuild:ListReportsForReportGroup", - "codebuild:DescribeTestCases"], - "Resource":"arn:aws:codebuild:us-west-2:123456789012:report-group/my-report-group" - }] - } - ``` - -1. Run the following command\. - - ``` - aws codebuild put-resource-policy --resource-arn report-group-arn --policy file://policy.json - ``` - -## Unsharing a shared report group - -An unshared report group, including its reports and their test case results, can be accessed only by its owner\. If you unshare a report group, any AWS account or user you previously shared it with cannot access the report group, its reports, or the results of test cases in the reports\. - -To unshare a shared report group that you own, you must remove it from the resource share\. You can use the AWS RAM console or AWS CLI to do this\. - -**To unshare a shared report group that you own \(AWS RAM console\)** -See [Updating a resource share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html#working-with-sharing-update) in the *AWS RAM User Guide*\. - -**To unshare a shared report group that you own \(AWS RAM command\)** -Use the [disassociate\-resource\-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command\. - - ** To unshare report group that you own CodeBuild command\)** - -Run the [delete\-resource\-policy](https://docs.aws.amazon.com/cli/latest/reference/codebuild/delete-resource-policy.html) command and specify the ARN of the report group you want to unshare: - -``` -aws codebuild delete-resource-policy --resource-arn report-group-arn -``` - -## Identifying a shared report group - -Owners and consumers can use the AWS CLI to identify shared report groups\. - -To identify and get information about a shared report group and its reports, use the following commands: -+ To see the ARNs of report groups shared with you, run `[list\-shared\-report\-groups](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-shared-report-groups.html)`: - - ``` - aws codebuild list-shared-report-groups - ``` -+ To see the ARNs of the reports in a report group, run `[list\-reports\-for\-report\-group](https://docs.aws.amazon.com/cli/latest/reference/codebuild/list-reports-for-report-group.html)` using the report group ARN: - - ``` - aws codebuild list-reports-for-report-group --report-group-arn report-group-arn - ``` -+ To see information about test cases in a report, run `[describe\-test\-cases](https://docs.aws.amazon.com/cli/latest/reference/codebuild/describe-test-cases.html)` using the report ARN: - - ``` - aws codebuild describe-test-cases --report-arn report-arn - ``` - - The output looks like the following: - - ``` - { - "testCases": [ - { - "status": "FAILED", - "name": "Test case 1", - "expired": 1575916770.0, - "reportArn": "report-arn", - "prefix": "Cucumber tests for agent", - "message": "A test message", - "durationInNanoSeconds": 1540540, - "testRawDataPath": "path-to-output-report-files" - }, - { - "status": "SUCCEEDED", - "name": "Test case 2", - "expired": 1575916770.0, - "reportArn": "report-arn", - "prefix": "Cucumber tests for agent", - "message": "A test message", - "durationInNanoSeconds": 1540540, - "testRawDataPath": "path-to-output-report-files" - } - ] - } - ``` - -## Shared report group permissions - -### Permissions for owners - -A report group owner can edit the report group and specify it in a project to run reports\. - -### Permissions for consumers - -A report group consumer can view a report group, its reports, and the test case results for its reports\. A consumer cannot edit a report group or its reports, and cannot use it to create reports\. \ No newline at end of file diff --git a/doc_source/retry-build.md b/doc_source/retry-build.md deleted file mode 100644 index 3b11df6..0000000 --- a/doc_source/retry-build.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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 deleted file mode 100644 index 7e58b7a..0000000 --- a/doc_source/run-batch-build-cli.md +++ /dev/null @@ -1,57 +0,0 @@ -# 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 deleted file mode 100644 index ae94018..0000000 --- a/doc_source/run-build-cli-auto-start.md +++ /dev/null @@ -1,33 +0,0 @@ -# Start running builds automatically \(AWS CLI\) - -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\-webhook command as follows: - -``` -aws codebuild create-webhook --project-name -``` - -** is the name of the build project that contains the source code to be rebuilt\. - -For GitHub, information similar to the following appears in the output: - -``` -{ - "webhook": { - "url": "" - } -} -``` - -** is the URL to the GitHub webhook\. - -For GitHub Enterprise Server, information similar to the following appears in the output: - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/create-webhook-ghe.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -1. Copy the secret key and payload URL from the output\. You need them to add a webhook in GitHub Enterprise Server\. - -1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored\. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. - -1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. \ No newline at end of file diff --git a/doc_source/run-build-cli-auto-stop.md b/doc_source/run-build-cli-auto-stop.md deleted file mode 100644 index 34433db..0000000 --- a/doc_source/run-build-cli-auto-stop.md +++ /dev/null @@ -1,15 +0,0 @@ -# Stop running builds automatically \(AWS CLI\) - -If your source code is stored in a GitHub or a GitHub Enterprise Server repository, you can set up GitHub webhooks to have AWS CodeBuild rebuild your source code whenever a code change is pushed to the repository\. For more information, see [Start running builds automatically \(AWS CLI\)](run-build-cli-auto-start.md)\. - -If you have enabled this behavior, you can turn it off by running the `delete-webhook` command as follows: - -``` -aws codebuild delete-webhook --project-name -``` -+ where ** is the name of the build project that contains the source code to be rebuilt\. - -If this command is successful, no information and no errors appear in the output\. - -**Note** -This deletes the webhook from your CodeBuild project only\. You should also delete the webhook from your GitHub or GitHub Enterprise Server repository\. \ No newline at end of file diff --git a/doc_source/run-build-cli.md b/doc_source/run-build-cli.md deleted file mode 100644 index f5f12cb..0000000 --- a/doc_source/run-build-cli.md +++ /dev/null @@ -1,127 +0,0 @@ -# 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-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: - - ``` - aws codebuild start-build --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 --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 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 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\-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: - - ``` - { - "projectName": "projectName", - "sourceVersion": "sourceVersion", - "artifactsOverride": { - "type": "type", - "location": "location", - "path": "path", - "namespaceType": "namespaceType", - "name": "artifactsOverride-name", - "packaging": "packaging" - }, - "buildspecOverride": "buildspecOverride", - "cacheOverride": { - "location": "cacheOverride-location", - "type": "cacheOverride-type" - }, - "certificateOverride": "certificateOverride", - "computeTypeOverride": "computeTypeOverride", - "environmentTypeOverride": "environmentTypeOverride", - "environmentVariablesOverride": { - "name": "environmentVariablesOverride-name", - "value": "environmentVariablesValue", - "type": "environmentVariablesOverride-type" - }, - "gitCloneDepthOverride": "gitCloneDepthOverride", - "imageOverride": "imageOverride", - "idempotencyToken": "idempotencyToken", - "insecureSslOverride": "insecureSslOverride", - "privilegedModeOverride": "privilegedModeOverride", - "queuedTimeoutInMinutesOverride": "queuedTimeoutInMinutesOverride", - "reportBuildStatusOverride": "reportBuildStatusOverride", - "timeoutInMinutesOverride": "timeoutInMinutesOverride", - "sourceAuthOverride": "sourceAuthOverride", - "sourceLocationOverride": "sourceLocationOverride", - "serviceRoleOverride": "serviceRoleOverride", - "sourceTypeOverride": "sourceTypeOverride" - } - ``` - - Replace the following placeholders: - + *projectName*: Required string\. The name of the build project to use for this build\. - + *sourceVersion*: Optional string\. A version of the source code to be built, as follows: - + For Amazon S3, the version ID that corresponds to the version of the input ZIP file you want to build\. If *sourceVersion* is not specified, then the latest version is used\. - + For CodeCommit, the commit ID that corresponds to the version of the source code you want to build\. If *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. \(You cannot specify a tag name for *sourceVersion*, but you can specify the tag's commit ID\.\) - + 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 *sourceVersion* is 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 *sourceVersion* is not specified, the default branch's HEAD commit ID is used\. - + The following placeholders are for `artifactsOveride`\. - + *type*: Optional\. The build output artifact type that overrides for this build the one defined in the build project\. - + *location*: Optional\. The build output artifact location that overrides for this build the one defined in the build project\. - + *path*: Optional\. The build output artifact path that overrides for this build the one defined in the build project\. - + *namespaceType*: Optional\. The build output artifact path type that overrides for this build the one defined in the build project\. - + *name*: Optional\. The build output artifact name that overrides for this build the one defined in the build project\. - + *packaging*: Optional\. The build output artifact packaging type that overrides for this build the one defined in the build project\. - + *buildspecOverride*: Optional\. A buildspec declaration that overrides for this build the one defined in the build project\. 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 S3 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)\. - + The following placeholders are for `cacheOveride`\. - + *cacheOverride\-location*: Optional\. The location of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `location` is required in a `ProjectCache` object\. - + *cacheOverride\-type*: Optional\. The type of a `ProjectCache` object for this build that overrides the `ProjectCache` object specified in the build project\. `cacheOverride` is optional and takes a `ProjectCache` object\. `type` is required in a `ProjectCache` object\. - + *certificateOverride*: Optional\. The name of a certificate for this build that overrides the one specified in the build project\. - + *environmentTypeOverride*: Optional\. A container type for this build that overrides the one specified in the build project\. The current valid string is `LINUX_CONTAINER`\. - + The following placeholders are for `environmentVariablesOveride`\. - + *environmentVariablesOverride\-name*: Optional\. The name of an environment variable in the build project whose value you want to override for this build\. - + *environmentVariablesOverride\-type*: Optional\. The type of environment variable in the build project whose value you want to override for this build\. - + *environmentVariablesValue*: Optional\. The value of the environment variable defined in the build project that you want to override for this build\. - + *gitCloneDepthOverride*: Optional\. The value of the **Git clone depth** in the build project whose value you want to override for this build\. If your source type is Amazon S3, this value is not supported\. - + *imageOverride*: Optional\. The name of an image for this build that overrides the one specified in the build project\. - + *idempotencyToken*: Optional\. A string that serves as a token to specify that the build request is idempotent\. You can choose any string that is 64 characters or less\. The token is valid for 5 minutes after the start\-build request\. If you repeat the start\-build request with the same token, but change a parameter, CodeBuild returns a parameter mismatch error\. - + *insecureSslOverride*: Optional boolean that specifies whether to override the insecure TLS setting specified in the build project\. The insecure TLS setting determines whether to ignore TLS warnings while connecting to the project source code\. This override applies only if the build's source is GitHub Enterprise Server\. - + *privilegedModeOverride*: Optional boolean\. If set to true, the build overrides privileged mode in the build project\. - + *queuedTimeoutInMinutesOverride*: Optional integer that specifies the number of minutes a build is allowed to be queued before it times out\. Its minimum value is five minutes and its maximum value is 480 minutes \(eight hours\)\. - + *reportBuildStatusOverride*: Optional boolean that 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\. - + *sourceAuthOverride*: Optional string\. An authorization type for this build that overrides the one defined in the build project\. This override applies only if the build project's source is Bitbucket or GitHub\. - + *sourceLocationOverride*: Optional string\. A location that overrides for this build the source location for the one defined in the build project\. - + *serviceRoleOverride*: Optional string\. The name of a service role for this build that overrides the one specified in the build project\. - + *sourceTypeOverride*: Optional string\. A source input type for this build that overrides the source input defined in the build project\. Valid strings are `NO_SOURCE`, `CODECOMMIT`, `CODEPIPELINE`, `GITHUB`, `S3`, `BITBUCKET`, and `GITHUB_ENTERPRISE`\. - + *timeoutInMinutesOverride*: Optional number\. The number of build timeout minutes that overrides for this build the one defined in the build project\. - - 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\. CodeBuild can use a parameter stored in Amazon EC2 Systems Manager Parameter Store only if that parameter's name starts 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\. However, if you use the Amazon EC2 Systems Manager Parameter Store console to create a parameter, you must start the parameter's name with `/CodeBuild/`, and you must set **Type** to **Secure String**\. For more information, see [AWS Systems Manager parameter store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.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 new 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\. - - 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 environment variable's 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 file declaration takes lowest precedence\. - - For information about valid values for these placeholders, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. For a list of the latest settings for a build project, see [View a build project's details](view-project-details.md)\. - -1. Switch to the directory that contains the file you just saved, and run the `start-build` command again\. - - ``` - aws codebuild start-build --cli-input-json file://start-build.json - ``` - -1. If successful, data similar to that described in the [To run the build](getting-started-cli-run-build.md#getting-started-run-build-cli) procedure appears in the output\. - -To work with detailed information about this build, make a note of the `id` value in the output, and then see [View build details \(AWS CLI\)](view-build-details.md#view-build-details-cli)\. \ No newline at end of file diff --git a/doc_source/run-build-console.md b/doc_source/run-build-console.md deleted file mode 100644 index 7a1c3b3..0000000 --- a/doc_source/run-build-console.md +++ /dev/null @@ -1,30 +0,0 @@ -# Run a build \(console\) - -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. In the navigation pane, choose **Build projects**\. - -1. In the list of build projects, choose the build project\. - -1. You can run the build with the default build project settings, or override build settings for this build only\. - - 1. If you want to run the build with the default build project settings, choose **Start build**\. The build starts immediately\. - - 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** - - 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** - - When you have made your override selections, 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 diff --git a/doc_source/run-build-sdks.md b/doc_source/run-build-sdks.md deleted file mode 100644 index 47558b7..0000000 --- a/doc_source/run-build-sdks.md +++ /dev/null @@ -1,5 +0,0 @@ -# Run a build \(AWS SDKs\) - -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 deleted file mode 100644 index f2a8626..0000000 --- a/doc_source/run-build.md +++ /dev/null @@ -1,11 +0,0 @@ -# Run a build in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to run a build in CodeBuild\. - -**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 deleted file mode 100644 index bf0d8c8..0000000 --- a/doc_source/runtime-versions.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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-bitbucket-pull-request.md b/doc_source/sample-bitbucket-pull-request.md deleted file mode 100644 index b458484..0000000 --- a/doc_source/sample-bitbucket-pull-request.md +++ /dev/null @@ -1,116 +0,0 @@ -# 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) - -## Prerequisites - - To run this sample you must connect your AWS CodeBuild project with your Bitbucket account\. - -**Note** - CodeBuild has updated its permissions with Bitbucket\. If you previously connected your project to Bitbucket and now receive a Bitbucket connection error, you must reconnect to grant CodeBuild permission to manage your webhooks\. - -## Create a build project with Bitbucket as the source repository and enable webhooks - - The following steps describe how to create an AWS CodeBuild project with Bitbucket as a source repository and enable webhooks\. - -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. Choose **Create build project**\. - -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. 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 the following\. -**Note** -The **Primary source webhook events** section is only visible if you chose **Repository in my Bitbucket account** in the previous step\. - - 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 about Bitbucket webhook event types and filters, see [Bitbucket webhook events](bitbucket-webhook.md)\. - -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\. - -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**: -**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\. - -1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. - -## Trigger a build with a Bitbucket webhook - -For a project that uses Bitbucket webhooks, AWS CodeBuild creates a build when the Bitbucket repository detects a change in your source code\. - -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. On the Bitbucket webhooks page, choose **View request** to see a list of recent events\. - -1. Choose **View details** to see details about the response returned by CodeBuild\. It might look something like this: - - ``` - "response":"Webhook received and build started: https://us-east-1.console.aws.amazon.com/codebuild/home..." - "statusCode":200 - ``` - -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 deleted file mode 100644 index 9c4729d..0000000 --- a/doc_source/sample-build-badges.md +++ /dev/null @@ -1,86 +0,0 @@ -# Build badges sample with CodeBuild - -AWS 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\. This image is accessible through a publicly available URL generated for your CodeBuild project\. This allows anyone to view the status of a CodeBuild project\. Build badges do not contain any security information, so they do not require authentication\. - -## Create a build project with build badges enabled \(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. 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** - CodeBuild does not support build badges with the Amazon S3 source provider\. Because AWS CodePipeline uses Amazon S3 for artifact transfers, build badges are not supported for build projects that are part of a pipeline created in CodePipeline\. - + If you chose **CodeCommit**, then for **Repository**, choose the name of the repository\. Select **Enable build badge** to make your project's build status visible and embeddable\. - + If you chose **GitHub**, follow the instructions to connect \(or reconnect\) with GitHub\. On the GitHub **Authorize application** page, for **Organization access**, choose **Request access** next to each repository you want AWS CodeBuild to be able to access\. After you choose **Authorize application**, back in the AWS CodeBuild console, for **Repository**, choose the name of the repository that contains the source code\. Select **Enable build badge** to make your project's build status visible and embeddable\. - + If you chose **Bitbucket**, follow the instructions to connect \(or reconnect\) with Bitbucket\. On the Bitbucket **Confirm access to your account** page, for **Organization access**, choose **Grant access**\. After you choose **Grant access**, back in the AWS CodeBuild console, for **Repository**, choose the name of the repository that contains the source code\. Select **Enable build badge** to make your project's build status visible and embeddable\. -**Important** -Updating your project source might affect the accuracy of the project's build badges\. - -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 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\. - + 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. 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: - + 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 choose options as appropriate\. - -1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. - -## Create a build project with build badges enabled \(CLI\) - -For information about creating a build project, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. To include build badges with your AWS CodeBuild project, you must specify *badgeEnabled* with a value of `true`\. - -## Access your AWS CodeBuild build badges - -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)\. - -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: - -``` -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: - -``` -https://codebuild.us-east-1.amazon.com/badges?uuid=...&tag= -``` - -## Publish your CodeBuild build badges - -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: - -``` -![]() -``` - -## CodeBuild badge statuses -+ **PASSING** The most recent build on the given branch passed\. -+ **FAILING** The most recent build on the given branch timed out, failed, faulted, or was stopped\. -+ **IN\_PROGRESS** The most recent build on the given branch is in progress\. -+ **UNKNOWN** The project has not yet run a build for the given branch or at all\. Also, the build badges feature might have been disabled\. \ No newline at end of file diff --git a/doc_source/sample-build-notifications.md b/doc_source/sample-build-notifications.md deleted file mode 100644 index 2511b02..0000000 --- a/doc_source/sample-build-notifications.md +++ /dev/null @@ -1,538 +0,0 @@ -# Build notifications sample for CodeBuild - -Amazon CloudWatch Events has built\-in support for AWS CodeBuild\. CloudWatch Events is a stream of system events describing changes in your AWS resources\. With CloudWatch Events, you write declarative rules to associate events of interest with automated actions to be taken\. This sample uses Amazon CloudWatch Events and Amazon Simple Notification Service \(Amazon SNS\) to send build notifications to subscribers whenever builds succeed, fail, go from one build phase to another, or any combination of these events\. - -**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 CloudWatch and Amazon SNS\. For more information, see [CodeBuild pricing](http://aws.amazon.com/codebuild/pricing), [Amazon CloudWatch pricing](http://aws.amazon.com/cloudwatch/pricing), and [Amazon SNS pricing](http://aws.amazon.com/sns/pricing)\. - -## Running the sample - -**To run this sample** - -1. If you already have a topic set up and subscribed to in Amazon SNS that you want to use for this sample, skip ahead to step 4\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon SNS, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\. This statement enables viewing, creating, subscribing, and testing the sending of notifications to topics in Amazon SNS\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. - - ``` - { - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Action": [ - "sns:CreateTopic", - "sns:GetTopicAttributes", - "sns:List*", - "sns:Publish", - "sns:SetTopicAttributes", - "sns:Subscribe" - ], - "Resource": "*", - "Effect": "Allow" - }, - ### END ADDING STATEMENT HERE ### - ... - ], - "Version": "2012-10-17" - } - ``` -**Note** -The IAM entity that modifies this policy must have permission in IAM to modify policies\. -For more information, see [Editing customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with inline policies \(console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. - -1. Create or identify a topic in Amazon SNS\. AWS CodeBuild uses CloudWatch Events to send build notifications to this topic through Amazon SNS\. - - To create a topic: - - 1. Open the Amazon SNS console at [https://console\.aws\.amazon\.com/sns](https://console.aws.amazon.com/sns)\. - - 1. Choose **Create topic**\. - - 1. In **Create new topic**, for **Topic name**, enter a name for the topic \(for example, **CodeBuildDemoTopic**\)\. \(If you choose a different name, substitute it throughout this sample\.\) - - 1. Choose **Create topic**\. - - 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\. - - To subscribe a recipient to a topic: - - 1. With the Amazon SNS console open from the previous step, in the navigation pane, choose **Subscriptions**, and then choose **Create subscription**\. - - 1. In **Create subscription**, for **Topic ARN**, paste the topic ARN you copied from the previous step\. - - 1. For **Protocol**, choose **Email**\. - - 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\. - - For more information, see [Subscribe to a topic](https://docs.aws.amazon.com/sns/latest/dg/SubscribeTopic.html) in the *Amazon SNS Developer Guide*\. - -1. If you are using an IAM user instead of an AWS root account or an administrator IAM user to work with CloudWatch Events, add the following statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\. This statement is used to allow the user to work with CloudWatch Events\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the existing policy\. - - ``` - { - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Action": [ - "events:*", - "iam:PassRole" - ], - "Resource": "*", - "Effect": "Allow" - }, - ### END ADDING STATEMENT HERE ### - ... - ], - "Version": "2012-10-17" - } - ``` -**Note** -The IAM entity that modifies this policy must have permission in IAM to modify policies\. -For more information, see [Editing customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-using.html#edit-managed-policy-console) or the "To edit or delete an inline policy for a group, user, or role" section in [Working with inline policies \(console\)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. - -1. Create a rule in CloudWatch Events\. To do this, open the CloudWatch console, at [https://console\.aws\.amazon\.com/cloudwatch](https://console.aws.amazon.com/cloudwatch)\. - -1. In the navigation pane, under **Events**, choose **Rules**, and then choose **Create rule**\. - -1. On the **Step 1: Create rule page**, **Event Pattern** and **Build event pattern to match events by service** should already be selected\. - -1. For **Service Name**, choose **CodeBuild**\. For **Event Type**, **All Events** should already be selected\. - -1. The following code should be displayed in **Event Pattern Preview**: - - ``` - { - "source": [ - "aws.codebuild" - ] - } - ``` - -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\. - - ``` - { - "source": [ - "aws.codebuild" - ], - "detail-type": [ - "CodeBuild Build State Change" - ], - "detail": { - "build-status": [ - "IN_PROGRESS", - "SUCCEEDED", - "FAILED", - "STOPPED" - ], - "project-name": [ - "my-demo-project-1", - "my-demo-project-2" - ] - } - } - ``` - - In the preceding rule, make the following code changes as needed\. - + To trigger an event when a build starts or completes, either leave all of the values as shown in the `build-status` array, or remove the `build-status` array altogether\. - + To trigger an event only when a build completes, remove `IN_PROGRESS` from the `build-status` array\. - + To trigger an event only when a build starts, remove all of the values except `IN_PROGRESS` from the `build-status` array\. - + To trigger events for all build projects, remove the `project-name` array altogether\. - + To trigger events only for individual build projects, specify the name of each build project in the `project-name` array\. - - This second rule pattern triggers an event whenever a build moves from one build phase to another for the specified build projects in AWS CodeBuild\. - - ``` - { - "source": [ - "aws.codebuild" - ], - "detail-type": [ - "CodeBuild Build Phase Change" - ], - "detail": { - "completed-phase": [ - "SUBMITTED", - "PROVISIONING", - "DOWNLOAD_SOURCE", - "INSTALL", - "PRE_BUILD", - "BUILD", - "POST_BUILD", - "UPLOAD_ARTIFACTS", - "FINALIZING" - ], - "completed-phase-status": [ - "TIMED_OUT", - "STOPPED", - "FAILED", - "SUCCEEDED", - "FAULT", - "CLIENT_ERROR" - ], - "project-name": [ - "my-demo-project-1", - "my-demo-project-2" - ] - } - } - ``` - - In the preceding rule, make the following code changes as needed\. - + To trigger an event for every build phase change \(which might send up to nine notifications for each build\), either leave all of the values as shown in the `completed-phase` array, or remove the `completed-phase` array altogether\. - + To trigger events only for individual build phase changes, remove the name of each build phase in the `completed-phase` array that you do not want to trigger an event for\. - + To trigger an event for every build phase status change, either leave all of the values as shown in the `completed-phase-status` array, or remove the `completed-phase-status` array altogether\. - + 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\. - - When you have finished replacing the code, choose **Save**\. - -1. For **Targets**, choose **Add target**\. - -1. In the list of targets, choose **SNS topic**\. - -1. For **Topic**, choose the topic you identified or created earlier\. - -1. Expand **Configure input**, and then choose **Input Transformer**\. - -1. In the **Input Path** box, enter one of the following input paths\. - - For a rule with a `detail-type` value of `CodeBuild Build State Change`, enter the following\. - - ``` - {"build-id":"$.detail.build-id","project-name":"$.detail.project-name","build-status":"$.detail.build-status"} - ``` - - For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, enter the following\. - - ``` - {"build-id":"$.detail.build-id","project-name":"$.detail.project-name","completed-phase":"$.detail.completed-phase","completed-phase-status":"$.detail.completed-phase-status"} - ``` - - To get other types of information, see the [Build notifications input format reference](#sample-build-notifications-ref)\. - -1. In the **Input Template** box, enter one of the following input templates\. - - For a rule with a `detail-type` value of `CodeBuild Build State Change`, enter the following\. - - ``` - "Build '' for build project '' has reached the build status of ''." - ``` - - For a rule with a `detail-type` value of `CodeBuild Build Phase Change`, enter the following\. - - ``` - "Build '' for build project '' has completed the build phase of '' with a status of ''." - ``` - -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\. - -1. Choose **Create rule**\. - -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\. - -To change a rule's behavior, in the CloudWatch console, choose the rule you want to change, choose **Actions**, and then choose **Edit**\. Make changes to the rule, choose **Configure details**, and then choose **Update rule**\. - -To stop using a rule to send build notifications, in the CloudWatch console, choose the rule you want to stop using, choose **Actions**, and then choose **Disable**\. - -To delete a rule altogether, in the CloudWatch console, choose the rule you want to delete, choose **Actions**, and then choose **Delete**\. - -### Related resources -+ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. - -## Build notifications input format reference - -CloudWatch delivers notifications in JSON format\. - -Build state change notifications use the following format: - -``` -{ - "version": "0", - "id": "c030038d-8c4d-6141-9545-00ff7b7153EX", - "detail-type": "CodeBuild Build State Change", - "source": "aws.codebuild", - "account": "123456789012", - "time": "2017-09-01T16:14:28Z", - "region": "us-west-2", - "resources":[ - "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" - ], - "detail":{ - "build-status": "SUCCEEDED", - "project-name": "my-sample-project", - "build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", - "additional-information": { - "artifact": { - "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", - "sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX", - "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" - }, - "environment": { - "image": "aws/codebuild/standard:4.0", - "privileged-mode": false, - "compute-type": "BUILD_GENERAL1_SMALL", - "type": "LINUX_CONTAINER", - "environment-variables": [] - }, - "timeout-in-minutes": 60, - "build-complete": true, - "initiator": "MyCodeBuildDemoUser", - "build-start-time": "Sep 1, 2017 4:12:29 PM", - "source": { - "location": "codebuild-123456789012-input-bucket/my-input-artifact.zip", - "type": "S3" - }, - "logs": { - "group-name": "/aws/codebuild/my-sample-project", - "stream-name": "8745a7a9-c340-456a-9166-edf953571bEX", - "deep-link": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logEvent:group=/aws/codebuild/my-sample-project;stream=8745a7a9-c340-456a-9166-edf953571bEX" - }, - "phases": [ - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:12:29 PM", - "end-time": "Sep 1, 2017 4:12:29 PM", - "duration-in-seconds": 0, - "phase-type": "SUBMITTED", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:12:29 PM", - "end-time": "Sep 1, 2017 4:13:05 PM", - "duration-in-seconds": 36, - "phase-type": "PROVISIONING", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:05 PM", - "end-time": "Sep 1, 2017 4:13:10 PM", - "duration-in-seconds": 4, - "phase-type": "DOWNLOAD_SOURCE", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:10 PM", - "end-time": "Sep 1, 2017 4:13:10 PM", - "duration-in-seconds": 0, - "phase-type": "INSTALL", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:10 PM", - "end-time": "Sep 1, 2017 4:13:10 PM", - "duration-in-seconds": 0, - "phase-type": "PRE_BUILD", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:10 PM", - "end-time": "Sep 1, 2017 4:14:21 PM", - "duration-in-seconds": 70, - "phase-type": "BUILD", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:14:21 PM", - "end-time": "Sep 1, 2017 4:14:21 PM", - "duration-in-seconds": 0, - "phase-type": "POST_BUILD", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:14:21 PM", - "end-time": "Sep 1, 2017 4:14:21 PM", - "duration-in-seconds": 0, - "phase-type": "UPLOAD_ARTIFACTS", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:14:21 PM", - "end-time": "Sep 1, 2017 4:14:26 PM", - "duration-in-seconds": 4, - "phase-type": "FINALIZING", - "phase-status": "SUCCEEDED" - }, - { - "start-time": "Sep 1, 2017 4:14:26 PM", - "phase-type": "COMPLETED" - } - ] - }, - "current-phase": "COMPLETED", - "current-phase-context": "[]", - "version": "1" - } -} -``` - -Build phase change notifications use the following format: - -``` -{ - "version": "0", - "id": "43ddc2bd-af76-9ca5-2dc7-b695e15adeEX", - "detail-type": "CodeBuild Build Phase Change", - "source": "aws.codebuild", - "account": "123456789012", - "time": "2017-09-01T16:14:21Z", - "region": "us-west-2", - "resources":[ - "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX" - ], - "detail":{ - "completed-phase": "COMPLETED", - "project-name": "my-sample-project", - "build-id": "arn:aws:codebuild:us-west-2:123456789012:build/my-sample-project:8745a7a9-c340-456a-9166-edf953571bEX", - "completed-phase-context": "[]", - "additional-information": { - "artifact": { - "md5sum": "da9c44c8a9a3cd4b443126e823168fEX", - "sha256sum": "6ccc2ae1df9d155ba83c597051611c42d60e09c6329dcb14a312cecc0a8e39EX", - "location": "arn:aws:s3:::codebuild-123456789012-output-bucket/my-output-artifact.zip" - }, - "environment": { - "image": "aws/codebuild/standard:4.0", - "privileged-mode": false, - "compute-type": "BUILD_GENERAL1_SMALL", - "type": "LINUX_CONTAINER", - "environment-variables": [] - }, - "timeout-in-minutes": 60, - "build-complete": true, - "initiator": "MyCodeBuildDemoUser", - "build-start-time": "Sep 1, 2017 4:12:29 PM", - "source": { - "location": "codebuild-123456789012-input-bucket/my-input-artifact.zip", - "type": "S3" - }, - "logs": { - "group-name": "/aws/codebuild/my-sample-project", - "stream-name": "8745a7a9-c340-456a-9166-edf953571bEX", - "deep-link": "https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#logEvent:group=/aws/codebuild/my-sample-project;stream=8745a7a9-c340-456a-9166-edf953571bEX" - }, - "phases": [ - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:12:29 PM", - "end-time": "Sep 1, 2017 4:12:29 PM", - "duration-in-seconds": 0, - "phase-type": "SUBMITTED", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:12:29 PM", - "end-time": "Sep 1, 2017 4:13:05 PM", - "duration-in-seconds": 36, - "phase-type": "PROVISIONING", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:05 PM", - "end-time": "Sep 1, 2017 4:13:10 PM", - "duration-in-seconds": 4, - "phase-type": "DOWNLOAD_SOURCE", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:10 PM", - "end-time": "Sep 1, 2017 4:13:10 PM", - "duration-in-seconds": 0, - "phase-type": "INSTALL", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:10 PM", - "end-time": "Sep 1, 2017 4:13:10 PM", - "duration-in-seconds": 0, - "phase-type": "PRE_BUILD", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:13:10 PM", - "end-time": "Sep 1, 2017 4:14:21 PM", - "duration-in-seconds": 70, - "phase-type": "BUILD", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:14:21 PM", - "end-time": "Sep 1, 2017 4:14:21 PM", - "duration-in-seconds": 0, - "phase-type": "POST_BUILD", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:14:21 PM", - "end-time": "Sep 1, 2017 4:14:21 PM", - "duration-in-seconds": 0, - "phase-type": "UPLOAD_ARTIFACTS", - "phase-status": "SUCCEEDED" - }, - { - "phase-context": [], - "start-time": "Sep 1, 2017 4:14:21 PM", - "end-time": "Sep 1, 2017 4:14:26 PM", - "duration-in-seconds": 4, - "phase-type": "FINALIZING", - "phase-status": "SUCCEEDED" - }, - { - "start-time": "Sep 1, 2017 4:14:26 PM", - "phase-type": "COMPLETED" - } - ] - }, - "completed-phase-status": "SUCCEEDED", - "completed-phase-duration-seconds": 4, - "version": "1", - "completed-phase-start": "Sep 1, 2017 4:14:21 PM", - "completed-phase-end": "Sep 1, 2017 4:14:26 PM" - } -} -``` \ No newline at end of file diff --git a/doc_source/sample-buildspec-artifact-naming.md b/doc_source/sample-buildspec-artifact-naming.md deleted file mode 100644 index a8a2bd7..0000000 --- a/doc_source/sample-buildspec-artifact-naming.md +++ /dev/null @@ -1,82 +0,0 @@ -# Use semantic versioning to name build artifacts sample - - This sample contains example buildspec files that demonstrate how to specify an artifact name that is created at build time\. A name specified in a buildspec file can incorporate Shell commands and environment variables to make it unique\. A name you specify in a buildspec file overrides a name you enter in the console when you create your project\. - - If you build multiple times, using an artifact name specified in the buildspec file can ensure your output artifact file names are unique\. For example, you can use a date and timestamp that is inserted into an artifact name at build time\. - -If you want to override the artifact name you entered in the console with a name in the buildspec file, do the following: - -1. Set your build project to override the artifact name with a name in the buildspec file\. - + If you use the console to create your build project, select **Enable semantic versioning**\. For more information, see [Create a build project \(console\)](create-project-console.md)\. - + If you use the AWS CLI, set the `overrideArtifactName` to true in the JSON\-formatted file passed to `create-project`\. For more information, see [Create a build project \(AWS CLI\)](create-project-cli.md)\. - + If you use the AWS CodeBuild API, set the `overrideArtifactName` flag on the `ProjectArtifacts` object when a project is created or updated or a build is started\. - -1. Specify a name in the buildspec file\. Use the following sample buildspec files as a guide\. - - This Linux example shows you how to specify an artifact name that includes the date the build is created: - -``` -version: 0.2 -phases: - build: - commands: - - rspec HelloWorld_spec.rb -artifacts: - files: - - '**/*' - name: myname-$(date +%Y-%m-%d) -``` - - This Linux example shows you how to specify 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 Windows example shows you how to specify an artifact name that includes the date and time the build is created: - -``` -version: 0.2 -env: - variables: - TEST_ENV_VARIABLE: myArtifactName -phases: - build: - commands: - - cd samples/helloworld - - dotnet restore - - dotnet run -artifacts: - files: - - '**/*' - name: $Env:TEST_ENV_VARIABLE-$(Get-Date -UFormat "%Y%m%d-%H%M%S") -``` - - This Windows example shows you how to specify an artifact name that uses a variable declared in the buildspec file and a CodeBuild environment variable\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. - -``` -version: 0.2 -env: - variables: - TEST_ENV_VARIABLE: myArtifactName -phases: - build: - commands: - - cd samples/helloworld - - dotnet restore - - dotnet run -artifacts: - files: - - '**/*' - name: $Env:TEST_ENV_VARIABLE-$Env:AWS_REGION -``` - - For more information, see [Build specification reference for CodeBuild](build-spec-ref.md)\. \ No newline at end of file diff --git a/doc_source/sample-codedeploy.md b/doc_source/sample-codedeploy.md deleted file mode 100644 index 69acaf5..0000000 --- a/doc_source/sample-codedeploy.md +++ /dev/null @@ -1,173 +0,0 @@ -# CodeDeploy sample for CodeBuild - -This sample instructs AWS CodeBuild to use Maven to produce as build output a single JAR file named `my-app-1.0-SNAPSHOT.jar`\. This sample then uses CodeDeploy to deploy the JAR file to an Amazon Linux instance\. You can also use AWS CodePipeline to automate the use of CodeDeploy to deploy the JAR file to an Amazon Linux instance\. This sample is based on the [Maven in 5 Minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html) topic on the Apache Maven website\. - -**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)\. - -## Running the sample - -**To run this sample** - -1. Download and install Maven\. For more information, see [Downloading Apache Maven](https://maven.apache.org/download.cgi) and [Installing Apache Maven](https://maven.apache.org/install.html) on the Apache Maven website\. - -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-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false - ``` - - If successful, this directory structure and files are created\. - - ``` - . - └── 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 `my-app` directory\. - - ``` - version: 0.2 - - phases: - install: - runtime-versions: - java: corretto8 - build: - commands: - - echo Build started on `date` - - mvn test - post_build: - commands: - - echo Build completed on `date` - - mvn package - artifacts: - files: - - target/my-app-1.0-SNAPSHOT.jar - - appspec.yml - discard-paths: yes - ``` - -1. Create a file with this content\. Name the file `appspec.yml`, and then add it to the `my-app` directory\. - - ``` - version: 0.0 - os: linux - files: - - source: ./my-app-1.0-SNAPSHOT.jar - destination: /tmp - ``` - - When finished, your directory structure and file should look like this\. - - ``` - . - └── 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 `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 `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 - ``` - -1. Create a build project by following the steps in [Create a build project](create-project.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\.\) - - ``` - { - "name": "sample-codedeploy-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/CodeDeploySample.zip" - }, - "artifacts": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket", - "packaging": "ZIP", - "name": "CodeDeployOutputArtifact.zip" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "BUILD_GENERAL1_SMALL" - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` - -1. If you plan to deploy the build output artifact with CodeDeploy, follow the steps in [Run a build](run-build.md)\. Otherwise, skip this step\. \(This is because if you plan to deploy the build output artifact with CodePipeline, CodePipeline uses CodeBuild to run the build automatically\.\) - -1. Complete the setup steps for using CodeDeploy, including: - + Grant the IAM user access to CodeDeploy and the AWS services and actions CodeDeploy depends on\. For more information, see [Provision an IAM user](https://docs.aws.amazon.com/codedeploy/latest/userguide/getting-started-setup.html#getting-started-user) in the *AWS CodeDeploy User Guide*\. - + Create or identify a service role to enable CodeDeploy to identify the instances where it deploys the build output artifact\. For more information, see [Creating a service role for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-service-role.html) in the *AWS CodeDeploy User Guide*\. - + Create or identify an IAM instance profile to enable your instances to access the S3 input bucket or GitHub repository that contains the build output artifact\. For more information, see [Creating an IAM instance profile for your Amazon EC2 instances](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-iam-instance-profile.html) in the *AWS CodeDeploy User Guide*\. - -1. Create or identify an Amazon Linux instance compatible with CodeDeploy where the build output artifact is deployed\. For more information, see [Working with instances for CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-prepare-instances.html) in the *AWS CodeDeploy User Guide*\. - -1. Create or identify a CodeDeploy application and deployment group\. For more information, see [Creating an application with CodeDeploy](https://docs.aws.amazon.com/codedeploy/latest/userguide/how-to-create-application.html) in the *AWS CodeDeploy User Guide*\. - -1. Deploy the build output artifact to the instance\. - - 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 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`\. - -## Related resources -+ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-disable-artifact-encryption.md b/doc_source/sample-disable-artifact-encryption.md deleted file mode 100644 index 05752c0..0000000 --- a/doc_source/sample-disable-artifact-encryption.md +++ /dev/null @@ -1,49 +0,0 @@ -# Create a static website with build output hosted in an S3 bucket - - You can disable the encryption of artifacts in a build\. You might want to do this so that you can publish artifacts to a location that is configured to host a website\. \(You cannot publish encrypted artifacts\.\) This sample shows how you can use webhooks to trigger a build and publish its artifacts to an S3 bucket that is configured to be a website\. - -1. Follow the instructions in [Setting up a static website](https://docs.aws.amazon.com/AmazonS3/latest/dev/HostingWebsiteOnS3Setup.html) to configure an S3 bucket to function like a website\. - -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. 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**\. - - For **Webhook**, select **Rebuild every time a code change is pushed to this repository**\. You can select this check box only if you chose **Use a repository in my account**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/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. 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 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\. - + 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. 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**, choose **Amazon S3** to store the build output in an S3 bucket\. - -1. For **Bucket name**, choose the name of the S3 bucket you configured to function as a website in step 1\. - -1. If you chose **Insert build commands** in **Environment**, then for **Output files**, enter the locations of the files from the build that you want to put into the output bucket\. If you have more than one location, use a comma to separate each location \(for example, **appspec\.yml, target/my\-app\.jar**\)\. For more information, see [Artifacts reference-key in the buildspec file](build-spec-ref.md#artifacts-build-spec)\. - -1. Select **Disable artifacts encryption**\. - -1. Expand **Additional configuration** and choose options as appropriate\. - -1. Choose **Create build project**\. On the build project page, in **Build history**, choose **Start build** to run the build\. - -1. \(Optional\) Follow the instructions in [Example: Speed up your website with Amazon CloudFront](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-cloudfront-walkthrough.html) in the *Amazon S3 Developer Guide*\. \ No newline at end of file diff --git a/doc_source/sample-docker-custom-image.md b/doc_source/sample-docker-custom-image.md deleted file mode 100644 index 8bea6e3..0000000 --- a/doc_source/sample-docker-custom-image.md +++ /dev/null @@ -1,105 +0,0 @@ -# Docker in custom image sample for CodeBuild - -This sample builds and runs a Docker image by using AWS CodeBuild and a custom Docker build image \(`docker:dind` in Docker Hub\)\. - -To learn how to build a Docker image by using a build image provided by CodeBuild with Docker support instead, see our [Docker sample](sample-docker.md)\. - -**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, 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)\. - -**Topics** -+ [Running the sample](#sample-docker-custom-image-running) -+ [Directory structure](#sample-docker-custom-image-dir) -+ [Files](#sample-docker-custom-image-files) -+ [Related resources](#acb-more-info) - -## Running the sample - -**To run this sample** - -1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. -**Important** -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 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\.\) - - ``` - { - "name": "sample-docker-custom-image-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/DockerCustomImageSample.zip" - }, - "artifacts": { - "type": "NO_ARTIFACTS" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "docker:dind", - "computeType": "BUILD_GENERAL1_SMALL", - "privilegedMode": true - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` -**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\. - -1. To see the build results, look in the build's log for the string `Hello, World!`\. For more information, see [View build details](view-build-details.md)\. - -## Directory structure - -This sample assumes this directory structure\. - -``` -(root directory name) -├── buildspec.yml -└── Dockerfile -``` - -## Files - -The base image of the operating system used in this sample is Ubuntu\. The sample uses these files\. For more information about the OverlayFS storage driver referenced in the buildspec file, see [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/) on the Docker website\. - -`buildspec.yml` \(in `(root directory name)`\) - -``` -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 & - - timeout 15 sh -c "until docker info; do echo .; sleep 1; done" - pre_build: - commands: - - docker build -t helloworld . - build: - commands: - - docker images - - docker run helloworld echo "Hello, World!" -``` - -**Note** - If the base operating system is Alpine Linux, in the `buildspec.yml` add the `-t` argument to `timeout`: - -``` -- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done" -``` - -`Dockerfile` \(in `(root directory name)`\) - -``` -FROM maven:3.3.9-jdk-8 - -RUN echo "Hello World" -``` - -## Related resources -+ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-docker.md b/doc_source/sample-docker.md deleted file mode 100644 index 5039dcc..0000000 --- a/doc_source/sample-docker.md +++ /dev/null @@ -1,310 +0,0 @@ -# Docker sample for CodeBuild - -This sample produces as build output a Docker image and then pushes the Docker image to an Amazon Elastic Container Registry \(Amazon ECR\) image repository\. You can adapt this sample to push the Docker image to Docker Hub\. For more information, see [Adapting the sample to push the image to Docker Hub](#sample-docker-docker-hub)\. - -To learn how to build a Docker image by using a custom Docker build image \(`docker:dind` in Docker Hub\), see our [Docker in custom image sample](sample-docker-custom-image.md)\. - -This sample was tested referencing `golang:1.12`\. - -This sample uses the new multi\-stage Docker builds feature, which produces a Docker image as build output\. It then pushes the Docker image to an Amazon ECR image repository\. Multi\-stage Docker image builds help to reduce the size of the final Docker image\. For more information, see [Use multi\-stage builds with Docker](https://docs.docker.com/engine/userguide/eng-image/multistage-build/)\. - -**Important** -Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing)\. - -**Topics** -+ [Running the sample](#sample-docker-running) -+ [Directory structure](#sample-docker-dir) -+ [Files](#sample-docker-files) -+ [Adapting the sample to push the image to Docker Hub](#sample-docker-docker-hub) -+ [Related resources](#acb-more-info) - -## Running the sample - -**To run this sample** - -1. If you already have an image repository in Amazon ECR you want to use, skip to step 3\. Otherwise, if you are using an IAM user instead of an AWS root account or an administrator IAM user to work with Amazon ECR, add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the user \(or IAM group the user is associated with\)\. Using an AWS root account is not recommended\.This statement allows the creation of Amazon ECR repositories for storing Docker images\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. For more information, see [Working with inline policies using the AWS Management Console](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_inline-using.html#AddingPermissions_Console) in the *IAM User Guide*\. - - ``` - { - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Action": [ - "ecr:CreateRepository" - ], - "Resource": "*", - "Effect": "Allow" - }, - ### END ADDING STATEMENT HERE ### - ... - ], - "Version": "2012-10-17" - } - ``` -**Note** -The IAM entity that modifies this policy must have permission in IAM to modify policies\. - -1. Create an image repository in Amazon ECR\. Be sure to create the repository in the same AWS Region where you create your build environment and run your build\. For more information, see [Creating a repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) in the *Amazon ECR User Guide*\. This repository's name must match the repository name you specify later in this procedure, represented by the `IMAGE_REPO_NAME` environment variable\. - -1. Add this statement \(between *\#\#\# BEGIN ADDING STATEMENT HERE \#\#\#* and *\#\#\# END ADDING STATEMENT HERE \#\#\#*\) to the policy you attached to your AWS CodeBuild service role\. This statement allows CodeBuild to upload Docker images to Amazon ECR repositories\. Ellipses \(`...`\) are used for brevity and to help you locate where to add the statement\. Do not remove any statements, and do not type these ellipses into the policy\. - - ``` - { - "Statement": [ - ### BEGIN ADDING STATEMENT HERE ### - { - "Action": [ - "ecr:BatchCheckLayerAvailability", - "ecr:CompleteLayerUpload", - "ecr:GetAuthorizationToken", - "ecr:InitiateLayerUpload", - "ecr:PutImage", - "ecr:UploadLayerPart" - ], - "Resource": "*", - "Effect": "Allow" - }, - ### END ADDING STATEMENT HERE ### - ... - ], - "Version": "2012-10-17" - } - ``` -**Note** -The IAM entity that modifies this policy must have permission in IAM to modify policies\. - -1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. -**Important** -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 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: - - 1. For **Operating system**, choose **Ubuntu**\. - - 1. For **Runtime**, choose **Standard**\. - - 1. For **Image**, choose **aws/codebuild/standard:4\.0**\. - - 1. Because you use this build project to build a Docker image, select **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\. - - 1. Add the following environment variables: - + AWS\_DEFAULT\_REGION with a value of *region\-ID* - + AWS\_ACCOUNT\_ID with a value of *account\-ID* - + IMAGE\_TAG with a value of Latest - + IMAGE\_REPO\_NAME with a value of *Amazon\-ECR\-repo\-name* - - 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\.\) - - ``` - { - "name": "sample-docker-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/DockerSample.zip" - }, - "artifacts": { - "type": "NO_ARTIFACTS" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "BUILD_GENERAL1_SMALL", - "environmentVariables": [ - { - "name": "AWS_DEFAULT_REGION", - "value": "region-ID" - }, - { - "name": "AWS_ACCOUNT_ID", - "value": "account-ID" - }, - { - "name": "IMAGE_REPO_NAME", - "value": "Amazon-ECR-repo-name" - }, - { - "name": "IMAGE_TAG", - "value": "latest" - } - ], - "privilegedMode": true - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` - -1. Confirm that CodeBuild successfully pushed the Docker image to the repository: - - 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. - - 1. Choose the repository name\. The image should be listed in the **Image tag** column\. - -## Directory structure - -This sample assumes this directory structure\. - -``` -(root directory name) -├── buildspec.yml -└── Dockerfile -``` - -## Files - -This sample uses these files\. - -`buildspec.yml` \(in `(root directory name)`\) - -``` -version: 0.2 - -phases: - pre_build: - commands: - - echo Logging in to Amazon ECR... - - 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` - - echo Building the Docker image... - - docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG . - - docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG - post_build: - commands: - - echo Build completed on `date` - - echo Pushing the Docker image... - - docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG -``` - -`Dockerfile` \(in `(root directory name)`\) - -``` -FROM golang:1.12-alpine AS build -#Install git -RUN apk add --no-cache git -#Get the hello world package from a GitHub repository -RUN go get github.com/golang/example/hello -WORKDIR /go/src/github.com/golang/example/hello -# Build the project and send the output to /bin/HelloWorld -RUN go build -o /bin/HelloWorld - -FROM golang:1.12-alpine -#Copy the build's output binary from the previous build container -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\. -**Note** -If you are using a version of Docker earlier than 17\.06, remove the `--no-include-email` option\. - -1. Replace these Amazon ECR\-specific lines of code in the `buildspec.yml` file: - - ``` - ... - pre_build: - commands: - - echo Logging in to Amazon ECR... - - 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` - - echo Building the Docker image... - - docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG . - - docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG - post_build: - commands: - - echo Build completed on `date` - - echo Pushing the Docker image... - - docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG - ... - ``` - - With these Docker Hub\-specific lines of code: - - ``` - ... - pre_build: - commands: - - echo Logging in to Docker Hub... - # Type the command to log in to your Docker Hub account here. - build: - commands: - - echo Build started on `date` - - echo Building the Docker image... - - docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG . - - docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $IMAGE_REPO_NAME:$IMAGE_TAG - post_build: - commands: - - echo Build completed on `date` - - echo Pushing the Docker image... - - docker push $IMAGE_REPO_NAME:$IMAGE_TAG - ... - ``` - -1. Upload the edited code to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. -**Important** -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. Replace these lines of code from the JSON\-formatted input to the `create-project` command: - - ``` - ... - "environmentVariables": [ - { - "name": "AWS_DEFAULT_REGION", - "value": "region-ID" - }, - { - "name": "AWS_ACCOUNT_ID", - "value": "account-ID" - }, - { - "name": "IMAGE_REPO_NAME", - "value": "Amazon-ECR-repo-name" - }, - { - "name": "IMAGE_TAG", - "value": "latest" - } - ] - ... - ``` - - With these lines of code: - - ``` - ... - "environmentVariables": [ - { - "name": "IMAGE_REPO_NAME", - "value": "your-Docker-Hub-repo-name" - }, - { - "name": "IMAGE_TAG", - "value": "latest" - } - ] - ... - ``` - -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\. - -## Related resources -+ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-ecr.md b/doc_source/sample-ecr.md deleted file mode 100644 index a18922a..0000000 --- a/doc_source/sample-ecr.md +++ /dev/null @@ -1,250 +0,0 @@ -# Amazon ECR sample for CodeBuild - -This sample uses a Docker image in an Amazon Elastic Container Registry \(Amazon ECR\) image repository to build a sample Go project\. - -**Important** -Running this sample might result in charges to your AWS account\. These include possible charges for AWS CodeBuild and for AWS resources and actions related to Amazon S3, AWS KMS, CloudWatch Logs, and Amazon ECR\. 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 Elastic Container Registry pricing](http://aws.amazon.com/ecr/pricing)\. - -## Running the sample - -**To run this sample** - -1. To create and push the Docker image to your image repository in Amazon ECR, complete the steps in the "Running the sample" section of the [Docker sample](sample-docker.md)\. - -1. Create a Go project: - - 1. Create the files as described in the [Go project structure](#ecr-sample-go-project-file-structure) and [Go project files](#sample-ecr-go-project-files) sections of this topic, and then upload them to an S3 input bucket or an AWS CodeCommit, GitHub, or Bitbucket repository\. -**Important** -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 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\.\) - - ``` - { - "name": "sample-go-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/GoSample.zip" - }, - "artifacts": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket", - "packaging": "ZIP", - "name": "GoOutputArtifact.zip" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "BUILD_GENERAL1_SMALL" - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` - - 1. To get the build output artifact, open your S3 output bucket\. - - 1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the file\. In the extracted contents, get the `hello` file\. - -1. If one of the following is true, you must add permissions to your image repository in Amazon ECR so that AWS CodeBuild can pull its Docker image into the build environment\. - + Your project uses CodeBuild credentials to pull Amazon ECR images\. This is denoted by a value of `CODEBUILD` in the `imagePullCredentialsType` attribute of your `ProjectEnvironment`\. - + Your project uses a cross\-account Amazon ECR image\. In this case, your project must use its service role to pull Amazon ECR images\. To enable this behavior, set the `imagePullCredentialsType` attribute of your `ProjectEnvironment` to `SERVICE_ROLE`\. - - 1. Open the Amazon ECR console at [https://console\.aws\.amazon\.com/ecr/](https://console.aws.amazon.com/ecr/)\. - - 1. In the list of repository names, choose the name of the repository you created or selected\. - - 1. From the navigation pane, choose **Permissions**, choose **Edit**, and then choose **Add statement**\. - - 1. For **Statement name**, enter an identifier \(for example, **CodeBuildAccess**\)\. - - 1. For **Effect**, leave **Allow** selected\. This indicates that you want to allow access to another AWS account\. - - 1. For **Principal**, do one of the following: - + If your project uses CodeBuild credentials to pull an Amazon ECR image, in **Service principal**, enter **codebuild\.amazonaws\.com**\. - + If your project uses a cross\-account Amazon ECR image, for **AWS account IDs**, enter IDs of the AWS accounts that you want to give access\. - - 1. Skip the **All IAM entities** list\. - - 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: - + If your project uses CodeBuild credentials to pull an Amazon ECR image, `"codebuild.amazonaws.com"` appears under **Service principals**\. - + If your project uses a cross\-account Amazon ECR image, the ID of the AWS account that you want to give access appears under **AWS Account IDs**\. - - 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", - "Statement":[ - { - "Sid":"CodeBuildAccessPrincipal", - "Effect":"Allow", - "Principal":{ - "Service":"codebuild.amazonaws.com" - }, - "Action":[ - "ecr:GetDownloadUrlForLayer", - "ecr:BatchGetImage", - "ecr:BatchCheckLayerAvailability" - ] - }, - { - "Sid":"CodeBuildAccessCrossAccount", - "Effect":"Allow", - "Principal":{ - "AWS":"arn:aws:iam:::root" - }, - "Action":[ - "ecr:GetDownloadUrlForLayer", - "ecr:BatchGetImage", - "ecr:BatchCheckLayerAvailability" - ] - } - ] - } - ``` - -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\.\) - - ``` - { - "name": "amazon-ecr-sample-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/GoSample.zip" - }, - "artifacts": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket", - "packaging": "ZIP", - "name": "GoOutputArtifact.zip" - }, - "environment": { - "type": "LINUX_CONTAINER", - "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", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` - -1. To get the build output artifact, open your S3 output bucket\. - -1. Download the `GoOutputArtifact.zip` file to your local computer or instance, and then extract the contents of the `GoOutputArtifact.zip` file\. In the extracted contents, get the `hello` file\. - -## Go project structure - -This sample assumes this directory structure\. - -``` -(root directory name) -├── buildspec.yml -└── hello.go -``` - -## Go project files - -This sample uses these files\. - -`buildspec.yml` \(in `(root directory name)`\) - -``` -version: 0.2 - -phases: - install: - runtime-versions: - golang: 1.13 - build: - commands: - - echo Build started on `date` - - echo Compiling the Go code - - go build hello.go - post_build: - commands: - - echo Build completed on `date` -artifacts: - files: - - hello -``` - -`hello.go` \(in `(root directory name)`\) - -``` -package main -import "fmt" - -func main() { - fmt.Println("hello world") - fmt.Println("1+1 =", 1+1) - fmt.Println("7.0/3.0 =", 7.0/3.0) - fmt.Println(true && false) - fmt.Println(true || false) - fmt.Println(!true) -} -``` - -## Related resources -+ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-efs.md b/doc_source/sample-efs.md deleted file mode 100644 index 16b1be4..0000000 --- a/doc_source/sample-efs.md +++ /dev/null @@ -1,178 +0,0 @@ -# Amazon Elastic File System sample for AWS CodeBuild - - You might want to create your AWS CodeBuild builds on Amazon Elastic File System, a scalable, shared file service for Amazon EC2 instances\. The storage capacity with Amazon EFS is elastic, so it grows or shrinks as files are added and removed\. It has a simple web services interface that you can use to create and configure file systems\. It also manages all of the file storage infrastructure for you, so you do not need to worry about deploying, patching, or maintaining file system configurations\. For more information, see [What is Amazon Elastic File System?](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) in the *Amazon Elastic File System User Guide*\. - - This sample shows you how to configure a CodeBuild project so that it mounts and then builds a Java application to an Amazon EFS file system\. Before you begin, you must have a Java application ready to build that is uploaded to an S3 input bucket or an AWS CodeCommit, GitHub, GitHub Enterprise Server, or Bitbucket repository\. - -Data in transit for your file system is encrypted\. To encrypt data in transit using a different image, see [Encrypting data in transit](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)\. - -## High\-level steps - - This sample covers the three high\-level steps required to use Amazon EFS with AWS CodeBuild: - -1. Create a virtual private cloud \(VPC\) in your AWS account\. - -1. Create a file system that uses this VPC\. - -1. Create and build a CodeBuild project that uses the VPC\. The CodeBuild project uses the following to identify the file system: - + A unique file system identifier\. You choose the identifier when you specify the file system in your build project\. - + The file system ID\. The ID is displayed when you view your file system in the Amazon EFS console\. - + A mount point\. This is a directory in your Docker container that mounts the file system\. - + Mount options\. These include details about how to mount the file system\. - -**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\. - -1. Follow the instructions in [AWS CloudFormation VPC template](cloudformation-vpc-template.md) to use AWS CloudFormation to create a VPC\. -**Note** - The VPC created by this AWS CloudFormation template has two private subnets and two public subnets\. You must only use private subnets when you use AWS CodeBuild to mount the file system you created in Amazon EFS\. If you use one of the public subnets, the build fails\. - -1. Sign in to the AWS Management Console and open the Amazon VPC console at [https://console\.aws\.amazon\.com/vpc/](https://console.aws.amazon.com/vpc/)\. - -1. Choose the VPC you created with AWS CloudFormation\. - -1. On the **Description** tab, make a note of the name of your VPC and its ID\. Both are required when you create your AWS CodeBuild project later in this sample\. - -## Create an Amazon Elastic File System file system with your VPC - - Create a simple Amazon EFS file system for this sample using the VPC you created earlier\. - -1. Sign in to the AWS Management Console and open the Amazon EFS console at [ https://console\.aws\.amazon\.com/efs/](https://console.aws.amazon.com/efs/)\. - -1. Choose **Create file system**\. - -1. From **VPC**, choose the VPC name you noted earlier in this sample\. - -1. Leave the Availability Zones associated with your subnets selected\. - -1. Choose **Next Step**\. - -1. In **Add tags**, for the default **Name** key, in **Value**, enter the name of your Amazon EFS file system\. - -1. Keep **Bursting** and **General Purpose** selected as your default performance and throughput modes, and then choose **Next Step**\. - -1. For **Configure client access**, choose **Next Step**\. - -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\. - -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. From the navigation pane, choose **Build projects**, and then choose **Create build project**\. - -1. In **Project name**, enter a name for your project\. - -1. From **Source provider**, choose the repository that contains the Java application you want to build\. - -1. Enter information, such as a repository URL, that CodeBuild uses to locate your application\. The options are different for each source provider\. For more information, see [Choose source provider](create-project-console.md#create-project-source-provider)\. - -1. From **Environment image**, choose **Managed image**\. - -1. From **Operating system**, choose **Amazon Linux 2**\. - -1. From **Runtime\(s\)**, choose **Standard**\. - -1. From **Image**, choose **aws/codebuild/amazonlinux2\-x86\_64\-standard:3\.0**\. - -1. From **Environment type**, choose **Linux**\. - -1. Select **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\. - -1. Under **Service role**, choose **New service role**\. In **Role name**, enter a name for the role CodeBuild creates for you\. - -1. Expand **Additional configuration**\. - -1. From **VPC**, choose the VPC ID\. - -1. From **Subnets**, choose one or more of the private subnets associated with your VPC\. You must use private subnets in a build that mounts an Amazon EFS file system\. If you use a public subnet, the build fails\. - -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_` 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 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 - phases: - install: - runtime-versions: - java: corretto11 - build: - commands: - - 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\. - -1. Choose **Start build**\. - -## 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*\. - -## 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 deleted file mode 100644 index 660f230..0000000 --- a/doc_source/sample-elastic-beanstalk.md +++ /dev/null @@ -1,341 +0,0 @@ -# AWS Elastic Beanstalk sample for CodeBuild - -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)\. - -## Create the source code - -In this section, you use Maven to produce the source code\. Later, you use CodeBuild to build a WAR file based on this source code\. - -1. Download and install Maven\. For information, see [Downloading Apache Maven](https://maven.apache.org/download.cgi) and [Installing Apache Maven](https://maven.apache.org/install.html) on the Apache Maven website\. - -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=ROOT" "-DarchetypeArtifactId=maven-archetype-webapp" "-DinteractiveMode=false" - ``` - - If successful, this directory structure and files are created\. - - ``` - . - └── ROOT - ├── pom.xml - └── src - └── main - ├── resources - └── webapp - ├── WEB-INF - │ └── web.xml - └── index.jsp - ``` - -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 ROOT.war 2>&1 > /var/log/my_last_deploy.log" - ``` - -After you run Maven, continue with one of the following scenarios: -+ [Scenario A: Run CodeBuild manually and deploy to Elastic Beanstalk manually](#sample-elastic-beanstalk-manual) -+ [Scenario B: Use CodePipeline to run CodeBuild and deploy to Elastic Beanstalk](#sample-elastic-beanstalk-codepipeline) -+ [Scenario C: Use the Elastic Beanstalk CLI to run AWS CodeBuild and deploy to an Elastic Beanstalk environment](#sample-elastic-beanstalk-eb-cli) - -## Scenario A: Run CodeBuild manually and deploy to Elastic Beanstalk manually - -In this scenario, you create and upload the source code\. You then use the AWS CodeBuild and AWS Elastic Beanstalk consoles to build the source code, create an Elastic Beanstalk application and environment, and deploy the build output to the environment\. - -### Step a1: Add files to the source code - -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\. - - ``` - version: 0.2 - - phases: - install: - runtime-versions: - java: corretto11 - post_build: - commands: - - mvn package - - mv target/ROOT.war ROOT.war - artifacts: - files: - - ROOT.war - - .ebextensions/**/* - ``` - -1. Your file structure should now look like this\. - - ``` - . - └── 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 `ROOT` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. -**Important** -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 - -In this step, you use the AWS CodeBuild console to create a build project and then run a build\. - -1. Create or choose an S3 output bucket to store the build output\. 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. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - - Use the AWS region selector to choose an AWS Region where CodeBuild is supported\. This must be the same Region where your S3 output bucket is stored\. - -1. Create a build project and then run a build\. 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 **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:3\.0**\. - + For **Artifacts**: - + For **Type**, choose **Amazon S3**\. - + For **Bucket name**, enter the name of an S3 bucket\. - + For **Name**, enter a build output file name that's easy for you to remember\. Include the `.zip` extension\. - + For **Artifacts packaging**, choose **Zip**\. - -### Step a3: Create the application and environment and deploy - -In this step, you use the AWS Elastic Beanstalk console to create an application and environment\. As part of creating the environment, you deploy the build output from the previous step to the environment\. - -1. Open the AWS Elastic Beanstalk console at [https://console\.aws\.amazon\.com/elasticbeanstalk](https://console.aws.amazon.com/elasticbeanstalk)\. - - Use the AWS Region selector to choose the AWS Region where your S3 output bucket is stored\. - -1. Create an Elastic Beanstalk application\. For more information, see [Managing and configuring AWS Elastic Beanstalk applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. - -1. Create an Elastic Beanstalk environment for this application\. For more information, see [The create new environment wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Leave all settings at their default values, except for these settings\. - + For **Platform**, choose **Tomcat**\. - + For **Application code**, choose **Upload your code**, and then choose **Upload**\. For **Source code origin**, choose **Public S3 URL**, and then enter the full URL to the build output ZIP file in the output bucket\. Choose **Upload**\. - -1. After Elastic Beanstalk deploys the build output to the environment, you can see the results in a web browser\. Go to the environment URL for the instance \(for example, `http://my-environment-name.random-string.region-ID.elasticbeanstalk.com`\)\. The web browser should display the text `Hello World!`\. - -## Scenario B: Use CodePipeline to run CodeBuild and deploy to Elastic Beanstalk - -In this scenario, you complete the steps to prepare and upload the source code\. You create a build project with CodeBuild and an Elastic Beanstalk application and environment with the AWS Elastic Beanstalk console\. You then use the AWS CodePipeline console to create a pipeline\. After you create the pipeline, CodePipeline builds the source code and deploys the build output to the environment\. - -### Step b1: Add a buildspec file to 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\. - - ``` - version: 0.2 - - phases: - install: - runtime-versions: - java: corretto11 - post_build: - commands: - - mvn package - - mv target/ROOT.war ROOT.war - artifacts: - files: - - ROOT.war - - .ebextensions/**/* - ``` - -1. Your file structure should now look like this\. - - ``` - . - └── 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 `ROOT` directory to an S3 input bucket or a CodeCommit, GitHub, or Bitbucket repository\. -**Important** -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 - -In this step, you create an AWS CodeBuild build project to use with your pipeline\. - -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 **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:3\.0**\. - + For **Artifacts**: - + For **Type**, choose **Amazon S3**\. - + For **Bucket name**, enter the name of an S3 bucket\. - + For **Name**, enter a build output file name that's easy for you to remember\. Include the `.zip` extension\. - + For **Artifacts packaging**, choose **Zip**\. - -### Step b3: Create an Elastic Beanstalk application and environment - -In this step, you create an Elastic Beanstalk application and environment to use with CodePipeline\. - -1. Open the Elastic Beanstalk console at [https://console\.aws\.amazon\.com/elasticbeanstalk/](https://console.aws.amazon.com/elasticbeanstalk/)\. - -1. Use the AWS Elastic Beanstalk console to create an application\. For more information, see [Managing and configuring AWS Elastic Beanstalk applications](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/applications.html) in the *AWS Elastic Beanstalk Developer Guide*\. - -1. Use the AWS Elastic Beanstalk console to create an environment\. For more information, see [The create new environment wizard](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-create-wizard.html) in the *AWS Elastic Beanstalk Developer Guide*\. Except for **Platform**, leave all settings at their default values\. For **Platform**, choose **Tomcat**\. - -### Step b4: Create the pipeline and deploy - -In this step, you use the AWS CodePipeline console to create a pipeline\. After you create and run the pipeline, CodePipeline uses CodeBuild to build the source code\. CodePipeline then uses Elastic Beanstalk to deploy the build output to the environment\. - -1. Create or identify a service role that CodePipeline, CodeBuild, and Elastic Beanstalk can use to access resources on your behalf\. For more information, see [Prerequisites](how-to-create-pipeline.md#how-to-create-pipeline-prerequisites)\. - -1. Open the CodePipeline console at [https://console\.aws\.amazon\.com/codesuite/codepipeline/home](https://console.aws.amazon.com/codesuite/codepipeline/home)\. - - 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-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\. - + For **Environment name**, choose the environment you just created\. - -1. After the pipeline has run successfully, you can see the results in a web browser\. Go to the environment URL for the instance \(for example, `http://my-environment-name.random-string.region-ID.elasticbeanstalk.com`\)\. The web browser should display the text `Hello World!`\. - -Now, whenever you make changes to the source code and upload those changes to the original S3 input bucket or to the CodeCommit, GitHub, or Bitbucket repository, CodePipeline detects the change and runs the pipeline again\. This causes CodeBuild to rebuild the code and then causes Elastic Beanstalk to deploy the rebuilt output to the environment\. - -## Scenario C: Use the Elastic Beanstalk CLI to run AWS CodeBuild and deploy to an Elastic Beanstalk environment - -In this scenario, you complete the steps to prepare and upload the source code\. You then run the Elastic Beanstalk CLI to create an Elastic Beanstalk application and environment, use CodeBuild to build the source code, and then deploy the build output to the environment\. For more information, see [Using the EB CLI with CodeBuild](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/eb-cli-codebuild.html) in the *AWS Elastic Beanstalk Developer Guide*\. - -### Step c1: Add files to the source code - -In this step, you add an Elastic Beanstalk configuration file and a buildspec file to the code you created in [Create the source code](#sample-elastic-beanstalk-prepare-source)\. You also create or identify a service role for the buildspec file\. - -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\. - - ``` - version: 0.2 - - phases: - install: - runtime-versions: - java: corretto11 - post_build: - commands: - - mvn package - - mv target/ROOT.war ROOT.war - artifacts: - files: - - ROOT.war - - .ebextensions/**/* - eb_codebuild_settings: - CodeBuildServiceRole: my-service-role-name - ComputeType: BUILD_GENERAL1_SMALL - Image: aws/codebuild/standard:4.0 - Timeout: 60 - ``` - - In the preceding code, replace *my\-service\-role\-name* with the name of the service role you created or identified earlier\. - -1. Your file structure should now look like this\. - - ``` - . - └── 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)/ROOT` directory\. Run the eb init command to configure the EB CLI\. - - ``` - eb init - ``` - - When prompted: - + Choose an AWS Region where AWS CodeBuild is supported and where you want to create your Elastic Beanstalk application and environment\. - + Create an Elastic Beanstalk application, and enter a name for the application\. - + Choose the `Tomcat` platform\. - + Choose the `Tomcat 8 Java 8` version\. - + Choose whether you want to use SSH to set up access to your environment's instances\. - -1. From the same directory, run the eb create command to create an Elastic Beanstalk environment\. - - ``` - eb create - ``` - - When prompted: - + Enter the name for the environment or accept the suggested name\. - + Enter the DNS CNAME prefix for the environment or accept the suggested value\. - + For this sample, accept the Classic load balancer type\. - -1. After you run the eb create command, the EB CLI does the following: - - 1. Creates a ZIP file from the source code and then uploads the ZIP file to an S3 bucket in your account\. - - 1. Creates an Elastic Beanstalk application and application version\. - - 1. Creates a CodeBuild project\. - - 1. Runs a build based on the new project\. - - 1. Deletes the project after the build is complete\. - - 1. Creates an Elastic Beanstalk environment\. - - 1. Deploys the build output to the environment\. - -1. After the EB CLI deploys the build output to the environment, you can see the results in a web browser\. Go to the environment URL for the instance \(for example, `http://my-environment-name.random-string.region-ID.elasticbeanstalk.com`\)\. The web browser should display the text `Hello World!`\. - -If you want, you can make changes to the source code and then run the eb deploy command from the same directory\. The EB CLI performs the same steps as the eb create command, but it deploys the build output to the existing environment instead of creating a new environment\. - -## Related resources -+ For information about getting started with AWS CodeBuild, see [Getting started with AWS CodeBuild using the console](getting-started.md)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/sample-github-enterprise.md b/doc_source/sample-github-enterprise.md deleted file mode 100644 index 49646e8..0000000 --- a/doc_source/sample-github-enterprise.md +++ /dev/null @@ -1,127 +0,0 @@ -# GitHub Enterprise Server sample for CodeBuild - -AWS CodeBuild supports GitHub Enterprise Server as a source repository\. This sample shows how to set up your CodeBuild projects when your GitHub Enterprise Server repository has a certificate installed\. It also shows how to enable webhooks so that CodeBuild rebuilds the source code every time a code change is pushed to your GitHub Enterprise Server repository\. - -## Prerequisites - -1. Generate a personal access token for your CodeBuild project\. We recommend that you create a GitHub Enterprise user and generate a personal access token for this user\. Copy it to your clipboard so that it can be used 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\. - - When you create the personal access token, include the **repo** scope in the definition\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/scopes.png) - -1. Download your certificate from GitHub Enterprise Server\. CodeBuild uses the certificate to make a trusted SSL connection to the repository\. - - **Linux/macOS clients:** - - From a terminal window, run the following command: - - ``` - echo -n | openssl s_client -connect HOST:PORTNUMBER \ - | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /folder/filename.pem - ``` - - Replace the placeholders in the command with the following values: - - *HOST*\. The IP address of your GitHub Enterprise Server repository\. - - *PORTNUMBER*\. The port number you are using to connect \(for example, 443\)\. - - *folder*\. The folder where you downloaded your certificate\. - - *filename*\. The file name of your certificate file\. -**Important** -Save the certificate as a \.pem file\. - - **Windows clients:** - - Use your browser to download your certificate from GitHub Enterprise Server\. To see the site's certificate details, choose the padlock icon\. For information about how to export the certificate, see your browser documentation\. -**Important** -Save the certificate as a \.pem file\. - -1. Upload your certificate file to an S3 bucket\. For information about how to create an S3 bucket, see [How do I create an S3 Bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-bucket.html) For information about how to upload objects to an S3 bucket, see [How do I upload files and folders to a bucket?](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/upload-objects.html) -**Note** -This bucket must be in the same AWS region as your builds\. For example, if you instruct CodeBuild to run a build in the US East \(Ohio\) Region, the bucket must be in the US East \(Ohio\) Region\. - -## Create a build project with GitHub Enterprise Server as the source repository and enable webhooks \(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. 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\. -**Note** -You only need to enter and save the personal access token once\. All future AWS CodeBuild projects use this token\. - + In **Repository URL**, enter the path to your repository, including the name of the repository\. - + Expand **Additional configuration**\. - + Select **Rebuild every time a code change is pushed to this repository** to rebuild every time a code change is pushed to this repository\. - + Select **Enable insecure SSL** to ignore SSL warnings while you connect to your GitHub Enterprise Server project repository\. -**Note** -We recommend that you use **Enable insecure SSL** for testing only\. It should not be used in a production environment\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-enterprise.png) - -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 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\. - + 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**\. - - 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)\. - -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: - + 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. 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)\. - -1. Choose **Create build project**\. On the build project page, choose **Start build**\. - -1. If you enabled webhooks in **Source**, a **Create webhook** dialog box is displayed with values for **Payload URL** and **Secret**\. -**Important** -The **Create webhook** dialog box appears only once\. Copy the payload URL and secret key\. You need them when you add a webhook in GitHub Enterprise Server\. -If you need to generate a payload URL and secret key again, you must first delete the webhook from your GitHub Enterprise Server repository\. In your CodeBuild project, clear the **Webhook** check box and then choose **Save**\. You can then create or update a CodeBuild project with the **Webhook** check box selected\. The **Create webhook** dialog box appears again\. - -1. In GitHub Enterprise Server, choose the repository where your CodeBuild project is stored\. - -1. Choose **Settings**, choose **Hooks & services**, and then choose **Add webhook**\. - -1. Enter the payload URL and secret key, accept the defaults for the other fields, and then choose **Add webhook**\. -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/ghe-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. Return to your CodeBuild project\. Close the **Create webhook** dialog box and choose **Start build**\. \ No newline at end of file diff --git a/doc_source/sample-github-pull-request.md b/doc_source/sample-github-pull-request.md deleted file mode 100644 index 95f5a99..0000000 --- a/doc_source/sample-github-pull-request.md +++ /dev/null @@ -1,92 +0,0 @@ -# GitHub pull request and webhook filter sample for CodeBuild - -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** -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\) - -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. Choose **Create build project**\. - -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. 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 **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\. - - 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 about GitHub webhook event types and filters, see [GitHub webhook events](github-webhook.md)\. - -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\. - -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**: -**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\. - -1. Choose **Create build project**\. On the **Review** page, choose **Start build** to run the build\. - -## Verification checks - -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 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 the **Build details** tab\. - -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\. \ No newline at end of file diff --git a/doc_source/sample-multi-in-out.md b/doc_source/sample-multi-in-out.md deleted file mode 100644 index e43b9f5..0000000 --- a/doc_source/sample-multi-in-out.md +++ /dev/null @@ -1,142 +0,0 @@ -# Multiple input sources and output artifacts sample - -You can create an AWS CodeBuild build project with more than one input source and more than one set of output artifacts\. This sample shows you how to set up a build project that: -+ Uses multiple sources and repositories of varying types\. -+ Publishes build artifacts to multiple S3 buckets in a single build\. - - In this sample, you create a build project and use it to run a build\. The sample uses the build project's buildspec file to show you how to incorporate more than one source and create more than one set of artifacts\. - -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 runs your buildspec file\. - -1. Create a build project\. For more information, see [Create a build project in AWS CodeBuild](create-project.md)\. - -1. Follow the instructions in [Run AWS CodeBuild directly](how-to-run.md) to create your build project, run the build, and get information about the build\. - -1. If you use the AWS CLI to create the build project, the JSON\-formatted input to the `create-project` command might look similar to the following: - - ``` - { - "name": "sample-project", - "source": { - "type": "S3", - "location": "bucket/sample.zip" - }, - "secondarySources": [ - { - "type": "CODECOMMIT", - "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", - "sourceIdentifier": "source2" - } - ], - "secondaryArtifacts": [ - { - "type": "S3", - "location": "output-bucket", - "artifactIdentifier": "artifact1" - }, - { - "type": "S3", - "location": "other-output-bucket", - "artifactIdentifier": "artifact2" - } - ], - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "BUILD_GENERAL1_SMALL" - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` - - Your primary source is defined under the `source` attribute\. All other sources are called secondary sources and appear under `secondarySources`\. All secondary sources are installed in their own directory\. This directory is stored in the built\-in environment variable `CODEBUILD_SRC_DIR_sourceIdentifer`\. For more information, see [Environment variables in build environments](build-env-ref-env-vars.md)\. - - The `secondaryArtifacts` attribute contains a list of artifact definitions\. These artifacts use the `secondary-artifacts` block of the buildspec file that is nested inside the `artifacts` block\. - - Secondary artifacts in the buildspec file have the same structure as artifacts and are separated by their artifact identifier\. - -**Note** - In the [CodeBuild API](https://docs.aws.amazon.com/codebuild/latest/APIReference/), the `artifactIdentifier` on a secondary artifact is a required attribute in `CreateProject` and `UpdateProject`\. It must be used to reference a secondary artifact\. - - Using the preceding JSON\-formatted input, the buildspec file for the project might look like: - -``` -version: 0.2 - -phases: - install: - runtime-versions: - java: openjdk11 - build: - commands: - - cd $CODEBUILD_SRC_DIR_source1 - - touch file1 - - cd $CODEBUILD_SRC_DIR_source2 - - touch file2 - -artifacts: - files: - - '**.*' - secondary-artifacts: - artifact1: - base-directory: $CODEBUILD_SRC_DIR_source1 - files: - - file1 - artifact2: - base-directory: $CODEBUILD_SRC_DIR_source2 - files: - - file2 -``` - - You can override the version of the primary source using the API with the `sourceVersion` attribute in `StartBuild`\. To override one or more secondary source versions, use the `secondarySourceVersionOverride` attribute\. - - The JSON\-formatted input to the the `start-build` command in the AWS CLI might look like: - -``` -{ - "projectName": "sample-project", - "secondarySourcesVersionOverride": [ - { - "sourceIdentifier": "source1", - "sourceVersion": "codecommit-branch" - }, - { - "sourceIdentifier": "source2", - "sourceVersion": "github-branch" - }, - ] -} -``` - -## Project without a source sample - - You can configure a CodeBuild project by choosing the **NO\_SOURCE** source type when you configure your source\. When your source type is **NO\_SOURCE**, you cannot specify a buildspec file because your project does not have a source\. Instead, you must specify a YAML\-formatted buildspec string in the `buildspec` attribute of the JSON\-formatted input to the `create-project` CLI command\. It might look like this: - -``` -{ - "name": "project-name", - "source": { - "type": "NO_SOURCE", - "buildspec": "version: 0.2\n\nphases:\n build:\n commands:\n - command" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "BUILD_GENERAL1_SMALL", - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" -} -``` - -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 diff --git a/doc_source/sample-pipeline-batch.md b/doc_source/sample-pipeline-batch.md deleted file mode 100644 index 5cb39db..0000000 --- a/doc_source/sample-pipeline-batch.md +++ /dev/null @@ -1,277 +0,0 @@ -# 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 deleted file mode 100644 index 30d509d..0000000 --- a/doc_source/sample-pipeline-multi-input-output.md +++ /dev/null @@ -1,132 +0,0 @@ -# AWS CodePipeline integration with CodeBuild and multiple input sources and output artifacts sample - -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 [CodePipeline pipeline structure reference](https://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html) in the *AWS CodePipeline User Guide*\. - -``` -{ - "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": "artifact1" - }, - { - "name": "artifact2" - } - ], - "configuration": { - "ProjectName": "my-build-project-name", - "PrimarySource": "source1" - }, - "runOrder": 1 - } - ] - } - ], - "artifactStore": { - "type": "S3", - "location": "AWS-CodePipeline-internal-bucket-name" - }, - "name": "my-pipeline-name", - "version": 1 - } -} -``` - - In this JSON file: -+ 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 - - phases: - build: - commands: - - touch source1_file - - cd $CODEBUILD_SRC_DIR_source2 - - touch source2_file - - artifacts: - files: - - '**/*' - secondary-artifacts: - artifact1: - base-directory: $CODEBUILD_SRC_DIR - files: - - source1_file - artifact2: - base-directory: $CODEBUILD_SRC_DIR_source2 - files: - - source2_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-private-registry.md b/doc_source/sample-private-registry.md deleted file mode 100644 index b8c230b..0000000 --- a/doc_source/sample-private-registry.md +++ /dev/null @@ -1,59 +0,0 @@ -# Private registry with AWS Secrets Manager sample for CodeBuild - - This sample shows you how to use a Docker image that is stored in a private registry as your AWS CodeBuild runtime environment\. The credentials for the private registry are stored in AWS Secrets Manager\. Any private registry works with CodeBuild\. This sample uses Docker Hub\. - -## Private registry sample requirements - - To use a private registry with AWS CodeBuild, you must have the following: -+ A Secrets Manager secret that stores your Docker Hub credentials\. The credentials are used to access your private repository\. -+ A private repository or account\. -+ A CodeBuild service role IAM policy that grants access to your Secrets Manager secret\. - - Follow these steps to create these resources and then create a CodeBuild build project using the Docker images stored in your private registry\. - -## Create a CodeBuild project with a private registry - -1. For information about how to create a free private repository, see [Repositories on Docker Hub](https://docs.docker.com/docker-hub/repos/)\. You can also run the following commands in a terminal to pull an image, get its ID, and push it to a new repository\. - - ``` - docker pull amazonlinux - docker images amazonlinux --format {{.ID}} - 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**\. - - 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\. - - 1. For **Secret name**, enter a name, such as **dockerhub**\. You can enter an optional description to help you remember that this is a secret for Docker Hub\. - - 1. Leave **Disable automatic rotation** selected because the keys correspond to your Docker Hub credentials\. - - 1. Choose **Store secret**\. - - 1. When you review your settings, write down the ARN to use later in this sample\. - - 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 *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/) - -1. To use the console to create a project with an environment stored in a private registry, do the following while you create a project\. For information, see [Create a build project \(console\)](create-project-console.md)\. -**Note** - If your private registry is in your VPC, it must have public internet access\. CodeBuild cannot pull an image from a private IP address in a VPC\. - - 1. In **Environment**, choose **Custom image**\. - - 1. For **Environment type**, choose **Linux** or **Windows**\. - - 1. For **Custom image type**, choose **Other location**\. - - 1. In **Other location**, enter the image location and the ARN or name of your Secrets Manager credentials\. -**Note** - If your credentials do not exist in your current Region, then you must use the ARN\. You cannot use the credential name if the credentials exist in a different Region\. \ No newline at end of file diff --git a/doc_source/sample-runtime-versions.md b/doc_source/sample-runtime-versions.md deleted file mode 100644 index 087c35f..0000000 --- a/doc_source/sample-runtime-versions.md +++ /dev/null @@ -1,378 +0,0 @@ -# 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)\. - -**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)\. - -## 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 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: - install: - runtime-versions: - java: corretto8 - ``` -+ A `runtime-versions` section that specifies version 11 of Java: - - ``` - phases: - install: - runtime-versions: - java: corretto11 - ``` - -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: - python: 3.7 - ``` -+ A `runtime-versions` section that specifies Python version 3\.8: - - ``` - phases: - install: - runtime-versions: - python: 3.8 - ``` - -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. 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 - - phases: - install: - runtime-versions: - java: corretto8 - build: - commands: - - java -version - - mvn package - artifacts: - files: - - '**/*' - 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\. - - 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 - ``` - -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`\. - -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 **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:3\.0**\. - -1. 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: - - ``` - [Container] Date Time Phase is DOWNLOAD_SOURCE - [Container] Date Time CODEBUILD_SRC_DIR=/codebuild/output/src460614277/src - [Container] Date Time YAML location is /codebuild/output/src460614277/src/buildspec.yml - [Container] Date Time Processing environment variables - [Container] Date Time Selecting 'java' runtime version 'corretto8' based on manual selections... - [Container] Date Time Running command echo "Installing Java version 8 ..." - Installing Java version 8 ... - - [Container] Date Time Running command export JAVA_HOME="$JAVA_8_HOME" - - [Container] Date Time Running command export JRE_HOME="$JRE_8_HOME" - - [Container] Date Time Running command export JDK_HOME="$JDK_8_HOME" - - [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: - - ``` - install: - runtime-versions: - 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: - - ``` - [Container] Date Time Phase is DOWNLOAD_SOURCE - [Container] Date Time CODEBUILD_SRC_DIR=/codebuild/output/src460614277/src - [Container] Date Time YAML location is /codebuild/output/src460614277/src/buildspec.yml - [Container] Date Time Processing environment variables - [Container] Date Time Selecting 'java' runtime version 'corretto11' based on manual selections... - Installing Java version 11 ... - - [Container] Date Time Running command export JAVA_HOME="$JAVA_11_HOME" - - [Container] Date Time Running command export JRE_HOME="$JRE_11_HOME" - - [Container] Date Time Running command export JDK_HOME="$JDK_11_HOME" - - [Container] Date Time Running command for tool_path in "$JAVA_11_HOME"/bin/* "$JRE_11_HOME"/bin/*; - ``` - -## 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\. - -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 **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 **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. In **Build commands**, replace the placeholder text with the following: - - ``` - version: 0.2 - - phases: - install: - runtime-versions: - android: 29 - java: corretto8 - build: - commands: - - ./gradlew assembleDebug - artifacts: - files: - - app/build/outputs/apk/app-debug.apk - ``` - - The `runtime-versions` section specifies both Android version 29 and Java version 8 runtimes\. - -1. Choose **Create build project**\. - -1. 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: - - ``` - [Container] 2019/05/14 23:21:42 Entering phase DOWNLOAD_SOURCES - [Container] Date Time Running command echo "Installing Android version 29 ..." - Installing Android version 29 ... - - [Container] Date Time Running command echo "Installing Java version 8 ..." - Installing Java version 8 ... - ``` - -## 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\. - -1. Create a directory named `my-source`\. - -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\. - - ``` - package main - import "fmt" - - func main() { - fmt.Println("hello world from golang") - fmt.Println("1+1 =", 1+1) - fmt.Println("7.0/3.0 =", 7.0/3.0) - fmt.Println(true && false) - fmt.Println(true || false) - fmt.Println(!true) - fmt.Println("good bye from golang") - } - ``` - -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\. - - ``` - console.log("hello world from nodejs"); - console.log("1+1 =" + (1+1)); - console.log("7.0/3.0 =" + 7.0/3.0); - console.log(true && false); - console.log(true || false); - console.log(!true); - 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\. - - ``` - { - "name": "mycompany-app", - "version": "1.0.0", - "description": "", - "main": "index.js", - "scripts": { - "test": "echo \"run some tests here\"" - }, - "author": "", - "license": "ISC" - } - ``` - -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 - - phases: - install: - runtime-versions: - golang: 1.13 - nodejs: 12 - build: - commands: - - echo Building the Go code... - - cd $CODEBUILD_SRC_DIR/golang-app - - go build hello.go - - echo Building the Node code... - - cd $CODEBUILD_SRC_DIR/nodejs-app - - npm run test - artifacts: - secondary-artifacts: - golang_artifacts: - base-directory: golang-app - files: - - hello - nodejs_artifacts: - base-directory: nodejs-app - files: - - index.js - - package.json - ``` - -1. Your file structure should now look like this\. - - ``` - 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\. -**Important** - 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 `my-source` to the ZIP file, just the directories and files in `my-source`\. - -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 **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:3\.0**\. - -1. Choose **Create build project**\. - -1. 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\. - - ``` - [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 '12' based on manual selections... - [Container] Date Time Running command echo "Installing Go version 1.13 ..." - Installing Go version 1.13 ... - - [Container] Date Time Running command echo "Installing Node.js version 12 ..." - Installing Node.js version 12 ... - - [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 - [Container] Date Time Phases found in YAML: 2 - [Container] Date Time INSTALL: 0 commands - [Container] Date Time BUILD: 1 commands - [Container] Date Time Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED - [Container] Date Time Phase context status code: Message: - [Container] Date Time Entering phase INSTALL - [Container] Date Time Phase complete: INSTALL State: SUCCEEDED - [Container] Date Time Phase context status code: Message: - [Container] Date Time Entering phase PRE_BUILD - [Container] Date Time Phase complete: PRE_BUILD State: SUCCEEDED - [Container] Date Time Phase context status code: Message: - [Container] Date Time Entering phase BUILD - [Container] Date Time Running command echo Building the Go code... - Building the Go code... - - [Container] Date Time Running command cd $CODEBUILD_SRC_DIR/golang-app - - [Container] Date Time Running command go build hello.go - - [Container] Date Time Running command echo Building the Node code... - Building the Node code... - - [Container] Date Time Running command cd $CODEBUILD_SRC_DIR/nodejs-app - - [Container] Date Time Running command npm run test - - > mycompany-app@1.0.0 test /codebuild/output/src924084119/src/nodejs-app - > echo "run some tests here" - - run some tests here - ``` \ No newline at end of file diff --git a/doc_source/sample-source-version.md b/doc_source/sample-source-version.md deleted file mode 100644 index 4b4f24a..0000000 --- a/doc_source/sample-source-version.md +++ /dev/null @@ -1,98 +0,0 @@ -# Source version sample with AWS CodeBuild - - This sample demonstrates how to specify a version of your source using a format other than a commit ID \(also known as a commit SHA\)\. You can specify the version of your source in the following ways: -+ For an Amazon S3 source provider, use the version ID of the object that represents the build input ZIP file\. -+ For CodeCommit, Bitbucket, GitHub, and GitHub Enterprise Server, use one of the following: - + Pull request as a pull request reference \(for example, `refs/pull/1/head`\)\. - + Branch as a branch name\. - + Commit ID\. - + Tag\. - + Reference and a commit ID\. The reference can be one of the following: - + A tag \(for example, `refs/tags/mytagv1.0^{full-commit-SHA}`\)\. - + A branch \(for example, `refs/heads/mydevbranch^{full-commit-SHA}`\)\. - + A pull request \(for example, `refs/pull/1/head^{full-commit-SHA}`\)\. - -**Note** - You can specify the version of a pull request source only if your repository is GitHub or GitHub Enterprise Server\. - - 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/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\. - -**To specify a GitHub repository version with a commit ID** - -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 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: - + In **Source**: - + For **Source provider**, choose **GitHub**\. If you are not connected to GitHub, follow the instructions to connect\. - + For **Repository**, choose **Public repository**\. - + For **Repository URL**, enter **https://github\.com/aws/aws\-sdk\-ruby\.git**\. - + In **Environment**: - + 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:3\.0**\. - -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: - - ``` - version: 0.2 - - phases: - install: - runtime-versions: - ruby: 2.6 - build: - commands: - - echo $CODEBUILD_RESOLVED_SOURCE_VERSION - ``` - - The `runtime-versions` section is required when you use the Ubuntu standard image 2\.0\. Here, the Ruby version 2\.6 runtime is specified, but you can use any runtime\. The `echo` command displays the version of the source code stored in the `CODEBUILD_RESOLVED_SOURCE_VERSION` environment variable\. - -1. On **Build configuration**, accept the defaults, and then choose **Start build**\. - -1. For **Source version**, enter **046e8b67481d53bdc86c3f6affdd5d1afae6d369**\. This is the SHA of a commit in the `https://github.com/aws/aws-sdk-ruby.git` repository\. - -1. Choose **Start build**\. - -1. When the build is complete, you should see the following: - + On the **Build logs** tab, which version of the project source was used\. Here is an example\. - - ``` - [Container] Date Time Running command echo $CODEBUILD_RESOLVED_SOURCE_VERSION - 046e8b67481d53bdc86c3f6affdd5d1afae6d369 - - [Container] Date Time Phase complete: BUILD State: SUCCEEDED - ``` - + On the **Environment variables** tab, the **Resolved source version** matches the commit ID used to create the build\. - + On the **Phase details** tab, the duration of the `DOWNLOAD_SOURCE` phase\. - - These steps show you how to create a build using the same version of the source\. This time, the version of the source is specified using a reference with the commit ID\. - -**To specify a GitHub repository version with a commit ID and reference** - -1. From the left navigation pane, choose **Build projects**, and then choose the project you created earlier\. - -1. Choose **Start build**\. - -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**\. - -1. When the build is complete, you should see the following: - + On the **Build logs** tab, which version of the project source was used\. Here is an example\. - - ``` - [Container] Date Time Running command echo $CODEBUILD_RESOLVED_SOURCE_VERSION - 046e8b67481d53bdc86c3f6affdd5d1afae6d369 - - [Container] Date Time Phase complete: BUILD State: SUCCEEDED - ``` - + On the **Environment variables** tab, the **Resolved source version** matches the commit ID used to create the build\. - + On the **Phase details** tab, the duration of the `DOWNLOAD_SOURCE` phase should be shorter than the duration when you used only the commit ID to specify the version of your source\. \ No newline at end of file diff --git a/doc_source/sample-test-report-cli.md b/doc_source/sample-test-report-cli.md deleted file mode 100644 index d07f03e..0000000 --- a/doc_source/sample-test-report-cli.md +++ /dev/null @@ -1,258 +0,0 @@ -# Create a test report in CodeBuild using the AWS CLI sample - - Tests that you specify in your buildspec file are run during your build\. This sample shows you how to use the AWS CLI to incorporate tests into builds in CodeBuild\. You can use JUnit to create unit tests, or you can use another tool to create configuration tests\. You can then evaluate the test results to fix issues or optimize your application\. - -You can use the CodeBuild API or the AWS CodeBuild console to access the test results\. This sample shows you how to configure your report so its test results are exported to an S3 bucket\. - -**Topics** -+ [Prerequisites](#sample-test-report-cli-prerequisites) -+ [Create a report group](#sample-test-report-cli-create-report) -+ [Configure a project with a report group](#sample-test-report-cli-create-project-with-report) -+ [Run and view results of a report](#sample-test-report-cli-run-and-view-report-results) - -## Prerequisites -+ 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 \(\.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*\. -+ Create an IAM role and make a note of its ARN\. You need the ARN when you create your build project\. -+ If your role does not have the following permissions, add them\. - - ``` - { - "Effect": "Allow", - "Resource": [ - "*" - ], - "Action": [ - "codebuild:CreateReportGroup", - "codebuild:CreateReport", - "codebuild:UpdateReport", - "codebuild:BatchPutTestCases" - ] - } - ``` - - For more information, see [Permissions for test reporting operations](test-permissions.md#test-permissions-related-to-reporting)\. - -## Create a report group - -1. Create a file named `CreateReportGroupInput.json`\. - -1. Create a folder in your S3 bucket where your test results are exported\. - -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": "", - "type": "TEST", - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "", - "path": "", - "packaging": "NONE" - } - } - } - ``` - -1. Run the following command in the directory that contains `CreateReportGroupInput.json`\. - - ``` - 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\. - - ``` - { - "reportGroup": { - "arn": "arn:aws:codebuild:us-west-2:123456789012:report-group/", - "name": "", - "type": "TEST", - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "", - "path": "", - "packaging": "NONE", - "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3" - } - }, - "created": 1570837165.885, - "lastModified": 1570837165.885 - } - } - ``` - -## 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\. - -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\. - - ``` - version: 0.2 - phases: - install: - runtime-versions: - java: openjdk8 - build: - commands: - - echo Running tests - - - - reports: - : #test file information - files: - - '' - 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)\. - -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\. - - ``` - { - "name": "test-report-project", - "description": "sample-test-report-project", - "source": { - "type": "CODECOMMIT|CODEPIPELINE|GITHUB|S3|BITBUCKET|GITHUB_ENTERPRISE|NO_SOURCE", - "location": "" - }, - "artifacts": { - "type": "NO_ARTIFACTS" - }, - "cache": { - "type": "NO_CACHE" - }, - "environment": { - "type": "LINUX_CONTAINER", - "image": "aws/codebuild/standard:4.0", - "computeType": "small" - }, - "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`\. - - ``` - 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\. - -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-report-project - ``` - -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 - ``` - -1. Run the following command to get details about your report\. For ``, specify your report ARN\. - - ``` - 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\. - - ``` - { - "reports": [ - { - "status": "FAILED", - "reportGroupArn": "", - "name": "", - "created": 1573324770.154, - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "", - "path": "", - "packaging": "NONE", - "encryptionKey": "" - } - }, - "expired": 1575916770.0, - "truncated": false, - "executionId": "arn:aws:codebuild:us-west-2:123456789012:build/:2c254862-ddf6-4831-a53f-6839a73829c1", - "type": "TEST", - "arn": "", - "testSummary": { - "durationInNanoSeconds": 6657770, - "total": 11, - "statusCounts": { - "FAILED": 3, - "SKIPPED": 7, - "ERROR": 0, - "SUCCEEDED": 1, - "UNKNOWN": 0 - } - } - } - ], - "reportsNotFound": [] - } - ``` - -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 \ - --filter status=SUCCEEDED|FAILED|SKIPPED|ERROR|UNKNOWN - ``` - - The output looks like the following\. - - ``` - { - "testCases": [ - { - "status": "FAILED", - "name": "Test case 1", - "expired": 1575916770.0, - "reportArn": "", - "prefix": "Cucumber tests for agent", - "message": "A test message", - "durationInNanoSeconds": 1540540, - "testRawDataPath": "" - }, - { - "status": "SUCCEEDED", - "name": "Test case 2", - "expired": 1575916770.0, - "reportArn": "", - "prefix": "Cucumber tests for agent", - "message": "A test message", - "durationInNanoSeconds": 1540540, - "testRawDataPath": "" - } - ] - } - ``` \ No newline at end of file diff --git a/doc_source/sample-windows.md b/doc_source/sample-windows.md deleted file mode 100644 index 355e436..0000000 --- a/doc_source/sample-windows.md +++ /dev/null @@ -1,831 +0,0 @@ -# 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 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)\. - -## Running the samples - -**To run these samples** - -1. Create the files as described in the "Directory structure" and "Files" sections of this topic, and then upload them to an S3 input bucket or a CodeCommit or GitHub repository\. -**Important** -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\. 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\.\) - - ``` - { - "name": "sample-windows-build-project", - "source": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-input-bucket/windows-build-input-artifact.zip" - }, - "artifacts": { - "type": "S3", - "location": "codebuild-region-ID-account-ID-output-bucket", - "packaging": "ZIP", - "name": "windows-build-output-artifact.zip" - }, - "environment": { - "type": "WINDOWS_SERVER_2019_CONTAINER", - "image": "mcr.microsoft.com/dotnet/framework/sdk:4.8", - "computeType": "BUILD_GENERAL1_MEDIUM" - }, - "serviceRole": "arn:aws:iam::account-ID:role/role-name", - "encryptionKey": "arn:aws:kms:region-ID:account-ID:key/key-ID" - } - ``` - -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\. - -### F\# and the \.NET Framework - -``` -(root directory name) -├── 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 -``` - -## Files - -These samples use the following files\. - -### F\# and the \.NET Framework - -`buildspec.yml` \(in `(root directory name)`\): - -``` -version: 0.2 - -env: - variables: - SOLUTION: .\FSharpHelloWorld.sln - PACKAGE_DIRECTORY: .\packages - DOTNET_FRAMEWORK: 4.8 - -phases: - build: - commands: - - '& 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\* -``` - -`FSharpHelloWorld.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("{F2A71F9B-5D33-465A-A702-920D77279786}") = "FSharpHelloWorld", "FSharpHelloWorld\FSharpHelloWorld.fsproj", "{D60939B6-526D-43F4-9A89-577B2980DF62}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Release|Any CPU = Release|Any CPU - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {D60939B6-526D-43F4-9A89-577B2980DF62}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {D60939B6-526D-43F4-9A89-577B2980DF62}.Debug|Any CPU.Build.0 = Debug|Any CPU - {D60939B6-526D-43F4-9A89-577B2980DF62}.Release|Any CPU.ActiveCfg = Release|Any CPU - {D60939B6-526D-43F4-9A89-577B2980DF62}.Release|Any CPU.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection -EndGlobal -``` - -`App.config` \(in `(root directory name)\FSharpHelloWorld`\): - -``` - - - - - - -``` - -`AssemblyInfo.fs` \(in `(root directory name)\FSharpHelloWorld`\): - -``` -namespace FSharpHelloWorld.AssemblyInfo - -open System.Reflection -open System.Runtime.CompilerServices -open 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. -[] -[] -[] -[] -[] -[] -[] -[] - -// 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. -[] - -// The following GUID is for the ID of the typelib if this project is exposed to COM -[] - -// 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: -// [] -[] -[] - -do - () -``` - -`FSharpHelloWorld.fsproj` \(in `(root directory name)\FSharpHelloWorld`\): - -``` - - - - - Debug - AnyCPU - 2.0 - d60939b6-526d-43f4-9a89-577b2980df62 - Exe - FSharpHelloWorld - FSharpHelloWorld - v4.8 - true - 4.4.0.0 - FSharpHelloWorld - - - true - full - false - false - bin\Debug\ - DEBUG;TRACE - 3 - AnyCPU - bin\Debug\FSharpHelloWorld.XML - true - - - pdbonly - true - true - bin\Release\ - TRACE - 3 - AnyCPU - bin\Release\FSharpHelloWorld.XML - true - - - - - True - - - - - - - - - - - - 11 - - - - - $(MSBuildExtensionsPath32)\..\Microsoft SDKs\F#\3.0\Framework\v4.0\Microsoft.FSharp.Targets - - - - - $(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\FSharp\Microsoft.FSharp.Targets - - - - - - -``` - -`Program.fs` \(in `(root directory name)\FSharpHelloWorld`\): - -``` -// Learn more about F# at http://fsharp.org -// See the 'F# Tutorial' project for more help. - -[] -let main argv = - printfn "Hello World" - 0 // return an integer exit code -``` - -### Visual Basic and the \.NET Framework - -`buildspec.yml` \(in `(root directory name)`\): - -``` -version: 0.2 - -env: - variables: - SOLUTION: .\VBHelloWorld.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: - - .\VBHelloWorld\bin\Debug\* -``` - -`VBHelloWorld.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("{F184B08F-C81C-45F6-A57F-5ABD9991F28F}") = "VBHelloWorld", "VBHelloWorld\VBHelloWorld.vbproj", "{4DCEC446-7156-4FE6-8CCC-219E34DD409D}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Release|Any CPU = Release|Any CPU - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {4DCEC446-7156-4FE6-8CCC-219E34DD409D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {4DCEC446-7156-4FE6-8CCC-219E34DD409D}.Debug|Any CPU.Build.0 = Debug|Any CPU - {4DCEC446-7156-4FE6-8CCC-219E34DD409D}.Release|Any CPU.ActiveCfg = Release|Any CPU - {4DCEC446-7156-4FE6-8CCC-219E34DD409D}.Release|Any CPU.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection -EndGlobal -``` - -`App.config` \(in `(root directory name)\VBHelloWorld`\): - -``` - - - - - - -``` - -`HelloWorld.vb` \(in `(root directory name)\VBHelloWorld`\): - -``` -Module HelloWorld - - Sub Main() - MsgBox("Hello World") - End Sub - -End Module -``` - -`VBHelloWorld.vbproj` \(in `(root directory name)\VBHelloWorld`\): - -``` - - - - - Debug - AnyCPU - {4DCEC446-7156-4FE6-8CCC-219E34DD409D} - Exe - VBHelloWorld.HelloWorld - VBHelloWorld - VBHelloWorld - 512 - Console - v4.8 - true - - - AnyCPU - true - full - true - true - bin\Debug\ - VBHelloWorld.xml - 42016,41999,42017,42018,42019,42032,42036,42020,42021,42022 - - - AnyCPU - pdbonly - false - true - true - bin\Release\ - VBHelloWorld.xml - 42016,41999,42017,42018,42019,42032,42036,42020,42021,42022 - - - On - - - Binary - - - Off - - - On - - - - - - - - - - - - - - - - - - - - - - - - - - - True - Application.myapp - - - True - True - Resources.resx - - - True - Settings.settings - True - - - - - VbMyResourcesResXFileCodeGenerator - Resources.Designer.vb - My.Resources - Designer - - - - - MyApplicationCodeGenerator - Application.Designer.vb - - - SettingsSingleFileGenerator - My - Settings.Designer.vb - - - - - - -``` - -`Application.Designer.vb` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` -'------------------------------------------------------------------------------ -' -' This code was generated by a tool. -' Runtime Version:4.0.30319.42000 -' -' Changes to this file may cause incorrect behavior and will be lost if -' the code is regenerated. -' -'------------------------------------------------------------------------------ - -Option Strict On -Option Explicit On -``` - -`Application.myapp` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` - - - false - false - 0 - true - 0 - 2 - true - -``` - -`AssemblyInfo.vb` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` -Imports System -Imports System.Reflection -Imports 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. - -' Review the values of the assembly attributes - - - - - - - - - - -'The following GUID is for the ID of the typelib if this project is exposed to COM - - -' 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: -' - - - -``` - -`Resources.Designer.vb` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` -'------------------------------------------------------------------------------ -' -' This code was generated by a tool. -' Runtime Version:4.0.30319.42000 -' -' Changes to this file may cause incorrect behavior and will be lost if -' the code is regenerated. -' -'------------------------------------------------------------------------------ - -Option Strict On -Option Explicit On - -Namespace My.Resources - - 'This class was auto-generated by the StronglyTypedResourceBuilder - 'class via a tool like ResGen or Visual Studio. - 'To add or remove a member, edit your .ResX file then rerun ResGen - 'with the /str option, or rebuild your VS project. - ''' - ''' A strongly-typed resource class, for looking up localized strings, etc. - ''' - _ - Friend Module Resources - - Private resourceMan As Global.System.Resources.ResourceManager - - Private resourceCulture As Global.System.Globalization.CultureInfo - - ''' - ''' Returns the cached ResourceManager instance used by this class. - ''' - _ - Friend ReadOnly Property ResourceManager() As Global.System.Resources.ResourceManager - Get - If Object.ReferenceEquals(resourceMan, Nothing) Then - Dim temp As Global.System.Resources.ResourceManager = New Global.System.Resources.ResourceManager("VBHelloWorld.Resources", GetType(Resources).Assembly) - resourceMan = temp - End If - Return resourceMan - End Get - End Property - - ''' - ''' Overrides the current thread's CurrentUICulture property for all - ''' resource lookups using this strongly typed resource class. - ''' - _ - Friend Property Culture() As Global.System.Globalization.CultureInfo - Get - Return resourceCulture - End Get - Set(ByVal value As Global.System.Globalization.CultureInfo) - resourceCulture = value - End Set - End Property - End Module -End Namespace -``` - -`Resources.resx` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - text/microsoft-resx - - - 2.0 - - - System.Resources.ResXResourceReader, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 - - - System.Resources.ResXResourceWriter, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 - - -``` - -`Settings.Designer.vb` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` -'------------------------------------------------------------------------------ -' -' This code was generated by a tool. -' Runtime Version:4.0.30319.42000 -' -' Changes to this file may cause incorrect behavior and will be lost if -' the code is regenerated. -' -'------------------------------------------------------------------------------ - -Option Strict On -Option Explicit On - -Namespace My - - _ - Partial Friend NotInheritable Class MySettings - Inherits Global.System.Configuration.ApplicationSettingsBase - - Private Shared defaultInstance As MySettings = CType(Global.System.Configuration.ApplicationSettingsBase.Synchronized(New MySettings), MySettings) - - #Region "My.Settings Auto-Save Functionality" - #If _MyType = "WindowsForms" Then - Private Shared addedHandler As Boolean - - Private Shared addedHandlerLockObject As New Object - - _ - Private Shared Sub AutoSaveSettings(ByVal sender As Global.System.Object, ByVal e As Global.System.EventArgs) - If My.Application.SaveMySettingsOnExit Then - My.Settings.Save() - End If - End Sub - #End If - #End Region - - Public Shared ReadOnly Property [Default]() As MySettings - Get - - #If _MyType = "WindowsForms" Then - If Not addedHandler Then - SyncLock addedHandlerLockObject - If Not addedHandler Then - AddHandler My.Application.Shutdown, AddressOf AutoSaveSettings - addedHandler = True - End If - End SyncLock - End If - #End If - Return defaultInstance - End Get - End Property - End Class -End Namespace - -Namespace My - - _ - Friend Module MySettingsProperty - - _ - Friend ReadOnly Property Settings() As Global.VBHelloWorld.My.MySettings - Get - Return Global.VBHelloWorld.My.MySettings.Default - End Get - End Property - End Module -End Namespace -``` - -`Settings.settings` \(in `(root directory name)\VBHelloWorld\My Project`\): - -``` - - - - - - - -``` \ No newline at end of file diff --git a/doc_source/samples.md b/doc_source/samples.md deleted file mode 100644 index d7dd5ec..0000000 --- a/doc_source/samples.md +++ /dev/null @@ -1,7 +0,0 @@ -# CodeBuild samples - -These groups of samples can be used to experiment with AWS CodeBuild: - -**Topics** -+ [Microsoft Windows samples for CodeBuild](sample-windows.md) -+ [CodeBuild use case\-based samples](use-case-based-samples.md) \ No newline at end of file diff --git a/doc_source/sdk-ref.md b/doc_source/sdk-ref.md deleted file mode 100644 index 17ffaa0..0000000 --- a/doc_source/sdk-ref.md +++ /dev/null @@ -1,18 +0,0 @@ -# AWS SDKs and tools reference for AWS CodeBuild - -To use one the AWS SDKs or tools to automate AWS CodeBuild, see the following resources\. - -If you want to use the AWS CLI to run CodeBuild, see the [Command line reference](cmd-ref.md)\. - -## Supported AWS SDKs and tools for AWS CodeBuild - -The following AWS SDKs and tools support CodeBuild: -+ The [AWS SDK for C\+\+](https://aws.amazon.com/sdk-for-cpp)\. For more information, see the [Aws::CodeBuild](http://sdk.amazonaws.com/cpp/api/LATEST/namespace_aws_1_1_code_build.html) namespace section of the *AWS SDK for C\+\+ API Reference*\. -+ The [AWS SDK for Go](https://aws.amazon.com/sdk-for-go/)\. For more information, see the [codebuild](http://docs.aws.amazon.com/sdk-for-go/api/service/codebuild/) section of the *AWS SDK for Go API Reference*\. -+ The [AWS SDK for Java](https://aws.amazon.com/sdk-for-java/)\. For more information, see the `com.amazonaws.services.codebuild` and `com.amazonaws.services.codebuild.model` sections of the [AWS SDK for Java API reference](http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/index.html)\. -+ The [AWS SDK for JavaScript in the browser](https://aws.amazon.com/sdk-for-browser/) and the [AWS SDK for JavaScript in Node\.js](https://aws.amazon.com/sdk-for-node-js/)\. For more information, see the [Class: AWS\.CodeBuild](http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CodeBuild.html) section of the *AWS SDK for JavaScript API Reference*\. -+ The [AWS SDK for \.NET](https://aws.amazon.com/sdk-for-net/)\. For more information, see the [Amazon\.CodeBuild](http://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CodeBuild/NCodeBuild.html) and [Amazon\.CodeBuild\.Model](http://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/CodeBuild/NCodeBuildModel.html) namespace sections of the *AWS SDK for \.NET API Reference*\. -+ The [AWS SDK for PHP](https://aws.amazon.com/sdk-for-php/)\. For more information, see the [Namespace Aws\\CodeBuild](http://docs.aws.amazon.com/aws-sdk-php/v3/api/namespace-Aws.CodeBuild.html) section of the *AWS SDK for PHP API Reference*\. -+ The [AWS SDK for Python \(Boto3\)](https://aws.amazon.com/sdk-for-python/)\. For more information, see the [CodeBuild](https://boto3.readthedocs.io/en/latest/reference/services/codebuild.html) section of the *Boto 3 Documentation*\. -+ The [AWS SDK for Ruby](https://aws.amazon.com/sdk-for-ruby/)\. For more information, see the [Module: Aws::CodeBuild](http://docs.aws.amazon.com/sdkforruby/api/Aws/CodeBuild.html) section of the *AWS SDK for Ruby API Reference*\. -+ The [AWS Tools for PowerShell](https://aws.amazon.com/powershell/)\. For more information, see the [AWS CodeBuild](http://docs.aws.amazon.com/powershell/latest/reference/items/AWS_CodeBuild_cmdlets.html) section of the *AWS Tools for PowerShell Cmdlet Reference*\. \ No newline at end of file diff --git a/doc_source/security-encryption.md b/doc_source/security-encryption.md deleted file mode 100644 index e260b00..0000000 --- a/doc_source/security-encryption.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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 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 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 deleted file mode 100644 index 5e57830..0000000 --- a/doc_source/security-key-management.md +++ /dev/null @@ -1,7 +0,0 @@ -# Key management - -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_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 diff --git a/doc_source/security-traffic-privacy.md b/doc_source/security-traffic-privacy.md deleted file mode 100644 index 691f960..0000000 --- a/doc_source/security-traffic-privacy.md +++ /dev/null @@ -1,3 +0,0 @@ -# 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 diff --git a/doc_source/security.md b/doc_source/security.md deleted file mode 100644 index 611c3d2..0000000 --- a/doc_source/security.md +++ /dev/null @@ -1,15 +0,0 @@ -# Security in AWS CodeBuild - -Cloud security at AWS is the highest priority\. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security\-sensitive organizations\. - -Security and compliance is a shared responsibility between AWS and you\. This shared model can help relieve your operational burden: AWS operates, manages, and controls the components from the host operating system and virtualization layer down to the physical security of the service facilities\. You assume responsibility and management of the guest operating system \(including updates and security patches\) and other associated application software\. You're also responsible for the configuration of the AWS provided security group firewall\. Your responsibilities vary with the services you use, the integration of those services into your IT environment, and applicable laws and regulations\. Therefore, you should carefully consider the services that your organization uses\. For more information, see [Shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/)\. - -To learn how to secure your CodeBuild resources, see the following topics\. - -**Topics** -+ [Data protection in AWS CodeBuild](data-protection.md) -+ [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) -+ [Access your source provider in CodeBuild](access-tokens.md) \ No newline at end of file diff --git a/doc_source/serverless-applications.md b/doc_source/serverless-applications.md deleted file mode 100644 index 0de8156..0000000 --- a/doc_source/serverless-applications.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 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)\. -+ For information about troubleshooting issues in CodeBuild, see [Troubleshooting AWS CodeBuild](troubleshooting.md)\. -+ For information about quotas in CodeBuild, see [Quotas for AWS CodeBuild](limits.md)\. \ No newline at end of file diff --git a/doc_source/session-manager.md b/doc_source/session-manager.md deleted file mode 100644 index 2c74fa1..0000000 --- a/doc_source/session-manager.md +++ /dev/null @@ -1,156 +0,0 @@ -# View a running build in Session Manager - -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) -+ [Start the build](#ssm-start-build) -+ [Connect to the build container](#ssm-connect) -+ [Resume the build](#ssm-resume-build) - -## Prerequisites - -To allow Session Manager to be used with the build session, you must enable session connection for the build\. There are two prerequisites: -+ CodeBuild Linux standard curated images already have the SSM agent installed and the SSM agent ContainerMode enabled\. - - 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\. 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: - - ``` - { - "Effect": "Allow", - "Action": [ - "ssmmessages:CreateControlChannel", - "ssmmessages:CreateDataChannel", - "ssmmessages:OpenControlChannel", - "ssmmessages:OpenDataChannel" - ], - "Resource": "*" - } - ``` - - 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 - -To pause the build, insert the codebuild\-breakpoint command in any of the build phases in your buildspec file\. The build will be paused at this point, which allows you to connect to the build container and view the container in its current state\. - -For example, add the following to the build phases in your buildspec file\. - -``` -phases: - pre_build: - commands: - - echo Entered the pre_build phase... - - echo "Hello World" > /tmp/hello-world - - codebuild-breakpoint -``` - -This code creates the `/tmp/hello-world` file and then pauses the build at this point\. - -## Start the build - -To allow Session Manager to be used with the build session, you must enable session connections for the build\. To do this, when starting the build, follow these steps: - -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**\. Choose the build project, and then choose **Start build**\. - -1. Choose **Advanced build overrides**\. - -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\. - -## Connect to the build container - -You can connect to the build container in one of two ways: - -CodeBuild console -In a web browser, open the **AWS Session Manager** link to connect to the build container\. A terminal session opens that allows you to browse and control the build container\. - -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, 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 --output json - ``` - -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\. - - ``` - aws ssm start-session --target --region - ``` - -For this example, verify that the `/tmp/hello-world` file exists and contains the text `Hello World`\. - -## Resume the build - -After you finish examining the build container, issue the codebuild\-resume command from the container shell\. - -``` -$ codebuild-resume -``` \ No newline at end of file diff --git a/doc_source/setting-up.md b/doc_source/setting-up.md deleted file mode 100644 index 7987a75..0000000 --- a/doc_source/setting-up.md +++ /dev/null @@ -1,558 +0,0 @@ -# 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 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 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 - -To access AWS CodeBuild with an IAM group or IAM user, you must add access permissions\. This section describes how to do this with the IAM console or the AWS CLI\. - -If you will access CodeBuild with your AWS root account \(not recommended\) or an administrator IAM user in your AWS account, then you do not need to follow these instructions\. - -For information about AWS root accounts and administrator IAM users, see [The Account Root User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) and [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*\. - -**To add CodeBuild access permissions to an IAM group or IAM user \(console\)** - -1. Open the IAM console at [https://console\.aws\.amazon\.com/iam/](https://console.aws.amazon.com/iam/)\. - - You should have already signed 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 perform the following minimum set of actions: - - ``` - iam:AttachGroupPolicy - iam:AttachUserPolicy - iam:CreatePolicy - iam:ListAttachedGroupPolicies - iam:ListAttachedUserPolicies - iam:ListGroups - iam:ListPolicies - iam:ListUsers - ``` - - For more information, see [Overview of IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*\. - -1. In the navigation pane, choose **Policies**\. - -1. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip ahead to step 4 in this procedure\. - - To add a default set of CodeBuild access permissions to an IAM group or IAM user, choose **Policy Type**, **AWS Managed**, and then do the following: - + To add full access permissions to CodeBuild, select the box named **AWSCodeBuildAdminAccess**, choose **Policy Actions**, and then choose **Attach**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policies named **AmazonS3ReadOnlyAccess** and **IAMFullAccess**\. - + To add access permissions to CodeBuild for everything except build project administration, select the box named **AWSCodeBuildDeveloperAccess**, choose **Policy Actions**, and then choose **Attach**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policy named **AmazonS3ReadOnlyAccess**\. - + To add read\-only access permissions to CodeBuild, select the boxes named **AWSCodeBuildReadOnlyAccess**\. Select the box next to the target IAM group or IAM user, and then choose **Attach Policy**\. Repeat this for the policy named **AmazonS3ReadOnlyAccess**\. - - You have now added a default set of CodeBuild access permissions to an IAM group or IAM user\. Skip the rest of the steps in this procedure\. - -1. Choose **Create Policy**\. - -1. On the **Create Policy** page, next to **Create Your Own Policy**, choose **Select**\. - -1. On the **Review Policy** page, for **Policy Name**, enter a name for the policy \(for example, **CodeBuildAccessPolicy**\)\. If you use a different name, be sure to use it throughout this procedure\. - -1. For **Policy Document**, enter the following, and then choose **Create Policy**\. - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "CodeBuildAccessPolicy", - "Effect": "Allow", - "Action": [ - "codebuild:*" - ], - "Resource": "*" - }, - { - "Sid": "CodeBuildRolePolicy", - "Effect": "Allow", - "Action": [ - "iam:PassRole" - ], - "Resource": "arn:aws:iam::account-ID:role/role-name" - }, - { - "Sid": "CloudWatchLogsAccessPolicy", - "Effect": "Allow", - "Action": [ - "logs:FilterLogEvents", - "logs:GetLogEvents" - ], - "Resource": "*" - }, - { - "Sid": "S3AccessPolicy", - "Effect": "Allow", - "Action": [ - "s3:CreateBucket", - "s3:GetObject", - "s3:List*", - "s3:PutObject" - ], - "Resource": "*" - }, - { - "Sid": "S3BucketIdentity", - "Effect": "Allow", - "Action": [ - "s3:GetBucketAcl", - "s3:GetBucketLocation" - ], - "Resource": "*" - } - ] - } - ``` -**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)\. -The `CodeBuildRolePolicy` statement is required to allow a build project to be created or modified\. - -1. In the navigation pane, choose **Groups** or **Users**\. - -1. In the list of groups or users, choose the name of the IAM group or IAM user to which you want to add CodeBuild access permissions\. - -1. For a group, on the group settings page, on the **Permissions** tab, expand **Managed Policies**, and then choose **Attach Policy**\. - - For a user, on the user settings page, on the **Permissions** tab, choose **Add permissions**\. - -1. For a group, on the **Attach Policy** page, select **CodeBuildAccessPolicy**, and then choose **Attach Policy**\. - - 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\)** - -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, as described in the previous procedure\. 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. To add a custom set of AWS CodeBuild access permissions to an IAM group or IAM user, skip to step 3 in this procedure\. - - To add a default set of CodeBuild access permissions to an IAM group or IAM user, do the following: - - Run one of the following commands, depending on whether you want to add permissions to an IAM group or IAM user: - - ``` - aws iam attach-group-policy --group-name group-name --policy-arn policy-arn - - aws iam attach-user-policy --user-name user-name --policy-arn policy-arn - ``` - - You must run the command three times, replacing *group\-name* or *user\-name* with the IAM group name or IAM user name, and replacing *policy\-arn* once for each of the following policy Amazon Resource Names \(ARNs\): - + To add full access permissions to CodeBuild, use the following policy ARNs: - + `arn:aws:iam::aws:policy/AWSCodeBuildAdminAccess` - + `arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess` - + `arn:aws:iam::aws:policy/IAMFullAccess` - + To add access permissions to CodeBuild for everything except build project administration, use the following policy ARNs: - + `arn:aws:iam::aws:policy/AWSCodeBuildDeveloperAccess` - + `arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess` - + To add read\-only access permissions to CodeBuild, use the following policy ARNs: - + `arn:aws:iam::aws:policy/AWSCodeBuildReadOnlyAccess` - + `arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess` - - You have now added a default set of CodeBuild access permissions to an IAM group or IAM user\. Skip the rest of the steps in this procedure\. - -1. In an empty directory on the local workstation or instance where the AWS CLI is installed, create a file named `put-group-policy.json` or `put-user-policy.json`\. If you use a different file name, be sure to use it throughout this procedure\. - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "CodeBuildAccessPolicy", - "Effect": "Allow", - "Action": [ - "codebuild:*" - ], - "Resource": "*" - }, - { - "Sid": "CodeBuildRolePolicy", - "Effect": "Allow", - "Action": [ - "iam:PassRole" - ], - "Resource": "arn:aws:iam::account-ID:role/role-name" - }, - { - "Sid": "CloudWatchLogsAccessPolicy", - "Effect": "Allow", - "Action": [ - "logs:FilterLogEvents", - "logs:GetLogEvents" - ], - "Resource": "*" - }, - { - "Sid": "S3AccessPolicy", - "Effect": "Allow", - "Action": [ - "s3:CreateBucket", - "s3:GetObject", - "s3:List*", - "s3:PutObject" - ], - "Resource": "*" - }, - { - "Sid": "S3BucketIdentity", - "Effect": "Allow", - "Action": [ - "s3:GetBucketAcl", - "s3:GetBucketLocation" - ], - "Resource": "*" - } - ] - } - ``` -**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\. -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\. - - For an IAM group: - - ``` - aws iam put-group-policy --group-name group-name --policy-name CodeBuildGroupAccessPolicy --policy-document file://put-group-policy.json - ``` - - For an IAM user: - - ``` - aws iam put-user-policy --user-name user-name --policy-name CodeBuildUserAccessPolicy --policy-document file://put-user-policy.json - ``` - - In the preceding commands, replace *group\-name* or *user\-name* with the name of the target IAM group or IAM user\. - -## Create a CodeBuild service role - -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-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\. - -**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\)** - -1. Open the IAM console at [https://console\.aws\.amazon\.com/iam/](https://console.aws.amazon.com/iam/)\. - - You should have already signed in to the 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 perform the following minimum set of actions: - - ``` - iam:AddRoleToInstanceProfile - iam:AttachRolePolicy - iam:CreateInstanceProfile - iam:CreatePolicy - iam:CreateRole - iam:GetRole - iam:ListAttachedRolePolicies - iam:ListPolicies - iam:ListRoles - iam:PassRole - iam:PutRolePolicy - iam:UpdateAssumeRolePolicy - ``` - - For more information, see [Overview of IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*\. - -1. In the navigation pane, choose **Policies**\. - -1. Choose **Create Policy**\. - -1. On the **Create Policy** page, choose **JSON**\. - -1. For the JSON policy, enter the following, and then choose **Review Policy**: - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "CloudWatchLogsPolicy", - "Effect": "Allow", - "Action": [ - "logs:CreateLogGroup", - "logs:CreateLogStream", - "logs:PutLogEvents" - ], - "Resource": "*" - }, - { - "Sid": "CodeCommitPolicy", - "Effect": "Allow", - "Action": [ - "codecommit:GitPull" - ], - "Resource": "*" - }, - { - "Sid": "S3GetObjectPolicy", - "Effect": "Allow", - "Action": [ - "s3:GetObject", - "s3:GetObjectVersion" - ], - "Resource": "*" - }, - { - "Sid": "S3PutObjectPolicy", - "Effect": "Allow", - "Action": [ - "s3:PutObject" - ], - "Resource": "*" - }, - { - "Sid": "ECRPullPolicy", - "Effect": "Allow", - "Action": [ - "ecr:BatchCheckLayerAvailability", - "ecr:GetDownloadUrlForLayer", - "ecr:BatchGetImage" - ], - "Resource": "*" - }, - { - "Sid": "ECRAuthPolicy", - "Effect": "Allow", - "Action": [ - "ecr:GetAuthorizationToken" - ], - "Resource": "*" - }, - { - "Sid": "S3BucketIdentity", - "Effect": "Allow", - "Action": [ - "s3:GetBucketAcl", - "s3:GetBucketLocation" - ], - "Resource": "*" - } - ] - } - ``` -**Note** -This policy contains statements that allow access to a potentially large number of AWS resources\. To restrict AWS CodeBuild to access specific AWS resources, change the value of the `Resource` array\. For more information, see the security documentation for the AWS service\. - -1. On the **Review Policy** page, for **Policy Name**, enter a name for the policy \(for example, **CodeBuildServiceRolePolicy**\), and then choose **Create policy**\. -**Note** -If you use a different name, be sure to use it throughout this procedure\. - -1. In the navigation pane, choose **Roles**\. - -1. Choose **Create role**\. - -1. On the **Create role** page, with **AWS Service** already selected, choose **CodeBuild**, and then choose **Next:Permissions**\. - -1. On the **Attach permissions policies** page, select **CodeBuildServiceRolePolicy**, and then choose **Next: Review**\. - -1. On the **Create role and review** page, for **Role name**, enter a name for the role \(for example, **CodeBuildServiceRole**\), and then choose **Create role**\. - -**To create a CodeBuild service role \(AWS CLI\)** - -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, as described in the previous procedure\. 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. In an empty directory on the local workstation or instance where the AWS CLI is installed, create two files named `create-role.json` and `put-role-policy.json`\. If you choose different file names, be sure to use them throughout this procedure\. - - `create-role.json`: - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Service": "codebuild.amazonaws.com" - }, - "Action": "sts:AssumeRole" - } - ] - } - ``` - - `put-role-policy.json`: - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Sid": "CloudWatchLogsPolicy", - "Effect": "Allow", - "Action": [ - "logs:CreateLogGroup", - "logs:CreateLogStream", - "logs:PutLogEvents" - ], - "Resource": "*" - }, - { - "Sid": "CodeCommitPolicy", - "Effect": "Allow", - "Action": [ - "codecommit:GitPull" - ], - "Resource": "*" - }, - { - "Sid": "S3GetObjectPolicy", - "Effect": "Allow", - "Action": [ - "s3:GetObject", - "s3:GetObjectVersion" - ], - "Resource": "*" - }, - { - "Sid": "S3PutObjectPolicy", - "Effect": "Allow", - "Action": [ - "s3:PutObject" - ], - "Resource": "*" - }, - { - "Sid": "S3BucketIdentity", - "Effect": "Allow", - "Action": [ - "s3:GetBucketAcl", - "s3:GetBucketLocation" - ], - "Resource": "*" - } - ] - } - ``` -**Note** -This policy contains statements that allow access to a potentially large number of AWS resources\. To restrict AWS CodeBuild to access specific AWS resources, change the value of the `Resource` array\. For more information, see the security documentation for the AWS service\. - -1. Switch to the directory where you saved the preceding files, and then run the following two commands, one at a time, in this order\. You can use different values for `CodeBuildServiceRole` and `CodeBuildServiceRolePolicy`, but be sure to use them here\. - - ``` - aws iam create-role --role-name CodeBuildServiceRole --assume-role-policy-document file://create-role.json - ``` - - ``` - aws iam put-role-policy --role-name CodeBuildServiceRole --policy-name CodeBuildServiceRolePolicy --policy-document file://put-role-policy.json - ``` - -## Create and configure a customer managed key for CodeBuild - -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 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 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 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\. - -``` -{ - "Version": "2012-10-17", - "Id": "...", - "Statement": [ - ### BEGIN ADDING STATEMENTS HERE ### - { - "Sid": "Allow access through Amazon S3 for all principals in the account that are authorized to use Amazon S3", - "Effect": "Allow", - "Principal": { - "AWS": "*" - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:GenerateDataKey*", - "kms:DescribeKey" - ], - "Resource": "*", - "Condition": { - "StringEquals": { - "kms:ViaService": "s3.region-ID.amazonaws.com", - "kms:CallerAccount": "account-ID" - } - } - }, - { - "Effect": "Allow", - "Principal": { - "AWS": "arn:aws:iam::account-ID:role/CodeBuild-service-role" - }, - "Action": [ - "kms:Encrypt", - "kms:Decrypt", - "kms:ReEncrypt*", - "kms:GenerateDataKey*", - "kms:DescribeKey" - ], - "Resource": "*" - }, - ### END ADDING STATEMENTS HERE ### - { - "Sid": "Enable IAM User Permissions", - ... - }, - { - "Sid": "Allow access for Key Administrators", - ... - }, - { - "Sid": "Allow use of the key", - ... - }, - { - "Sid": "Allow attachment of persistent resources", - ... - } - ] -} -``` -+ *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 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 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 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 - -To access AWS CodeBuild, you can use the AWS CLI with—or instead of—the CodeBuild console, the CodePipeline console, or the AWS SDKs\. To install and configure the AWS CLI, 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. Run the following command to confirm whether your installation of the AWS CLI supports CodeBuild: - - ``` - aws codebuild list-builds - ``` - - If successful, information similar to the following will appear in the output: - - ``` - { - "ids": [] - } - ``` - - The empty square brackets indicate that you have not yet run any builds\. - -1. If an error is output, you must uninstall your current version of the AWS CLI and then install the latest version\. For more information, see [Uninstalling the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-uninstall.html) and [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) in the *AWS Command Line Interface User Guide*\. \ No newline at end of file diff --git a/doc_source/stop-batch-build.md b/doc_source/stop-batch-build.md deleted file mode 100644 index 70b8ccc..0000000 --- a/doc_source/stop-batch-build.md +++ /dev/null @@ -1,41 +0,0 @@ -# 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/stop-build.md b/doc_source/stop-build.md deleted file mode 100644 index 7af0f19..0000000 --- a/doc_source/stop-build.md +++ /dev/null @@ -1,41 +0,0 @@ -# Stop a build in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI,or AWS SDKs to stop a build in AWS CodeBuild\. - -**Topics** -+ [Stop a build \(console\)](#stop-build-console) -+ [Stop a build \(AWS CLI\)](#stop-build-cli) -+ [Stop a build \(AWS SDKs\)](#stop-build-sdks) - -## Stop 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 **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 build \(for example, if the build process is already complete\), the **Stop** button is disabled or might not appear\. - -## Stop a build \(AWS CLI\) -+ Run the stop\-build command: - - ``` - aws codebuild stop-build --id id - ``` - - In the preceding command, replace the following placeholder: - + *id*: Required string\. The ID of the build to stop\. 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 build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) - - If AWS CodeBuild successfully stops the build, the `buildStatus` value in the `build` object in the output is `STOPPED`\. - - If CodeBuild cannot successfully stop the build \(for example, if the build is already complete\), the `buildStatus` value in the `build` object in the output is the final build status \(for example, `SUCCEEDED`\)\. - -## Stop 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/test-framework-reporting.md b/doc_source/test-framework-reporting.md deleted file mode 100644 index c674de3..0000000 --- a/doc_source/test-framework-reporting.md +++ /dev/null @@ -1,9 +0,0 @@ -# Test reporting with test frameworks - -The topics in this section demonstrate how to set up test reporting in AWS CodeBuild for various test frameworks\. - -**Topics** -+ [Set up test reporting with Jasmine](test-report-jasmine.md) -+ [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) \ No newline at end of file diff --git a/doc_source/test-permissions.md b/doc_source/test-permissions.md deleted file mode 100644 index a705ce6..0000000 --- a/doc_source/test-permissions.md +++ /dev/null @@ -1,109 +0,0 @@ -# Working with test report permissions - - This topic describes important information about permissions related to test reporting\. - -**Topics** -+ [Create a role for test reports](#test-permissions-required) -+ [Permissions for test reporting operations](#test-permissions-related-to-reporting) -+ [Test reporting permissions examples](#test-permissions-examples) - -## 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 code coverage report, your IAM role must also include the `BatchPutCodeCoverages` permission\. - -**Note** -`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: - -``` -{ - "Effect": "Allow", - "Resource": [ - "*" - ], - "Action": [ - "codebuild:CreateReportGroup", - "codebuild:CreateReport", - "codebuild:UpdateReport", - "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: - -``` -{ - "Effect": "Allow", - "Resource": [ - "arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1", - "arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-2" - ], - "Action": [ - "codebuild:CreateReportGroup", - "codebuild:CreateReport", - "codebuild:UpdateReport", - "codebuild:BatchPutTestCases", - "codebuild:BatchPutCodeCoverages" - ] -} -``` - -The following restricts permissions to only report groups created by running builds of a project named `my-project`: - -``` -{ - "Effect": "Allow", - "Resource": [ - "arn:aws:codebuild:your-region:your-aws-account-id:report-group/my-project-*" - ], - "Action": [ - "codebuild:CreateReportGroup", - "codebuild:CreateReport", - "codebuild:UpdateReport", - "codebuild:BatchPutTestCases", - "codebuild:BatchPutCodeCoverages" - ] -} -``` - -**Note** -The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. - -## Permissions for test reporting operations - - You can specify permissions for the following test reporting CodeBuild API operations: -+ `BatchGetReportGroups` -+ `BatchGetReports` -+ `CreateReportGroup` -+ `DeleteReportGroup` -+ `DeleteReport` -+ `DescribeTestCases` -+ `ListReportGroups` -+ `ListReports` -+ `ListReportsForReportGroup` -+ `UpdateReportGroup` - -For more information, see [AWS CodeBuild permissions reference](auth-and-access-control-permissions-reference.md)\. - -## Test reporting permissions examples - - For information about sample policies related to test reporting, see the following: -+ [Allow a user to change a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-change-report-group) -+ [Allow a user to create a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-create-report-group) -+ [Allow a user to delete a report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report) -+ [Allow a user to delete a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-delete-report-group) -+ [Allow a user to get information about report groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-report-group) -+ [Allow a user to get information about reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-get-information-about-reports) -+ [Allow a user to get a list of report groups](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-report-groups) -+ [Allow a user to get a list of reports](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports) -+ [Allow a user to get a list of reports for a report group](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-reports-for-report-group) -+ [Allow a user to get a list of test cases for a report](auth-and-access-control-iam-identity-based-access-control.md#customer-managed-policies-example-get-list-of-test-cases-for-report) \ No newline at end of file diff --git a/doc_source/test-report-group-create-buildspec.md b/doc_source/test-report-group-create-buildspec.md deleted file mode 100644 index 625ecd3..0000000 --- a/doc_source/test-report-group-create-buildspec.md +++ /dev/null @@ -1,24 +0,0 @@ -# Create a report group \(buildspec\) - -A report group created using the buildspec does not export raw test result files\. You can view your report group and specify export settings\. For more information, see [Update a report group](report-group-export-settings.md)\. - -**To create a report group using a buildspec file** - -1. Choose a report group name that is not associated with a report group in your AWS account\. - -1. Configure the `reports` section of the buildspec file with this name\. In this example, the report group name is `new-report-group` and the use test cases are created with the JUnit framework: - - ``` - reports: - new-report-group: #surefire junit reports - files: - - '**/*' - base-directory: 'surefire/target/surefire-reports' - ``` - - For more information, see [Specify test files](report-group-test-cases.md) and [Reports syntax in the buildspec file](build-spec-ref.md#reports-buildspec-file)\. - -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)\. - diff --git a/doc_source/test-report-group-create-cfn.md b/doc_source/test-report-group-create-cfn.md deleted file mode 100644 index 2a93288..0000000 --- a/doc_source/test-report-group-create-cfn.md +++ /dev/null @@ -1,40 +0,0 @@ -# Create a report group \(AWS CloudFormation\) - - **To create a test report using the AWS CloudFormation template** - - You can use an AWS CloudFormation template file to create and provision a report group\. For more information, see [AWS CloudFormation User Guide](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)\. - - The following AWS CloudFormation YAML template creates a report group that does not export raw test result files\. - -``` -Resources: - CodeBuildReportGroup: - Type: AWS::CodeBuild::ReportGroup - Properties: - Name: my-report-group-name - Type: TEST - ExportConfig: - ExportConfigType: NO_EXPORT -``` - - The following AWS CloudFormation YAML template creates a report group that exports raw test result files to an Amazon S3 bucket\. - -``` -Resources: - CodeBuildReportGroup: - Type: AWS::CodeBuild::ReportGroup - Properties: - Name: my-report-group-name - Type: TEST - ExportConfig: - ExportConfigType: S3 - S3Destination: - Bucket: my-s3-bucket-name - Path: path-to-folder-for-exported-files - Packaging: ZIP - EncryptionKey: my-KMS-encryption-key - EncryptionDisabled: false -``` - -**Note** -The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. \ No newline at end of file diff --git a/doc_source/test-report-group-create-cli.md b/doc_source/test-report-group-create-cli.md deleted file mode 100644 index c2d8a83..0000000 --- a/doc_source/test-report-group-create-cli.md +++ /dev/null @@ -1,55 +0,0 @@ -# Create a report group \(CLI\) - -**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`: - + Use the following JSON to specify that your test report group exports raw test result files to an Amazon S3 bucket\. - - ``` - { - "name": "", - "type": "TEST", - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "", - "bucketOwner": "", - "path": "", - "packaging": "NONE | ZIP", - "encryptionDisabled": "false", - "encryptionKey": "" - }, - "tags": [ - { - "key": "tag-key", - "value": "tag-value" - } - ] - } - } - ``` - + 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": "", - "type": "TEST", - "exportConfig": { - "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: - - ``` - 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 deleted file mode 100644 index 3c131b3..0000000 --- a/doc_source/test-report-group-create-console.md +++ /dev/null @@ -1,36 +0,0 @@ -# Create a report group \(console\) - -**To create a test report** - -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. 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. If you want to upload the raw data of your test report results to an Amazon S3 bucket: - - 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. 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)\. -**Note** -The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. - -1. Choose **Create report group**\. \ No newline at end of file diff --git a/doc_source/test-report-group-naming.md b/doc_source/test-report-group-naming.md deleted file mode 100644 index d25d1ea..0000000 --- a/doc_source/test-report-group-naming.md +++ /dev/null @@ -1,14 +0,0 @@ -# Report group naming - - When you use the AWS CLI or the AWS CodeBuild console to create a report group, you specify a name for the report group\. If you use the buildspec to create a new report group, it is named using the format `project-name-report-group-name-specified-in-buildspec`\. All reports created by running builds of that build project belong to the new report group that has the new name\. - - If you do not want CodeBuild to create a new report group, specify the ARN of the report group in a build project's buildspec file\. You can specify a report group's ARN in multiple build projects\. After each build project runs, the report group contains test reports created by each build project\. - - For example, if you create one report group with the name `my-report-group`, and then use its name in two different build projects named `my-project-1` and `my-project-2` and create a build of both projects, two new report groups are created\. The result is three report groups with the following names: -+ `my-report-group`: Does not have any test reports\. -+ `my-project-1-my-report-group`: Contains reports with results of tests run by the build project named `my-project-1`\. -+ `my-project-2-my-report-group`: Contains reports with results of tests run by the build project named `my-project-2`\. - - If you use the ARN of the report group named `my-report-group` in both projects, and then run builds of each project, you still have one report group \(`my-report-group`\)\. That report group contains test reports with results of tests run by both build projects\. - - If you choose a report group name that doesn't belong to a report group in your AWS account, and then use that name for a report group in a buildspec file and run a build of its build project, a new report group is created\. The format of name of the new report group is `project-name-new-group-name`\. For example, if there is not a report group in your AWS account with the name `new-report-group`, and specify it in a build project called `test-project`, a build run creates a new report group with the name `test-project-new-report-group`\. \ No newline at end of file diff --git a/doc_source/test-report-group.md b/doc_source/test-report-group.md deleted file mode 100644 index 1e2e856..0000000 --- a/doc_source/test-report-group.md +++ /dev/null @@ -1,16 +0,0 @@ -# Working with report groups - -A *report group* contains test reports and specifies shared settings\. You use the buildspec file to specify the test cases to run and the commands to run them when it builds\. For each report group configured in a build project, a run of the build project creates a test report\. Multiple runs of a build project configured with a report group create multiple test reports in that report group, each with results of the same test cases specified for that report group\. - - The test cases are specified for a report group in the buildspec file of a build project\. You can specify up to five report groups in one build project\. When you run a build, all the test cases run\. A new test report is created with the results of each test case specified for a report group\. Each time you run a new build, the test cases run and a new test report is created with the new test results\. - - Report groups can be used in more than one build project\. All test reports created with one report group share the same configuration, such as its export option and permissions, even if the test reports are created using different build projects\. Test reports created with one report group in multiple build projects can contain the results from running different sets of test cases \(one set of test cases for each build project\)\. This is because you can specify different test case files for the report group in each project's buildspec file\. You can also change the test case files for a report group in a build project by editing its buildspec file\. Subsequent build runs create new test reports that contain the results of the test case files in the updated buildspec\. - -**Topics** -+ [Create a report group](report-group-create.md) -+ [Update a report group](report-group-export-settings.md) -+ [Specify test files](report-group-test-cases.md) -+ [Specify test commands](report-group-test-case-commands.md) -+ [Report group naming](test-report-group-naming.md) -+ [Tagging report groups in AWS CodeBuild](how-to-tag-report-group.md) -+ [Working with shared report groups](report-groups-sharing.md) \ No newline at end of file diff --git a/doc_source/test-report-jasmine.md b/doc_source/test-report-jasmine.md deleted file mode 100644 index 5a98f23..0000000 --- a/doc_source/test-report-jasmine.md +++ /dev/null @@ -1,91 +0,0 @@ -# Set up test reporting with Jasmine - -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 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\. - -``` -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 run\. - -``` -{ - "scripts": { - "test": "npx jasmine" - } -} -``` - -CodeBuild supports the following Jasmine test reporters: - -JUnitXmlReporter -Used to generate reports in the `JunitXml` format\. - -NUnitXmlReporter -Used to generate reports in the `NunitXml` format\. - -A Node\.js project with Jasmine will, by default, have a `spec` sub\-directory, which contains the Jasmine configuration and test scripts\. - -To configure Jasmine to generate reports in the `JunitXML` format, instantiate the `JUnitXmlReporter` reporter by adding the following code to your tests\. - -``` -var reporters = require('jasmine-reporters'); - -var junitReporter = new reporters.JUnitXmlReporter({ - savePath: , - filePrefix: , - consolidateAll: true -}); - -jasmine.getEnv().addReporter(junitReporter); -``` - -To configure Jasmine to generate reports in the `NunitXML` format, instantiate the `NUnitXmlReporter` reporter by adding the following code to your tests\. - -``` -var reporters = require('jasmine-reporters'); - -var nunitReporter = new reporters.NUnitXmlReporter({ - savePath: , - filePrefix: , - consolidateAll: true -}); - -jasmine.getEnv().addReporter(nunitReporter) -``` - -The test reports are exported to the file specified by **/**\. - -In your `buildspec.yml` file, add/update the following sections\. - -``` -version: 0.2 - -phases: - pre_build: - commands: - - npm install - build: - commands: - - npm build - - npm test - -reports: - jasmine_reports: - files: - - - 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 -``` \ No newline at end of file diff --git a/doc_source/test-report-jest.md b/doc_source/test-report-jest.md deleted file mode 100644 index 53e2948..0000000 --- a/doc_source/test-report-jest.md +++ /dev/null @@ -1,59 +0,0 @@ -# Set up test reporting with Jest - -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 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\. 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 run\. - -``` -{ - "scripts": { - "test": "jest" - } -} -``` - -Configure Jest to use the `JunitXml` reporter by adding the following to your Jest configuration file\. If your project does not have a Jest configuration file, create a file named `jest.config.js` in the root of your project and add the following\. The test reports are exported to the file specified by **/**\. - -``` -module.exports = { - reporters: [ - 'default', - [ 'jest-junit', { - outputDirectory: , - outputName: , - } ] - ] -}; -``` - -In your `buildspec.yml` file, add/update the following sections\. - -``` -version: 0.2 - -phases: - pre_build: - commands: - - npm install - build: - commands: - - npm build - - npm test - -reports: - jest_reports: - files: - - - 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 deleted file mode 100644 index 04b14ff..0000000 --- a/doc_source/test-report-pytest.md +++ /dev/null @@ -1,36 +0,0 @@ -# Set up test reporting with pytest - -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 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\. - -``` - - python -m pytest --junitxml=/ -``` - -In your `buildspec.yml` file, add/update the following sections\. - -``` -version: 0.2 - -phases: - install: - runtime-versions: - python: 3.7 - commands: - - pip3 install pytest - build: - commands: - - python -m pytest --junitxml=/ - -reports: - pytest_reports: - files: - - - base-directory: - 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 deleted file mode 100644 index a1e6e67..0000000 --- a/doc_source/test-report-rspec.md +++ /dev/null @@ -1,31 +0,0 @@ -# Set up test reporting with RSpec - -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 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\. - -``` -version: 0.2 - -phases: - install: - runtime-versions: - ruby: 2.6 - pre_build: - commands: - - gem install rspec - - gem install rspec_junit_formatter - build: - commands: - - rspec /* --format RspecJunitFormatter --out / -reports: - rspec_reports: - files: - - - base-directory: - file-format: JUNITXML -``` \ No newline at end of file diff --git a/doc_source/test-report.md b/doc_source/test-report.md deleted file mode 100644 index 5e89eb3..0000000 --- a/doc_source/test-report.md +++ /dev/null @@ -1,24 +0,0 @@ -# Working with reports - -A report contains the results of test cases that are specified for one report group\. A test report is created during the run of a build project\. You specify a report group, test case files, and commands to run the test cases in its buildspec file\. Each time the test cases run, a new test report is created in the report group\. - - A test report expires 30 days after it is created\. You cannot view an expired test report, but you can export the test results to raw test result files in an S3 bucket\. Exported raw test files do not expire\. For more information, see [Update a report group](report-group-export-settings.md)\. - -The status of a test report can be one of the following: -+ `GENERATING`: The run of the test cases is still in progress\. -+ `DELETING`: The test report is being deleted\. When a test report is deleted, its test cases are also deleted\. Raw test result data files exported to an S3 bucket are not deleted\. -+ `INCOMPLETE`: The test report was not completed\. This status might be returned for one of the following reasons: - + A problem with the configuration of the report group that specifies this report's test cases\. For example, the path to the test cases under the report group in the buildspec file might be incorrect\. - + The IAM user that ran the build does not have permissions to run tests\. For more information, see [Working with test report permissions](test-permissions.md)\. - + The build was not completed because of an error that is not related to the tests\. -+ `SUCCEEDED`: All test cases were successful\. -+ `FAILED`: Some of the test cases were not successful\. - -Each test case returns a status\. The status for a test case can be one of the following: -+ `SUCCEEDED`: The test case passed\. -+ `FAILED`: The test case failed\. -+ `ERROR`: The test case resulted in an unexpected error\. -+ `SKIPPED`: The test case did not run\. -+ `UNKNOWN`: The test case returned a status other than `SUCCEEDED`, `FAILED`, `ERROR`, or `SKIPPED`\. - -A test report can have a maximum of 500 test case results\. If more than 500 test cases are run, CodeBuild prioritizes tests with the status `FAILED` and truncates the test case results\. \ No newline at end of file diff --git a/doc_source/test-reporting.md b/doc_source/test-reporting.md deleted file mode 100644 index 07aa636..0000000 --- a/doc_source/test-reporting.md +++ /dev/null @@ -1,34 +0,0 @@ -# Working with test reporting in AWS CodeBuild - -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 \(\.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\)\. - -To create a test report, you add a report group name to the buildspec file of a build project with information about your test cases\. When you run the build project, the test cases are run and a test report is created\. You do not need to create a report group before you run your tests\. If you specify a report group name, CodeBuild creates a report group for you when you run your reports\. If you want to use a report group that already exists, you specify its ARN in the buildspec file\. - -You can use a test report to help troubleshoot a problem during a build run\. If you have many test reports from multiple builds of a build project, you can use your test reports to view trends and test and failure rates to help you optimize builds\. - -A report expires 30 days after it was created\. You cannot view an expired test report\. If you want to keep test reports for more than 30 days, you can export your test results' raw data files to an Amazon S3 bucket\. Exported test files do not expire\. Information about the S3 bucket is specified when you create the report group\. - -**Note** -The CodeBuild service role specified in the project is used for permissions to upload to the S3 bucket\. - -**Topics** -+ [Create a test report](report-create.md) -+ [Working with report groups](test-report-group.md) -+ [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) -+ [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 deleted file mode 100644 index 9191cb0..0000000 --- a/doc_source/test-view-reports.md +++ /dev/null @@ -1,52 +0,0 @@ -# View test reports - - You can view details about a test report, such as information about its test cases, pass and fail numbers, and how long it took for it to run\. You can view test reports grouped by build run, report group, or your AWS account\. Choose a test report in the console to see its details and results of its test cases\. - - You can see view test reports that are not expired\. Test reports expire 30 days after they are created\. You cannot view an expired report in CodeBuild\. - -**Topics** -+ [View test reports for a build](#test-view-project-reports) -+ [View test reports for a report group](#test-view-report-group-reports) -+ [View test reports in your AWS account](#test-view-account-reports) - -## View test reports for a build - -**To view test reports for a build** - -1. Open the AWS CodeBuild console at [https://console\.aws\.amazon\.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home)\. - -1. Locate the build you want to view\. If you know the project that ran the build that created the test report: - - 1. In the navigation pane, choose **Build projects**, and then choose the project with the build that ran the test report you want to view\. - - 1. Choose **Build history**, and then choose the build that ran created the reports you want to view\. - - You can also locate the build in the build history for your AWS account: - - 1. In the navigation pane, choose **Build history**, and then choose the build that created the test reports you want to view\. - -1. In the build page, choose **Reports**, and then choose a test report to see its details\. - -## View test reports for a report group - -**To view test reports in a report group** - -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. Choose the report group that contains the test reports you want to view\. - -1. Choose a test report to see its details\. - -## 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)\. - -1. In the navigation pane, choose **Report history**\. - -1. Choose a test report to see its details\. \ No newline at end of file diff --git a/doc_source/trigger-create.md b/doc_source/trigger-create.md deleted file mode 100644 index 8a028af..0000000 --- a/doc_source/trigger-create.md +++ /dev/null @@ -1,46 +0,0 @@ -# Create AWS CodeBuild triggers - -## Create AWS CodeBuild triggers \(console\) - -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** - -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 to which you want to add a trigger, and then choose the **Build triggers** tab\. -**Note** -By default, the 100 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. - -1. Choose **Create trigger**\. - -1. Enter a name in **Trigger name**\. - -1. From the **Frequency** drop\-down list, choose the frequency for your trigger\. If you want to create a frequency using a cron expression, choose **Custom**\. - -1. Specify the parameters for the frequency of your trigger\. You can enter the first few characters of your selections in the text box to filter drop\-down menu items\. -**Note** - Start hours and minutes are zero\-based\. The start minute is a number between zero and 59\. The start hour is a number between zero and 23\. For example, a daily trigger that starts every day at 12:15 P\.M\. has a start hour of 12 and a start minute of 15\. A daily trigger that starts every day at midnight has a start hour of zero and a start minute of zero\. A daily trigger that starts every day at 11:59 P\.M\. has a start hour of 23 and a start minute of 59\. -**** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/trigger-create.html) - -1. Select **Enable this trigger**\. - -1. \(Optional\) Expand **Advanced section**\. In **Source version**, type a version of your source\. - + For Amazon S3, enter the version ID that corresponds to the version of the input artifact you want to build\. If **Source version** is left blank, the latest version is used\. - + For AWS CodeCommit, type a commit ID\. If **Source version** is left blank, the default branch's HEAD commit ID is used\. - + For GitHub or GitHub Enterprise, type a commit ID, a pull request ID, a branch name, or a tag name that corresponds to 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\. - + For Bitbucket, type a commit ID, a branch name, or a tag name that corresponds to 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\. - -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**\. - -## 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 deleted file mode 100644 index da3b8f3..0000000 --- a/doc_source/triggers-edit.md +++ /dev/null @@ -1,34 +0,0 @@ -# Edit AWS CodeBuild triggers - -## 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** - -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 change, and then choose the **Build triggers** tab\. -**Note** -By default, the 100 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. - -1. Choose the radio button next to the trigger you want to change, and then choose **Edit**\. - -1. From the **Frequency** drop\-down list, choose the frequency for your trigger\. If you want to create a frequency using a cron expression, choose **Custom**\. - -1. Specify the parameters for the frequency of your trigger\. You can enter the first few characters of your selections in the text box to filter drop\-down menu items\. -**Note** - Start hours and minutes are zero\-based\. The start minute is a number between zero and 59\. The start hour is a number between zero and 23\. For example, a daily trigger that starts every day at 12:15 P\.M\. has a start hour of 12 and a start minute of 15\. A daily trigger that starts every day at midnight has a start hour of zero and a start minute of zero\. A daily trigger that starts every day at 11:59 P\.M\. has a start hour of 23 and a start minute of 59\. -**** -[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/triggers-edit.html) - -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\. - -## 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 deleted file mode 100644 index 3853910..0000000 --- a/doc_source/troubleshooting.md +++ /dev/null @@ -1,537 +0,0 @@ -# Troubleshooting AWS CodeBuild - -Use the information in this topic to help you identify, diagnose, and address issues\. To learn how to log and monitor CodeBuild builds to troubleshoot issues, see [Logging and monitoring](logging-monitoring.md)\. - -**Topics** -+ [Apache Maven builds reference artifacts from the wrong repository](#troubleshooting-maven-repos) -+ [Build commands run as root by default](#troubleshooting-root-build-commands) -+ [Builds might fail when file names have non\-U\.S\. English characters](#troubleshooting-utf-8) -+ [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) -+ [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 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) -+ [Error: "Git clone failed: Unable to access `'your-repository-URL'`: SSL certificate problem: Self signed certificate"](#troubleshooting-self-signed-certificate) -+ [Error: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build](#troubleshooting-input-bucket-different-region) -+ [Error: "The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation\."](#enhanced-zero-click-role-creation) -+ [Error: "This build image requires selecting at least one runtime version\."](#troubleshooting-build-must-specify-runtime) -+ [Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails](#queued-insufficient-subnet-error) -+ [Error: "Unable to download cache: RequestError: Send request failed caused by: x509: Failed to load system roots and no roots provided"](#troubleshooting-cache-image) -+ [Error: "Unable to download certificate from S3\. AccessDenied"](#troubleshooting-certificate-in-S3) -+ [Error: "Unable to locate credentials"](#troubleshooting-versions) -+ [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 - -**Issue:** When you use Maven with an AWS CodeBuild\-provided Java build environment, Maven pulls build and plugin dependencies from the secure central Maven repository at [https://repo1\.maven\.org/maven2](https://repo1.maven.org/maven2)\. This happens even if your build project's `pom.xml` file explicitly declares other locations to use instead\. - -**Possible cause:** CodeBuild\-provided Java build environments include a file named `settings.xml` that is preinstalled in the build environment's `/root/.m2` directory\. This `settings.xml` file contains the following declarations, which instruct Maven to always pull build and plugin dependencies from the secure central Maven repository at [https://repo1\.maven\.org/maven2](https://repo1.maven.org/maven2)\. - -``` - - - securecentral - - - - securecentral - - - central - https://repo1.maven.org/maven2 - - true - - - - - - central - https://repo1.maven.org/maven2 - - true - - - - - - -``` - -**Recommended solution:** Do the following: - -1. Add a `settings.xml` file to your source code\. - -1. In this `settings.xml` file, use the preceding `settings.xml` format as a guide to declare the repositories you want Maven to pull the build and plugin dependencies from instead\. - -1. In the `install` phase of your build project, instruct CodeBuild to copy your `settings.xml` file to the build environment's `/root/.m2` directory\. For example, consider the following snippet from a `buildspec.yml` file that demonstrates this behavior\. - - ``` - version 0.2 - - phases: - install: - commands: - - cp ./settings.xml /root/.m2/settings.xml - ``` - -## Build commands run as root by default - -**Issue:** AWS CodeBuild runs your build commands as the root user\. This happens even if your related build image's Dockerfile sets the `USER` instruction to a different user\. - -**Cause:** By default, CodeBuild runs all build commands as the root user\. - -**Recommended solution:** None\. - -## Builds might fail when file names have non\-U\.S\. English characters - -**Issue:** When you run a build that uses files with file names that contain non\-U\.S\. English characters \(for example, Chinese characters\), the build fails\. - -**Possible cause:** Build environments provided by AWS CodeBuild have their default locale set to `POSIX`\. `POSIX` localization settings are less compatible with CodeBuild and file names that contain non\-U\.S\. English characters and can cause related builds to fail\. - -**Recommended solution:** Add the following commands to the `pre_build` section of your buildspec file\. These commands make the build environment use U\.S\. English UTF\-8 for its localization settings, which is more compatible with CodeBuild and file names that contain non\-U\.S\. English characters\. - -For build environments based on Ubuntu: - -``` -pre_build: - commands: - - export LC_ALL="en_US.UTF-8" - - locale-gen en_US en_US.UTF-8 - - dpkg-reconfigure locales -``` - -For build environments based on Amazon Linux: - -``` -pre_build: - commands: - - export LC_ALL="en_US.utf8" -``` - -## Builds might fail when getting parameters from Amazon EC2 Parameter Store - -**Issue:** When a build tries to get the value of one or more parameters stored in Amazon EC2 Parameter Store, the build fails in the `DOWNLOAD_SOURCE` phase with the error `Parameter does not exist`\. - -**Possible cause:** The service role the build project relies on does not have permission to call the `ssm:GetParameters` action or the build project uses a service role that is generated by AWS CodeBuild and allows calling the `ssm:GetParameters` action, but the parameters have names that do not start with `/CodeBuild/`\. - - **Recommended solutions:** -+ If the service role was not generated by CodeBuild, update its definition to allow CodeBuild to call the `ssm:GetParameters` action\. For example, the following policy statement allows calling the `ssm:GetParameters` action to get parameters with names starting with `/CodeBuild/`: - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Action": "ssm:GetParameters", - "Effect": "Allow", - "Resource": "arn:aws:ssm:REGION_ID:ACCOUNT_ID:parameter/CodeBuild/*" - } - ] - } - ``` -+ If the service role was generated by CodeBuild, update its definition to allow CodeBuild to access parameters in Amazon EC2 Parameter Store with names other than those starting with `/CodeBuild/`\. For example, the following policy statement allows calling the `ssm:GetParameters` action to get parameters with the specified name: - - ``` - { - "Version": "2012-10-17", - "Statement": [ - { - "Action": "ssm:GetParameters", - "Effect": "Allow", - "Resource": "arn:aws:ssm:REGION_ID:ACCOUNT_ID:parameter/PARAMETER_NAME" - } - ] - } - ``` - -## Cannot access branch filter in the CodeBuild console - -**Issue:** The branch filter option is not available in the console when you create or update an AWS CodeBuild project\. - - **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 [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 - -**Issue:** You cannot see the success or failure of a retried 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) in the *AWS CodeBuild API Reference*\. - -## Build status not reported to source provider - -**Issue:** After allowing build status reporting to a source provider, such as GitHub or Bitbucket, the build status is not updated\. - -**Possible cause:** The user associated with the source provider does not have write access to the repo\. - -**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 2019 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\. - - **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 - -**Issue:** The results of one or more commands in your buildspec file are not recognized by later commands in the same buildspec file\. For example, a command might set a local environment variable, but a command run later might fail to get the value of that local environment variable\. - -**Possible cause:** In buildspec file version 0\.1, AWS CodeBuild runs each command in a separate instance of the default shell in the build environment\. This means that each command runs in isolation from all other commands\. By default, then, you cannot run a single command that relies on the state of any previous commands\. - -**Recommended solutions:** We recommend that you use build spec version 0\.2, which solves this issue\. If you must use buildspec version 0\.1, we recommend that you use the shell command chaining operator \(for example, `&&` in Linux\) to combine multiple commands into a single command\. Or include a shell script in your source code that contains multiple commands, and then call that shell script from a single command in the buildspec file\. For more information, see [Shells and commands in build environments](build-env-ref-cmd.md) and [Environment variables in build environments](build-env-ref-env-vars.md)\. - -## Error: "Access denied" when attempting to download cache - -**Issue:** When attempting to download the cache on a build project that has cache enabled, you receive an `Access denied` error\. - - **Possible causes:** -+ You have just configured caching as part of your build project\. -+ The cache has recently been invalidated through the `InvalidateProjectCache` API\. -+ The service role being used by CodeBuild does not have `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. - -**Recommended solution:** For first time use, it's normal to see this immediately after updating the cache configuration\. If this error persists, then you should check to see if your service role has `s3:GetObject` and `s3:PutObject` permissions to the S3 bucket that is holding the cache\. For more information, see [Specifying S3 permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html) in the *Amazon S3 Developer Guide*\. - -## Error: "BUILD\_CONTAINER\_UNABLE\_TO\_PULL\_IMAGE" when using a custom build image - -**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 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\. - -***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" - - **Issue:** When you try to use a Microsoft Windows or Linux container in AWS CodeBuild, this error occurs during the PROVISIONING phase\. - - **Possible causes:** -+ The container OS version is not supported by CodeBuild\. -+ `HTTP_PROXY`, `HTTPS_PROXY`, or both are specified in the container\. - - **Recommended solutions:** -+ For Microsoft Windows, use a Windows container with a container OS that is version microsoft/windowsservercore:10\.0\.x \(for example, microsoft/windowsservercore:10\.0\.14393\.2125\)\. -+ For Linux, clear the `HTTP_PROXY` and `HTTPS_PROXY` settings in your Docker image, or specify the VPC configuration in your build project\. - -## Error: "Cannot connect to the Docker daemon" when running a build - -**Issue:** Your build fails and you receive an error similar to `Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running?` in the build log\. - -**Possible cause:** You are not running your build in privileged mode\. - -**Recommended solution:** Follow these steps to run your build in privileged mode: - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In the navigation pane, choose **Build projects**, and then choose your build project\. - -1. From **Edit**, choose **Environment**\. - -1. Choose **Override images**, and then choose **Environment**\. - -1. Specify your environment image, operating system, runtime, and image\. These settings should match the settings for the build that failed\. - -1. Select **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\. - -1. Choose **Update environment**\. - -1. Choose **Start build** to retry your build\. - -## 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`\. - - **Possible causes:** -+ The AWS Security Token Service \(AWS STS\) has been deactivated for the AWS region where you are attempting to create or update the build project\. -+ The AWS CodeBuild service role associated with the build project does not exist or does not have sufficient permissions to trust CodeBuild\. - - **Recommended solutions:** -+ Make sure AWS STS is activated for the AWS region where you are attempting to create or update the build project\. For more information, see [Activating and deactivating AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) in the *IAM User Guide*\. -+ Make sure the target CodeBuild service role exists in your AWS account\. If you are not using the console, make sure you did not misspell the Amazon Resource Name \(ARN\) of the service role when you created or updated the build project\. -+ Make sure the target CodeBuild service role has sufficient permissions to trust CodeBuild\. For more information, see the trust relationship policy statement in [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. - -## Error: "Error calling GetBucketAcl: Either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl" - -**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\. - -**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)\. - -## Error: "Failed to upload artifacts: Invalid arn" when running a build - -**Issue:** When you run a build, the `UPLOAD_ARTIFACTS` build phase fails with the error `Failed to upload artifacts: Invalid arn`\. - -**Possible cause:** Your S3 output bucket \(the bucket where AWS CodeBuild stores its output from the build\) is in an AWS Region different from the CodeBuild build project\. - -**Recommended solution:** Update the build project's settings to point to an output bucket that is in the same AWS Region as the build project\. - -## Error: "Git clone failed: Unable to access `'your-repository-URL'`: SSL certificate problem: Self signed certificate" - -**Issue:** When you try to run a build project, the build fails with this error\. - - **Possible cause:** Your source repository has a self\-signed certificate, but you have not chosen to install the certificate from your S3 bucket as part of your build project\. - - **Recommended solutions:** -+ Edit your project\. For **Certificate**, choose **Install certificate from S3**\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. For **Object key of certificate**, enter the name of your S3 object key\. -+ Edit your project\. Select **Insecure SSL** to ignore SSL warnings while connecting to your GitHub Enterprise Server project repository\. -**Note** -We recommend that you use **Insecure SSL** for testing only\. It should not be used in a production environment\. - -## Error: "The bucket you are attempting to access must be addressed using the specified endpoint" when running a build - -**Issue:** When you run a build, the `DOWNLOAD_SOURCE` build phase fails with the error `The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint`\. - -**Possible cause:** Your pre\-built source code is stored in an S3 bucket, and that bucket is in an AWS Region different from the AWS CodeBuild build project\. - -**Recommended solution:** Update the build project's settings to point to a bucket that contains your pre\-built source code\. Make sure that bucket is in the same AWS Region as the build project\. - -## Error: "The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation\." - -**Issue:** When you try to update a project in the console, the update failed with this error: - - **Possible causes:** -+ You have updated the policies attached to the target AWS CodeBuild service role\. -+ You have selected an earlier version of a policy attached to the target CodeBuild service role\. - - **Recommended solutions:** -+ Edit your CodeBuild project and clear the **Allow CodeBuild to modify this service role so it can be used with this build project** check box\. Verify the CodeBuild service role you are using has sufficient permissions\. If you edit your CodeBuild project again, you must clear this check box again\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. -+ Follow these steps to edit your CodeBuild project to use a new service role: - - 1. Open the IAM console and create a new service role\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. - - 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 button next to your build project, choose **Edit**, and then choose **Environment**\. - - 1. For **Service role**, choose the role you created\. - - 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`\. - -**Possible cause:** Your build uses 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 not specified in the buildspec file\. - -**Recommended solution:** If you use the `aws/codebuild/standard:2.0` CodeBuild managed image, you must specify a runtime version in the `runtime-versions` section of the buildspec file\. For example, you might use the following buildspec file for a project that uses PHP: - -``` -version: 0.2 - -phases: - install: - runtime-versions: - php: 7.3 - build: - commands: - - php --version -artifacts: - files: - - README.md -``` - -**Note** - 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`\." - - For more information, see [Specify runtime versions in the buildspec file](build-spec-ref.md#runtime-versions-buildspec-file)\. - -## Error: "QUEUED: INSUFFICIENT\_SUBNET" when a build in a build queue fails - -**Issue:** A build in a build queue fails with an error similar to `QUEUED: INSUFFICIENT_SUBNET`\. - -**Possible causes:** The IPv4 CIDR block specified for your VPC uses a reserved IP address\. The first four IP addresses and the last IP address in each subnet CIDR block are not available for you to use and cannot be assigned to an instance\. For example, in a subnet with CIDR block `10.0.0.0/24`, the following five IP addresses are reserved: -+ `10.0.0.0:` Network address\. -+ `10.0.0.1`: Reserved by AWS for the VPC router\. -+ `10.0.0.2`: Reserved by AWS\. The IP address of the DNS server is always the base of the VPC network range plus two; however, we also reserve the base of each subnet range plus two\. For VPCs with multiple CIDR blocks, the IP address of the DNS server is located in the primary CIDR\. For more information, see [Amazon DNS server](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html#AmazonDNS) in the *Amazon VPC User Guide*\. -+ `10.0.0.3`: Reserved by AWS for future use\. -+ `10.0.0.255`: Network broadcast address\. We do not support broadcast in a VPC\. This address is reserved\. - -**Recommended solutions:** Check if your VPC uses a reserved IP address\. Replace any reserved IP address with one that is not reserved\. For more information, see [VPC and subnet sizing](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html#VPC_Sizing) in the *Amazon VPC User Guide*\. - -## Error: "Unable to download cache: RequestError: Send request failed caused by: x509: Failed to load system roots and no roots provided" - -**Issue:** When you try to run a build project, the build fails with this error\. - - **Possible cause:** You configured caching as part of your build project and are using an older Docker image that includes an expired root certificate\. - - **Recommended solution:** Update the Docker image that is being used in your AWS CodeBuild the project\. For more information, see [Docker images provided by CodeBuild](build-env-ref-available.md)\. - -## Error: "Unable to download certificate from S3\. AccessDenied" - -**Issue:** When you try to run a build project, the build fails with this error\. - - **Possible causes:** -+ You have chosen the wrong S3 bucket for your certificate\. -+ You have entered the wrong object key for your certificate\. - - **Recommended solutions:** -+ Edit your project\. For **Bucket of certificate**, choose the S3 bucket where your SSL certificate is stored\. -+ Edit your project\. For **Object key of certificate**, enter the name of your S3 object key\. - -## Error: "Unable to locate credentials" - -**Issue:** When you try to run the AWS CLI, use an AWS SDK, or call another similar component as part of a build, you get build errors that are directly related to the AWS CLI, AWS SDK, or component\. For example, you might get a build error such as `Unable to locate credentials`\. - - **Possible causes:** -+ The version of the AWS CLI, AWS SDK, or component in the build environment is incompatible with AWS CodeBuild\. -+ You are running a Docker container within a build environment that uses Docker, and the container does not have access to the AWS credentials by default\. - - **Recommended solutions:** -+ Make sure your build environment has the following version or higher of the AWS CLI, AWS SDK, or component\. - + AWS CLI: 1\.10\.47 - + AWS SDK for C\+\+: 0\.2\.19 - + AWS SDK for Go: 1\.2\.5 - + AWS SDK for Java: 1\.11\.16 - + AWS SDK for JavaScript: 2\.4\.7 - + AWS SDK for PHP: 3\.18\.28 - + AWS SDK for Python \(Boto3\): 1\.4\.0 - + AWS SDK for Ruby: 2\.3\.22 - + Botocore: 1\.4\.37 - + CoreCLR: 3\.2\.6\-beta - + Node\.js: 2\.4\.7 -+ If you need to run a Docker container in a build environment and the container requires AWS credentials, you must pass through the credentials from the build environment to the container\. In your buildspec file, include a Docker `run` command such as the following\. This example uses the `aws s3 ls` command to list your available S3 buckets\. The `-e` option passes through the environment variables required for your container to access AWS credentials\. - - ``` - docker run -e AWS_DEFAULT_REGION -e AWS_CONTAINER_CREDENTIALS_RELATIVE_URI your-image-tag aws s3 ls - ``` -+ If you are building a Docker image and the build requires AWS credentials \(for example, to download a file from Amazon S3\), you must pass through the credentials from the build environment to the Docker build process as follows\. - - 1. In your source code's Dockerfile for the Docker image, specify the following `ARG` instructions\. - - ``` - ARG AWS_DEFAULT_REGION - ARG AWS_CONTAINER_CREDENTIALS_RELATIVE_URI - ``` - - 1. In your buildspec file, include a Docker `build` command such as the following\. The `--build-arg` options sets the environment variables required for your Docker build process to access the AWS credentials\. - - ``` - docker build --build-arg AWS_DEFAULT_REGION=$AWS_DEFAULT_REGION --build-arg AWS_CONTAINER_CREDENTIALS_RELATIVE_URI=$AWS_CONTAINER_CREDENTIALS_RELATIVE_URI -t your-image-tag . - ``` - -## RequestError timeout error when running CodeBuild in a proxy server - - **Issue:** You receive a `RequestError` error similar to one of the following: -+ `RequestError: send request failed caused by: Post https://logs..amazonaws.com/: dial tcp 52.46.158.105:443: i/o timeout` from CloudWatch Logs\. -+ `Error uploading artifacts: RequestError: send request failed caused by: Put https://your-bucket.s3.your-aws-region.amazonaws.com/*: dial tcp 52.219.96.208:443: connect: connection refused` from Amazon S3\. - - **Possible causes:** -+ `ssl-bump` is not configured properly\. -+ Your organization's security policy does not allow you to use `ssl_bump`\. -+ Your buildspec file does not have proxy settings specified using a `proxy` element\. - -**Recommended solutions:** -+ Make sure `ssl-bump` is configured properly\. If you use Squid for your proxy server, see [ Configure Squid as an explicit proxy server](use-proxy-server.md#use-proxy-server-explicit-squid-configure)\. -+ Follow these steps to use private endpoints for Amazon S3 and CloudWatch Logs: - - 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](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)\. - - ``` - version: 0.2 - proxy: - upload-artifacts: yes - logs: yes - phases: - build: - commands: - ``` - -## The bourne shell \(sh\) must exist in build images - -**Issue:** You are using a build image that is not provided by AWS CodeBuild, and your builds fail with the message `Build container found dead before completing the build`\. - -**Possible cause:** The Bourne shell \(`sh`\) is not included in your build image\. CodeBuild needs `sh` to run build commands and scripts\. - -**Recommended solution:** If `sh` in not present in your build image, be sure to include it before you start any more builds that use your image\. \(CodeBuild already includes `sh` in its build images\.\) - -## Warning: "Skipping install of runtimes\. runtime version selection is not supported by this build image" when running a build - -**Issue:** When you run a build, the build log contains this warning\. - -**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\. - -## 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 deleted file mode 100644 index 257c344..0000000 --- a/doc_source/update-report-group-cli.md +++ /dev/null @@ -1,55 +0,0 @@ -# Update a report group \(CLI\) - -**To update a report group** - -1. Create a file named `UpdateReportGroupInput.json`\. - -1. Copy the following into `UpdateReportGroupInput.json`: - - ``` - { - "arn": "", - "exportConfig": { - "exportConfigType": "S3", - "s3Destination": { - "bucket": "bucket-name", - "path": "path", - "packaging": "NONE | ZIP", - "encryptionDisabled": "false", - "encryptionKey": "your-key" - } - }, - "tags": [ - { - "key": "tag-key", - "value": "tag-value" - } - ] - } - ``` - -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 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: - - ``` - { - "exportConfig": { - "exportConfigType": "NO_EXPORT" - } - } - ``` - + 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": [] - ``` - -1. Run the following command: - - ``` - 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 deleted file mode 100644 index abe5f6c..0000000 --- a/doc_source/update-report-group-console.md +++ /dev/null @@ -1,24 +0,0 @@ -# Update a report group \(console\) - -**To update a report group** - -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. Choose the report group you want to update\. - -1. Choose **Edit**\. - -1. Select or clear **Backup to Amazon S3**\. If you selected this option, specify your export settings: - - 1. For **S3 bucket name**, enter the name of the S3 bucket\. - - 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. 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 deleted file mode 100644 index 799b6b1..0000000 --- a/doc_source/use-case-based-samples.md +++ /dev/null @@ -1,63 +0,0 @@ -# CodeBuild use case\-based samples - -You can use these use case\-based samples to experiment with AWS CodeBuild: - -[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\. - -[Amazon EFS sample](sample-efs.md) -Shows how to configure a buildspec file so that a CodeBuild project mounts and builds on an Amazon EFS file system\. - -[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 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) -Shows how to set up AWS Config\. Lists which CodeBuild resources are tracked and describes how to look up CodeBuild projects in AWS Config\. - -[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\. - -[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\. - -[Build badges sample](sample-build-badges.md) -Shows how to set up CodeBuild with build badges\. - -[Build notifications sample](sample-build-notifications.md) -Uses Apache Maven to produce a single JAR file\. Sends a build notification to subscribers of an Amazon SNS topic\. - -[Create a test report using the AWS CLI sample](sample-test-report-cli.md) -Uses the AWS CLI to create, run, and view the results of a test report\. - -[Docker in custom image sample](sample-docker-custom-image.md) -Uses a custom Docker image to produce a Docker image\. - -[Docker sample](sample-docker.md) -Uses a build image provided by CodeBuild with Docker support to produce a Docker image with Apache Maven\. Pushes the Docker image to a repository in Amazon ECR\. You can also adapt this sample to push the Docker image to Docker Hub\. - -[GitHub Enterprise Server sample](sample-github-enterprise.md) -Uses CodeBuild with GitHub Enterprise Server as the source repository, with certificates installed and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. - -[GitHub pull request and webhook filter sample](sample-github-pull-request.md) -Uses CodeBuild with GitHub as the source repository and webhooks enabled, to rebuild the source code every time a code change is pushed to the repository\. - -[ Host build output in an S3 bucket ](sample-disable-artifact-encryption.md) -Shows how to create a static website in an S3 bucket using unencrypted build artifacts\. - -[ Multiple input sources and output artifacts sample ](sample-multi-in-out.md) -Shows how to use multiple input sources and multiple output artifacts in a build project\. - -[Private registry with AWS Secrets Manager sample](sample-private-registry.md) -Shows how to use a Docker image in a private registry as the runtime environment when building with CodeBuild The private registry credentials are stored in AWS Secrets Manager\. - -[ Runtime versions in buildspec file sample ](sample-runtime-versions.md) -Shows how to specify runtimes and their versions in the buildspec file\. This is a requirement when using the Ubuntu standard image version 2\.0\. - -[Source version sample](sample-source-version.md) -Shows how to use a specific version of your source in a CodeBuild build project\. - -[Use semantic versioning to name build artifacts sample](sample-buildspec-artifact-naming.md) -Shows how to use semantic versioning to create an artifact name at build time\. \ No newline at end of file diff --git a/doc_source/use-codebuild-agent.md b/doc_source/use-codebuild-agent.md deleted file mode 100644 index 076cecd..0000000 --- a/doc_source/use-codebuild-agent.md +++ /dev/null @@ -1,148 +0,0 @@ -# Run builds locally with the AWS CodeBuild 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\. - -You can also subscribe to receive notifications when new versions of the agent are published\. - -## Prerequisites - -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\. - -## Set up the build image - -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: - - ``` - $ docker pull public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:3.0 - ``` - - Alternatively, if you want to use another Linux image, perform the following steps: - - 1. Clone the CodeBuild image repo: - - ``` - $ 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 - ``` - - To download the ARM version of the agent, run the following command: - - ``` - $ docker pull public.ecr.aws/codebuild/local-builds:aarch64 - ``` - -1. The CodeBuild agent is available from [https://gallery\.ecr\.aws/codebuild/local\-builds](https://gallery.ecr.aws/codebuild/local-builds)\. - - The Secure Hash Algorithm \(SHA\) signature for the x86\_64 version of the agent is: - - ``` - sha256:fdfff9470520c53dcd522606a3cc2b5df195ae8a5546697b08249b48175f45ed - ``` - - The SHA signature for the ARM version of the agent is: - - ``` - sha256:5480b70cf48435e276c21789c61280cfada24e17701ede6386e5d82088bc41ca - ``` - - 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`: - - ``` - $ 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 - ``` - - 1. For **Protocol**, choose **Email** or **SMS**\. - - 1. For **Endpoint**, choose where \(email or SMS\) to receive the notifications\. Enter an email or address or phone number, including area code\. - - 1. Choose **Create 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, 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. 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 diff --git a/doc_source/use-proxy-server.md b/doc_source/use-proxy-server.md deleted file mode 100644 index b4ead5c..0000000 --- a/doc_source/use-proxy-server.md +++ /dev/null @@ -1,369 +0,0 @@ -# Use AWS CodeBuild with a proxy server - - You can use AWS CodeBuild with a proxy server to regulate HTTP and HTTPS traffic to and from the internet\. To run CodeBuild with a proxy server, you install a proxy server in a public subnet and CodeBuild in a private subnet in a VPC\. - -There are two primary use cases for running CodeBuild in a proxy server: -+ It eliminates the use of a NAT gateway or NAT instance in your VPC\. -+ 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)\. -+ **Transparent proxy**: If you use a transparent proxy server, no special configuration is required\. - -**Topics** -+ [Components required to run CodeBuild in a proxy server](#use-proxy-server-transparent-components) -+ [Run CodeBuild in an explicit proxy server](#run-codebuild-in-explicit-proxy-server) -+ [Run CodeBuild in a transparent proxy server](#run-codebuild-in-transparent-proxy-server) -+ [Run a package manager and other tools in a proxy server](#use-proxy-server-tools) - -## Components required to run CodeBuild in a proxy server - - You need these components to run AWS CodeBuild in a transparent or explicit proxy server: -+ A VPC\. -+ One public subnet in your VPC for the proxy server\. -+ One private subnet in your VPC for CodeBuild\. -+ An internet gateway that allows communcation between the VPC and the internet\. - - The following diagram shows how the components interact\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/codebuild-proxy-transparent.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - -### Set up a VPC, subnets, and a network gateway - - The following steps are required to run AWS CodeBuild in a transparent or explicit proxy server\. - -1. Create a VPC\. For information, see [Creating a VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#Create-VPC) in the *Amazon VPC User Guide*\. - -1. Create two subnets in your VPC\. One is a public subnet named `Public Subnet` in which your proxy server runs\. The other is a private subnet named `Private Subnet` in which CodeBuild runs\. - - For information, see [Creating a subnet in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/working-with-vpcs.html#AddaSubnet)\. - -1. Create and attach an internet gateway to your VPC\. For more information, see [Creating and attaching an internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. - -1. Add a rule to the default route table that routes outgoing traffic from the VPC \(0\.0\.0\.0/0\) to the internet gateway\. For information, see [Adding and removing routes from a route table](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#AddRemoveRoutes)\. - -1. Add a rule to the default security group of your VPC that allows ingress SSH traffic \(TCP 22\) from your VPC \(0\.0\.0\.0/0\)\. - -1. Follow the instructions in [Launching an instance using the launch instance wizard](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html) in the *Amazon EC2 User Guide* to launch an Amazon Linux instance\. When you run the wizard, choose the following options: - + In **Choose an Instance Type**, choose an Amazon Linux Amazon Machine Image \(AMI\)\. - + In **Subnet**, choose the public subnet you created earlier in this topic\. If you used the suggested name, it is **Public Subnet**\. - + In **Auto\-assign Public IP**, choose **Enable**\. - + On the **Configure Security Group** page, for **Assign a security group**, choose **Select an existing security group**\. Next, choose the default security group\. - + After you choose **Launch**, choose an existing key pair or create one\. - - Choose the default settings for all other options\. - -1. After your EC2 instance is running, disable source/destination checks\. For information, see [Disabling Source/Destination checks](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html#EIP_Disable_SrcDestCheck) in the *Amazon VPC User Guide*\. - -1. Create a route table in your VPC\. Add a rule to the route table that routes traffic destined for the internet to your proxy server\. Associate this route table with your private subnet\. This is required so that outbound requests from instances in your private subnet, where CodeBuild runs, are always routed through the proxy server\. - -### Install and configure a proxy server - - There are many proxy servers from which to choose\. An open\-source proxy server, Squid, is used here to demonstrate how AWS CodeBuild runs in a proxy server\. You can apply the same concepts to other proxy servers\. - - To install Squid, use a yum repo by running the following commands: - -``` -sudo yum update -y -sudo yum install -y squid -``` - - After you install Squid, edit its `squid.conf` file using the instructions later in this topic\. - -### Configure Squid for HTTPS traffic - - For HTTPS, the HTTP traffic is encapsulated in a Transport Layer Security \(TLS\) connection\. Squid uses a feature called [SslPeekAndSplice](https://wiki.squid-cache.org/Features/SslPeekAndSplice) to retrieve the Server Name Indication \(SNI\) from the TLS initiation that contains the requested internet host\. This is required so Squid does not need to unencrypt HTTPS traffic\. To enable SslPeekAndSplice, Squid requires a certificate\. Create this certificate using OpenSSL: - -``` -sudo mkdir /etc/squid/ssl -cd /etc/squid/ssl -sudo openssl genrsa -out squid.key 2048 -sudo openssl req -new -key squid.key -out squid.csr -subj "/C=XX/ST=XX/L=squid/O=squid/CN=squid" -sudo openssl x509 -req -days 3650 -in squid.csr -signkey squid.key -out squid.crt -sudo cat squid.key squid.crt | sudo tee squid.pem -``` - -**Note** - For HTTP, Squid does not require configuration\. From all HTTP/1\.1 request messages, it can retrieve the host header field, which specifies the internet host that is being requested\. - -## Run CodeBuild in an explicit proxy server - -**Topics** -+ [Configure Squid as an explicit proxy server](#use-proxy-server-explicit-squid-configure) -+ [Create a CodeBuild project](#use-proxy-server-explicit-create-acb-project) -+ [Explicit proxy server sample `squid.conf` file](#use-proxy-server-explicit-sample-squid-conf) - - To run AWS CodeBuild in an explicit proxy server, you must configure the proxy server to allow or deny traffic to and from external sites, and then configure the `HTTP_PROXY` and `HTTPS_PROXY` environment variables\. - -### Configure Squid as an explicit proxy server - - To configure the Squid proxy server to be explicit, you must make the following modifications to its `/etc/squid/squid.conf` file: -+ Remove the following default access control list \(ACL\) rules\. - - ``` - acl localnet src 10.0.0.0/8 - acl localnet src 172.16.0.0/12 - acl localnet src 192.168.0.0/16 - acl localnet src fc00::/7 - acl localnet src fe80::/10 - ``` - - Add the following in place of the default ACL rules you removed\. The first line allows requests from your VPC\. The next two lines grant your proxy server access to destination URLs that might be used by AWS CodeBuild\. Edit the regular expression in the last line to specify S3 buckets or a CodeCommit repository in an AWS Region\. For example: - + If your source is Amazon S3, use the command acl download\_src dstdom\_regex \.\*s3\\\.us\-west\-1\\\.amazonaws\\\.comto grant access to S3 buckets in the `us-west-1` Region\. - + If your source is AWS CodeCommit, use `git-codecommit..amazonaws.com` to add an AWS Region to an allow list\. - - ``` - acl localnet src 10.1.0.0/16 #Only allow requests from within the VPC - 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 download_src dstdom_regex .*\.amazonaws\.com #Allows to download source from Amazon S3 or CodeCommit - ``` -+ Replace `http_access allow localnet` with the following: - - ``` - http_access allow localnet allowed_sites - http_access allow localnet download_src - ``` -+ If you want your build to upload logs and artifacts, do one of the following: - - 1. Before the `http_access deny all` statement, insert the following statements\. They allow CodeBuild to access CloudWatch and Amazon S3\. Access to CloudWatch is required so that CodeBuild can create CloudWatch logs\. Access to Amazon S3 is required for uploading artifacts and Amazon S3 caching\. - + - - ``` - https_port 3130 cert=/etc/squid/ssl/squid.pem ssl-bump intercept - acl SSL_port port 443 - http_access allow SSL_port - acl allowed_https_sites ssl::server_name .amazonaws.com - acl step1 at_step SslBump1 - acl step2 at_step SslBump2 - acl step3 at_step SslBump3 - ssl_bump peek step1 all - ssl_bump peek step2 allowed_https_sites - ssl_bump splice step3 allowed_https_sites - ssl_bump terminate step2 all - ``` - + After you save `squid.conf`, run the following command: - - ``` - sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3130 - sudo service squid restart - ``` - - 1. Add `proxy` to your buildspec file\. For more information, see [Buildspec syntax](build-spec-ref.md#build-spec-ref-syntax)\. - - ``` - version: 0.2 - proxy: - upload-artifacts: yes - logs: yes - phases: - build: - commands: - - command - ``` - -**Note** -If you receive a RequestError timeout error, see [ RequestError timeout error when running CodeBuild in a proxy server](troubleshooting.md#code-request-timeout-error)\. - -For more information, see [Explicit proxy server sample `squid.conf` file](#use-proxy-server-explicit-sample-squid-conf) later in this topic\. - -### 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)\. - - Use the following command to view the Squid proxy access log: - -``` -sudo tail -f /var/log/squid/access.log -``` - -### Explicit proxy server sample `squid.conf` file - - The following is an example of a `squid.conf` file that is configured for an explicit proxy server\. - -``` - 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 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 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 - acl Safe_ports port 21 # ftp - acl Safe_ports port 443 # https - acl Safe_ports port 70 # gopher - acl Safe_ports port 210 # wais - acl Safe_ports port 1025-65535 # unregistered ports - acl Safe_ports port 280 # http-mgmt - acl Safe_ports port 488 # gss-http - acl Safe_ports port 591 # filemaker - acl Safe_ports port 777 # multiling http - acl CONNECT method CONNECT - # - # Recommended minimum Access Permission configuration: - # - # Deny requests to certain unsafe ports - http_access deny !Safe_ports - # Deny CONNECT to other than secure SSL ports - http_access deny CONNECT !SSL_ports - # Only allow cachemgr access from localhost - http_access allow localhost manager - http_access deny manager - # We strongly recommend the following be uncommented to protect innocent - # web applications running on the proxy server who think the only - # one who can access services on "localhost" is a local user - #http_access deny to_localhost - # - # INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS - # - # Example rule allowing access from your local networks. - # Adapt localnet in the ACL section to list your (internal) IP networks - # from where browsing should be allowed - http_access allow localnet allowed_sites - http_access allow localnet download_src - http_access allow localhost - # Add this for CodeBuild to access CWL end point, caching and upload artifacts S3 bucket end point - https_port 3130 cert=/etc/squid/ssl/squid.pem ssl-bump intercept - acl SSL_port port 443 - http_access allow SSL_port - acl allowed_https_sites ssl::server_name .amazonaws.com - acl step1 at_step SslBump1 - acl step2 at_step SslBump2 - acl step3 at_step SslBump3 - ssl_bump peek step1 all - ssl_bump peek step2 allowed_https_sites - ssl_bump splice step3 allowed_https_sites - ssl_bump terminate step2 all - # And finally deny all other access to this proxy - http_access deny all - # Squid normally listens to port 3128 - http_port 3128 - # Uncomment and adjust the following to add a disk cache directory. - #cache_dir ufs /var/spool/squid 100 16 256 - # Leave coredumps in the first cache dir - coredump_dir /var/spool/squid - # - # Add any of your own refresh_pattern entries above these. - # - refresh_pattern ^ftp: 1440 20% 10080 - refresh_pattern ^gopher: 1440 0% 1440 - refresh_pattern -i (/cgi-bin/|\?) 0 0% 0 - refresh_pattern . 0 20% 4320 -``` - -## Run CodeBuild in a transparent proxy server - - To run AWS CodeBuild in a transparent proxy server, you must configure the proxy server with access to the websites and domains it interacts with\. - -### Configure Squid as a transparent proxy server - - To configure a proxy server to be transparent, you must grant it access to the domains and websites you want it to access\. To run AWS CodeBuild with a transparent proxy server, you must grant it access to `amazonaws.com`\. You must also grant access to other websites CodeBuild uses\. These vary, depending on how you create your CodeBuild projects\. Example websites are those for repositories such as GitHub, Bitbucket, Yum, and Maven\. To grant Squid access to specific domains and websites, use a command similar to the following to update the `squid.conf` file\. This sample command grants access to `amazonaws.com`, `github.com`, and `bitbucket.com`\. You can edit this sample to grant access to other websites\. - -``` -cat | sudo tee /etc/squid/squid.conf ≪EOF -visible_hostname squid -#Handling HTTP requests -http_port 3129 intercept -acl allowed_http_sites dstdomain .amazonaws.com -#acl allowed_http_sites dstdomain domain_name [uncomment this line to add another domain] -http_access allow allowed_http_sites -#Handling HTTPS requests -https_port 3130 cert=/etc/squid/ssl/squid.pem ssl-bump intercept -acl SSL_port port 443 -http_access allow SSL_port -acl allowed_https_sites ssl::server_name .amazonaws.com -acl allowed_https_sites ssl::server_name .github.amrom.workers.dev -acl allowed_https_sites ssl::server_name .bitbucket.com -#acl allowed_https_sites ssl::server_name [uncomment this line to add another website] -acl step1 at_step SslBump1 -acl step2 at_step SslBump2 -acl step3 at_step SslBump3 -ssl_bump peek step1 all -ssl_bump peek step2 allowed_https_sites -ssl_bump splice step3 allowed_https_sites -ssl_bump terminate step2 all -http_access deny all -EOF -``` - - Incoming requests from instances in the private subnet must redirect to the Squid ports\. Squid listens on port 3129 for HTTP traffic \(instead of 80\) and 3130 for HTTPS traffic \(instead of 443\)\. Use the iptables command to route traffic: - -``` -sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3129 -sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 3130 -sudo service iptables save -sudo service squid start -``` - -### Create a CodeBuild project - - After you configure your proxy server, you can use it with AWS CodeBuild in a private subnet without more configuration\. Every HTTP and HTTPS request goes through the public proxy server\. Use the following command to view the Squid proxy access log: - -``` -sudo tail -f /var/log/squid/access.log -``` - -## Run a package manager and other tools 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\. - -1. Add a line to your buildspec file that points to the private endpoint of your proxy server\. - - The following examples demonstrate how to do this for `apt-get`, `curl`, and `maven`\. If you use a different tool, the same principles apply\. Add it to an allow list in the `squid.conf` file and add a command to your buildspec file to make CodeBuild aware of your proxy server's endpoint\. - -**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 run 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 - ``` - -1. Add the following statement in your buildspec file so that `apt-get` commands look for the proxy configuration in `/etc/apt/apt.conf.d/00proxy`\. - - ``` - echo 'Acquire::http::Proxy "http://:3128"; Acquire::https::Proxy "http://:3128"; Acquire::ftp::Proxy "http://:3128";' > /etc/apt/apt.conf.d/00proxy - ``` - -**To run `curl` in a proxy server** - -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 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 - ``` - -1. Add the following statement in your buildspec file so `curl` uses the private proxy server to access the website you added to the `squid.conf`\. In this example, the website is `google.com`\. - - ``` - curl -x :3128 https://www.google.com - ``` - -**To run `maven` in a proxy server** - -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 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 - ``` - -1. Add the following statement to your buildspec file\. - - ``` - maven clean install -DproxySet=true -DproxyHost= -DproxyPort=3128 - ``` \ No newline at end of file diff --git a/doc_source/use-vpc-endpoints-with-codebuild.md b/doc_source/use-vpc-endpoints-with-codebuild.md deleted file mode 100644 index 7fefd42..0000000 --- a/doc_source/use-vpc-endpoints-with-codebuild.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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 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 - - Before you configure VPC endpoints for AWS CodeBuild, be aware of the following restrictions and limitations\. - -**Note** - Use a [NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_NAT_Instance.html) if you want to use CodeBuild with AWS services that do not support Amazon VPC PrivateLink connections\. -+ VPC endpoints support Amazon\-provided DNS through Amazon Route 53 only\. If you want to use your own DNS, you can use conditional DNS forwarding\. For more information, see [DHCP option sets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_DHCP_Options.html) in the *Amazon VPC User Guide*\. -+ VPC endpoints currently do not support cross\-Region requests\. Make sure that you create your endpoint in the same AWS Region as any S3 buckets that store your build input and output\. You can use the Amazon S3 console or the [get\-bucket\-location](https://docs.aws.amazon.com/cli/latest/reference/s3api/get-bucket-location.html) command to find the location of your bucket\. Use a Region\-specific Amazon S3 endpoint to access your bucket \(for example, `mybucket.s3-us-west-2.amazonaws.com`\)\. For more information about Region\-specific endpoints for Amazon S3, see [Amazon Simple Storage Service](https://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) in the *Amazon Web Services General Reference*\. If you use the AWS CLI to make requests to Amazon S3, set your default Region to the same Region where your bucket was created, or use the `--region` parameter in your requests\. - -## Creating VPC endpoints for CodeBuild - -Follow the instructions in [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) to create the endpoint `com.amazonaws.region.codebuild`\. This is a VPC endpoint for AWS CodeBuild\. - -![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/vpc-endpoint.png)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/)![\[Image NOT FOUND\]](http://docs.aws.amazon.com/codebuild/latest/userguide/) - - *region* represents the region identifier for an AWS Region supported by CodeBuild, such as `us-east-2` for the US East \(Ohio\) Region\. For a list of supported AWS Regions, see [CodeBuild](https://docs.aws.amazon.com/general/latest/gr/rande.html#codebuild_region) in the * AWS General Reference*\. The endpoint is prepopulated with the Region you specified when you signed in to AWS\. If you change your Region, the VPC endpoint is updated accordingly\. - -## Create a VPC endpoint policy for CodeBuild - - You can create a policy for Amazon VPC endpoints for AWS CodeBuild in which you can specify: -+ The principal that can perform actions\. -+ The actions that can be performed\. -+ The resources that can have actions performed on them\. - -The following example policy specifies that all principals can only start and view builds for the `project-name` project\. - -``` -{ - "Statement": [ - { - "Action": [ - "codebuild:ListBuildsForProject", - "codebuild:StartBuild", - "codebuild:BatchGetBuilds" - ], - "Effect": "Allow", - "Resource": "arn:aws:codebuild:region-ID:account-ID:project/project-name", - "Principal": "*" - } - ] -} -``` - - For more information, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html) in the *Amazon VPC User Guide*\. \ No newline at end of file diff --git a/doc_source/view-build-details.md b/doc_source/view-build-details.md deleted file mode 100644 index 5305ff6..0000000 --- a/doc_source/view-build-details.md +++ /dev/null @@ -1,59 +0,0 @@ -# View build details in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view details about builds managed by CodeBuild\. - -**Topics** -+ [View build details \(console\)](#view-build-details-console) -+ [View build details \(AWS CLI\)](#view-build-details-cli) -+ [View build details \(AWS SDKs\)](#view-build-details-sdks) -+ [Build phase transitions](#view-build-details-phases) - -## View build details \(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: - + In the navigation pane, choose **Build history**\. In the list of builds, in the **Build run** column, choose the link for the build\. - + In the navigation pane, choose **Build projects**\. In the list of build projects, in the **Name** column, choose the link for the name of the build project\. Then, in the list of builds, in the **Build run** column, choose the link for the build\. -**Note** -By default, only the 10 most recent 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\. - -## View build details \(AWS CLI\) - -For more information about using the AWS CLI with AWS CodeBuild, see the [Command line reference](cmd-ref.md)\. - -Run the batch\-get\-builds command: - -``` -aws codebuild batch-get-builds --ids ids -``` - -Replace the following placeholder: -+ *ids*: Required string\. One or more build IDs to view details about\. To specify more than one build ID, separate each build ID with a space\. You can specify up to 100 build IDs\. 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 build IDs for a build project \(AWS CLI\)](view-builds-for-project.md#view-builds-for-project-cli) - -For example, if you run this command: - -``` -aws codebuild batch-get-builds --ids codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE my-other-project:813bb6c6-891b-426a-9dd7-6d8a3EXAMPLE -``` - -If the command is successful, data similar to that described in [To view summarized build information ](getting-started-cli-monitor-build.md#getting-started-cli-monitor-build-cli) appears in the output\. - -## View build details \(AWS SDKs\) - -For more information about using AWS CodeBuild with the AWS SDKs, see the [AWS SDKs and tools reference](sdk-ref.md)\. - -## Build phase transitions - -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 deleted file mode 100644 index 5d862f1..0000000 --- a/doc_source/view-build-list.md +++ /dev/null @@ -1,125 +0,0 @@ -# View a list of build IDs in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build IDs for builds managed by CodeBuild\. - -**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\) - -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 history**\. -**Note** -By default, only the 10 most recent builds are displayed\. To view more builds, choose the gear icon, and then choose a different value for **Builds per page** or use the back and forward arrows\. - -## View a list of 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\-builds command: - - ``` - aws codebuild list-builds --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 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-builds --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-builds --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 ... - "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 ... - "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE" - ] - } - ``` - -## View a list of build IDs \(AWS SDKs\) - -For more 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/view-builds-for-project.md b/doc_source/view-builds-for-project.md deleted file mode 100644 index 13502f2..0000000 --- a/doc_source/view-builds-for-project.md +++ /dev/null @@ -1,130 +0,0 @@ -# View a list of build IDs for a build project in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build IDs for a build project in CodeBuild\. - -**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\) - -1. Open the CodeBuild console at [https://console\.aws\.amazon\.com/codebuild/](https://console.aws.amazon.com/codebuild/)\. - -1. In the navigation pane, choose **Build projects**\. In the list of build projects, in the **Name** column, choose the build project\. - -**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\. - -## View a list of 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\-builds\-for\-project command, as follows: - -``` -aws codebuild list-builds-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-builds-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-builds-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 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 deleted file mode 100644 index f25e255..0000000 --- a/doc_source/view-project-details.md +++ /dev/null @@ -1,112 +0,0 @@ -# View a build project's details in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view the details of a build project in CodeBuild\. - -**Topics** -+ [View a build project's details \(console\)](#view-project-details-console) -+ [View a build project's details \(AWS CLI\)](#view-project-details-cli) -+ [View a build project's details \(AWS SDKs\)](#view-project-details-sdks) - -## View a build project's details \(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**\. -**Note** -By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. - -1. In the list of build projects, in the **Name** column, choose the link for the build project\. - -1. On the **Build project: *project\-name*** page, choose **Build details**\. - -## View a build project's details \(AWS CLI\) - - - -Run the batch\-get\-projects command: - -``` -aws codebuild batch-get-projects --names names -``` - -In the preceding command, replace the following placeholder: -+ *names*: Required string used to indicate one or more build project names to view details about\. To specify more than one build project, separate each build project's name with a space\. You can specify up to 100 build project names\. 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)\. - -For example, if you run this command: - -``` -aws codebuild batch-get-projects --names codebuild-demo-project codebuild-demo-project2 my-other-demo-project -``` - -A result similar to the following might appear in the output\. Ellipses \(`...`\) are used to represent data omitted for brevity\. - -``` -{ - "projectsNotFound": [ - "my-other-demo-project" - ], - "projects": [ - { - ... - "name": codebuild-demo-project, - ... - }, - { - ... - "name": codebuild-demo-project2", - ... - } - ] -} -``` - -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\) - -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-list.md b/doc_source/view-project-list.md deleted file mode 100644 index 3e37872..0000000 --- a/doc_source/view-project-list.md +++ /dev/null @@ -1,77 +0,0 @@ -# View a list of build project names in AWS CodeBuild - -You can use the AWS CodeBuild console, AWS CLI, or AWS SDKs to view a list of build projects in CodeBuild\. - -**Topics** -+ [View a list of build project names \(console\)](#view-project-list-console) -+ [View a list of build project names \(AWS CLI\)](#view-project-list-cli) -+ [View a list of build project names \(AWS SDKs\)](#view-project-list-sdks) - -## View a list of build project names \(console\) - -You can view a list of build projects in an AWS Region in the console\. Information includes the name, source provider, repository, latest build status, and description, if any\. - -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**\. -**Note** -By default, only the 10 most recent build projects are displayed\. To view more build projects, choose the gear icon, and then choose a different value for **Projects per page** or use the back and forward arrows\. - -## View a list of build project names \(AWS CLI\) - -Run the list\-projects command: - -``` -aws codebuild list-projects --sort-by sort-by --sort-order sort-order --next-token next-token -``` - -In the preceding command, replace the following placeholders: -+ *sort\-by*: Optional string used to indicate the criterion to be used to list build project names\. Valid values include: - + `CREATED_TIME`: List the build project names based on when each build project was created\. - + `LAST_MODIFIED_TIME`: List the build project names based on when information about each build project was last changed\. - + `NAME`: List the build project names based on each build project's name\. -+ *sort\-order*: Optional string used to indicate the order in which to list build projects, based on *sort\-by*\. 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-projects --sort-by NAME --sort-order ASCENDING -``` - -A result similar to the following might appear in the output: - -``` -{ - "nextToken": "Ci33ACF6...The full token has been omitted for brevity...U+AkMx8=", - "projects": [ - "codebuild-demo-project", - "codebuild-demo-project2", - ... The full list of build project names has been omitted for brevity ... - "codebuild-demo-project99" - ] -} -``` - -If you run this command again: - -``` -aws codebuild list-projects --sort-by NAME --sort-order ASCENDING --next-token Ci33ACF6...The full token has been omitted for brevity...U+AkMx8= -``` - -A result similar to the following might appear in the output: - -``` -{ - "projects": [ - "codebuild-demo-project100", - "codebuild-demo-project101", - ... The full list of build project names has been omitted for brevity ... - "codebuild-demo-project122" - ] -} -``` - -## View a list of build project names \(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/vpc-support.md b/doc_source/vpc-support.md deleted file mode 100644 index 09024d3..0000000 --- a/doc_source/vpc-support.md +++ /dev/null @@ -1,105 +0,0 @@ -# Use AWS CodeBuild with Amazon Virtual Private Cloud - -Typically, AWS CodeBuild cannot access resources in a VPC\. To enable access, you must provide additional VPC\-specific configuration information in your CodeBuild project configuration\. This includes the VPC ID, the VPC subnet IDs, and the VPC security group IDs\. VPC\-enabled builds can then access resources inside your VPC\. For more information about setting up a VPC in Amazon VPC, see the [Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. - -**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) -+ [Best practices for VPCs](#best-practices-for-vpcs) -+ [Troubleshooting your VPC setup](#troubleshooting-vpc) -+ [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 cases - -VPC connectivity from AWS CodeBuild builds makes it possible to: -+ Run integration tests from your build against data in an Amazon RDS database that's isolated on a private subnet\. -+ Query data in an Amazon ElastiCache cluster directly from tests\. -+ Interact with internal web services hosted on Amazon EC2, Amazon ECS, or services that use internal Elastic Load Balancing\. -+ Retrieve dependencies from self\-hosted, internal artifact repositories, such as PyPI for Python, Maven for Java, and npm for Node\.js\. -+ Access objects in an S3 bucket configured to allow access through an Amazon VPC endpoint only\. -+ Query external web services that require fixed IP addresses through the Elastic IP address of the NAT gateway or NAT instance associated with your subnet\. - -Your builds can access any resource that's hosted in your VPC\. - -## Allowing Amazon VPC access in your CodeBuild projects - -Include these settings in your VPC configuration: -+ For **VPC ID**, choose the VPC ID that CodeBuild uses\. -+ 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*\. -+ *vpcId*: Required\. The VPC ID that CodeBuild uses\. Run this command to get a list of all Amazon VPC IDs in your Region: - - ``` - aws ec2 describe-vpcs - ``` -+ *subnets*: Required\. The subnet IDs that include resources used by CodeBuild\. Run this command obtain these IDs: - - ``` - aws ec2 describe-subnets --filters "Name=vpc-id,Values=" --region us-east-1 - ``` -**Note** -Replace `us-east-1` with your Region\. -+ *securityGroupIds*: Required\. The security group IDs used by CodeBuild to allow access to resources in the VPCs\. Run this command to obtain these IDs: - - ``` - aws ec2 describe-security-groups --filters "Name=vpc-id,Values=" --region us-east-1 - ``` -**Note** -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\. 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 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\. - - For more information, see [Security groups rules](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules) in the *Amazon VPC User Guide*\. -+ Set up separate subnets for your builds\. -+ When you set up your CodeBuild projects to access your VPC, choose private subnets only\. - -For more information about setting up a VPC in Amazon VPC, see the [Amazon VPC User Guide](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Introduction.html)\. - -For more information about using AWS CloudFormation to configure a VPC to use the CodeBuild VPC feature, see the [AWS CloudFormation VPC template](cloudformation-vpc-template.md)\. - -## Troubleshooting your VPC setup - -Use the information that appears in the error message to help you identify, diagnose, and address issues\. - -The following are some guidelines to assist you when troubleshooting a common CodeBuild VPC error: `Build does not have internet connectivity. Please check subnet network configuration`\. - -1. [Make sure that your internet gateway is attached to VPC](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html#Add_IGW_Attach_Gateway)\. - -1. [Make sure that the route table for your public subnet points to the internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#route-tables-internet-gateway)\. - -1. [Make sure that your network ACLs allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. - -1. [Make sure that your security groups allow traffic to flow](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#SecurityGroupRules)\. - -1. [Troubleshoot your NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC-nat-gateway.html#nat-gateway-troubleshooting)\. - -1. [Make sure that the route table for private subnets points to the NAT gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html#route-tables-nat)\. - -1. Make sure that the service role used by CodeBuild to interact with services on behalf of the IAM user has the permissions in [ this policy](https://docs.aws.amazon.com/codebuild/latest/userguide/auth-and-access-control-iam-identity-based-access-control.html#customer-managed-policies-example-create-vpc-network-interface)\. For more information, see [Create a CodeBuild service role](setting-up.md#setting-up-service-role)\. - - If CodeBuild is missing permissions, you might receive an error that says, `Unexpected EC2 error: UnauthorizedOperation`\. This error can occur if CodeBuild does not have the Amazon EC2 permissions required to work with a VPC\. \ No newline at end of file diff --git a/doc_source/webhooks.md b/doc_source/webhooks.md deleted file mode 100644 index ce0752b..0000000 --- a/doc_source/webhooks.md +++ /dev/null @@ -1,24 +0,0 @@ -# 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 deleted file mode 100644 index d9b2e98..0000000 --- a/doc_source/welcome.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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/)\. - -## 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 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)\. - -## Pricing for CodeBuild - -For information, see [CodeBuild pricing](https://aws.amazon.com/codebuild/pricing)\. - -## How do I get started with CodeBuild? - -We recommend that you complete the following steps: - -1. **Learn** more about CodeBuild by reading the information in [Concepts](concepts.md)\. - -1. **Experiment** with CodeBuild in an example scenario by following the instructions in [Getting started using the console](getting-started.md)\. - -1. **Use** CodeBuild in your own scenarios by following the instructions in [Plan a build](planning.md)\. \ No newline at end of file diff --git a/doc_source/working-with-build-projects.md b/doc_source/working-with-build-projects.md deleted file mode 100644 index 21a1fb5..0000000 --- a/doc_source/working-with-build-projects.md +++ /dev/null @@ -1,21 +0,0 @@ -# Working with build projects - -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\. - -You can perform these tasks when working with build projects: - -**Topics** -+ [Create a build project in AWS CodeBuild](create-project.md) -+ [Create a notification rule](notification-rule-create.md) -+ [View a list of build project names in AWS CodeBuild](view-project-list.md) -+ [View a build project's details in AWS CodeBuild](view-project-details.md) -+ [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) -+ [Batch builds in AWS CodeBuild](batch-build.md) -+ [Public build projects in AWS CodeBuild](public-builds.md) \ No newline at end of file