AWS CodeBuild build and test action reference (original) (raw)

Allows you to run builds and tests as part of your pipeline. When you run a CodeBuild build or test action, commands specified in the buildspec are run inside of a CodeBuild container. All artifacts that are specified as input artifacts to a CodeBuild action are available inside of the container running the commands. CodeBuild can provide either a build or test action. For more information, see the AWS CodeBuild User Guide.

When you use the CodePipeline wizard in the console to create a build project, the CodeBuild build project shows the source provider is CodePipeline. When you create a build project in the CodeBuild console, you cannot specify CodePipeline as the source provider, but adding the build action to your pipeline adjusts the source in the CodeBuild console. For more information, see ProjectSource in the AWS CodeBuild API Reference.

Topics

Action type

Configuration parameters

ProjectName

Required: Yes

ProjectName is the name of the build project in CodeBuild.

PrimarySource

Required: Conditional

The value of the PrimarySource parameter must be the name of one of the input artifacts to the action. CodeBuild looks for the buildspec file and runs the buildspec commands in the directory that contains the unzipped version of this artifact.

This parameter is required if multiple input artifacts are specified for a CodeBuild action. When there is only one source artifact for the action, thePrimarySource artifact defaults to that artifact.

BatchEnabled

Required: No

The Boolean value of the BatchEnabled parameter allows the action to run multiple builds in the same build execution.

When this option is enabled, the CombineArtifacts option is available.

For pipeline examples with batch builds enabled, see CodePipeline integration with CodeBuild and batch builds.

BuildspecOverride

Required: No

An inline buildspec definition or buildspec file declaration that overrides the latest one defined in the build project, for this build only. The buildspec defined on the project is not changed.

If this value is set, it can be one of the following:

Note

Since this property allows you to change the build commands that will run in the container, you should note that an IAM principal with the ability to call this API and set this parameter can override the default settings. Moreover, we encourage that you use a trustworthy buildspec location like a file in your source repository or a Amazon S3 bucket.

CombineArtifacts

Required: No

The Boolean value of the CombineArtifacts parameter combines all build artifacts from a batch build into a single artifact file for the build action.

To use this option, the BatchEnabled parameter must be enabled.

EnvironmentVariables

Required: No

The value of this parameter is used to set environment variables for the CodeBuild action in your pipeline. The value for theEnvironmentVariables parameter takes the form of a JSON array of environment variable objects. See the example parameter in Action declaration (CodeBuild example).

Each object has three parts, all of which are strings:

Note

We strongly discourage the use of environment variables to store sensitive values, especially AWS credentials. When you use the CodeBuild console or AWS CLI, environment variables are displayed in plain text. For sensitive values, we recommend that you use the SECRETS_MANAGER type instead.

Note

When you enter the name, value, andtype for your environment variables configuration, especially if the environment variable contains CodePipeline output variable syntax, do not exceed the 1000-character limit for the configuration’s value field. A validation error is returned when this limit is exceeded.

For more information, see EnvironmentVariable in the AWS CodeBuild API Reference. For an example CodeBuild action with an environment variable that resolves to the GitHub branch name, see Example: Use a BranchName variable with CodeBuild environment variables.

Input artifacts

Note

The artifact configured in your CodeBuild project becomes the input artifact used by the CodeBuild action in your pipeline.

Output artifacts

Note

The artifact configured in your CodeBuild project becomes the CodePipeline input artifact in your pipeline action.
If the CombineArtifacts parameter is selected for batch builds, the output artifact location contains the combined artifacts from multiple builds that were run in the same execution.

Output variables

This action will produce as variables all environment variables that were exported as part of the build. For more details on how to export environment variables, see EnvironmentVariable in the_AWS CodeBuild API Guide_.

For more information about using CodeBuild environment variables in CodePipeline, see the examples in CodeBuild action output variables. For a list of the environment variables you can use in CodeBuild, see Environment variables in build environments in the AWS CodeBuild User Guide.

Service role permissions: CodeBuild action

For CodeBuild support, add the following to your policy statement:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "codebuild:BatchGetBuilds",
        "codebuild:StartBuild",
        "codebuild:BatchGetBuildBatches",
        "codebuild:StartBuildBatch"
      ],
      "Resource": [
        "arn:aws:codebuild:*:{{customerAccountId}}:project/[[ProjectName]]"
      ],
      "Effect": "Allow"
    }
  ]
}

Action declaration (CodeBuild example)

YAML

Name: Build
Actions:
  - Name: PackageExport
    ActionTypeId:
      Category: Build
      Owner: AWS
      Provider: CodeBuild
      Version: '1'
    RunOrder: 1
    Configuration:
      BatchEnabled: 'true'
      CombineArtifacts: 'true'
      ProjectName: my-build-project
      PrimarySource: MyApplicationSource1
      EnvironmentVariables: '[{"name":"TEST_VARIABLE","value":"TEST_VALUE","type":"PLAINTEXT"},{"name":"ParamStoreTest","value":"PARAMETER_NAME","type":"PARAMETER_STORE"}]'
    OutputArtifacts:
      - Name: MyPipeline-BuildArtifact
    InputArtifacts:
      - Name: MyApplicationSource1
      - Name: MyApplicationSource2

JSON

{
    "Name": "Build",
    "Actions": [
        {
            "Name": "PackageExport",
            "ActionTypeId": {
                "Category": "Build",
                "Owner": "AWS",
                "Provider": "CodeBuild",
                "Version": "1"
            },
            "RunOrder": 1,
            "Configuration": {
                "BatchEnabled": "true",
                "CombineArtifacts": "true",
                "ProjectName": "my-build-project",
                "PrimarySource": "MyApplicationSource1",
                "EnvironmentVariables": "[{\"name\":\"TEST_VARIABLE\",\"value\":\"TEST_VALUE\",\"type\":\"PLAINTEXT\"},{\"name\":\"ParamStoreTest\",\"value\":\"PARAMETER_NAME\",\"type\":\"PARAMETER_STORE\"}]"
            },
            "OutputArtifacts": [
                {
                    "Name": "MyPipeline-BuildArtifact"
                }
            ],
            "InputArtifacts": [
                {
                    "Name": "MyApplicationSource1"
                },
                {
                    "Name": "MyApplicationSource2"
                }
            ]
        }
    ]
}

See also

The following related resources can help you as you work with this action.