Create the JSON file Fill in the JSON file Create the project

Create a build project (AWS CLI)

For more information about using the AWS CLI with CodeBuild, see the Command line reference.

To create a CodeBuild build project using the AWS CLI, you create a JSON-formatted Project structure, fill in the structure, and call the create-project command to create the project.

Create the JSON file

Create a skeleton JSON file with the create-project command, using the --generate-cli-skeleton option:


aws codebuild create-project --generate-cli-skeleton > <json-file>

This creates a JSON file with the path and file name specified by <json-file>.

Fill in the JSON file

Modify the JSON data as follows and save your results.


{
  "name": "<project-name>",
  "description": "<description>",
  "source": {
    "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "BITBUCKET" | "S3" | "NO_SOURCE",
    "location": "<source-location>",
    "gitCloneDepth": "<git-clone-depth>",
    "buildspec": "<buildspec>",
    "InsecureSsl": "<insecure-ssl>",
    "reportBuildStatus": "<report-build-status>",
    "buildStatusConfig": {
      "context": "<context>",
      "targetUrl": "<target-url>"
    },
    "gitSubmodulesConfig": {
      "fetchSubmodules": "<fetch-submodules>"
    },
    "auth": {
      "type": "<auth-type>",
      "resource": "<auth-resource>"
    },
    "sourceIdentifier": "<source-identifier>"
  },
  "secondarySources": [
    {
        "type": "CODECOMMIT" | "CODEPIPELINE" | "GITHUB" | "GITHUB_ENTERPRISE" | "BITBUCKET" | "S3" | "NO_SOURCE",
        "location": "<source-location>",
        "gitCloneDepth": "<git-clone-depth>",
        "buildspec": "<buildspec>",
        "InsecureSsl": "<insecure-ssl>",
        "reportBuildStatus": "<report-build-status>",
        "auth": {
          "type": "<auth-type>",
          "resource": "<auth-resource>"
        },
        "sourceIdentifier": "<source-identifier>"
    }
  ],
  "secondarySourceVersions": [
    {
      "sourceIdentifier": "<secondary-source-identifier>",
      "sourceVersion": "<secondary-source-version>"
    }
  ],
  "sourceVersion": "<source-version>",
  "artifacts": {
    "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS",
    "location": "<artifacts-location>",
    "path": "<artifacts-path>",
    "namespaceType": "<artifacts-namespacetype>",
    "name": "<artifacts-name>",
    "overrideArtifactName": "<override-artifact-name>",
    "packaging": "<artifacts-packaging>"
  },
  "secondaryArtifacts": [
    {
      "type": "CODEPIPELINE" | "S3" | "NO_ARTIFACTS",
      "location": "<secondary-artifact-location>",
      "path": "<secondary-artifact-path>",
      "namespaceType": "<secondary-artifact-namespaceType>",
      "name": "<secondary-artifact-name>",
      "packaging": "<secondary-artifact-packaging>",
      "artifactIdentifier": "<secondary-artifact-identifier>"
    }
  ],
  "cache": {
    "type": "<cache-type>",
    "location": "<cache-location>",
    "mode": [
      "<cache-mode>"
    ]
  },
  "environment": {
    "type": "LINUX_CONTAINER" | "LINUX_GPU_CONTAINER" | "ARM_CONTAINER" | "WINDOWS_SERVER_2019_CONTAINER",
    "image": "<image>",
    "computeType": "BUILD_GENERAL1_SMALL" | "BUILD_GENERAL1_MEDIUM" | "BUILD_GENERAL1_LARGE" | "BUILD_GENERAL1_2XLARGE",
    "certificate": "<certificate>",
    "environmentVariables": [
      {
        "name": "<environmentVariable-name>",
        "value": "<environmentVariable-value>",
        "type": "<environmentVariable-type>"
      }
    ],
    "registryCredential": [
      {
        "credential": "<credential-arn-or-name>",
        "credentialProvider": "<credential-provider>"
      }
    ],
    "imagePullCredentialsType": "CODEBUILD" | "SERVICE_ROLE",
    "privilegedMode": "<privileged-mode>"
  },
  "serviceRole": "<service-role>",
  "timeoutInMinutes": <timeout>,
  "queuedTimeoutInMinutes": <queued-timeout>,
  "encryptionKey": "<encryption-key>",
  "tags": [
    {
      "key": "<tag-key>",
      "value": "<tag-value>"
    }
  ],
  "vpcConfig": {
    "securityGroupIds": [
         "<security-group-id>"
    ],
    "subnets": [
         "<subnet-id>"
    ],
    "vpcId": "<vpc-id>"
  },
  "badgeEnabled": "<badge-enabled>",
  "logsConfig": {
    "cloudWatchLogs": {
      "status": "<cloudwatch-logs-status>",
      "groupName": "<group-name>",
      "streamName": "<stream-name>"
    },
    "s3Logs": {
      "status": "<s3-logs-status>",
      "location": "<s3-logs-location>",
      "encryptionDisabled": "<s3-logs-encryption-disabled>"
    }
  },
  "fileSystemLocations": [
    {
      "type": "EFS",
      "location": "<EFS-DNS-name-1>:/<directory-path>",
      "mountPoint": "<mount-point>",
      "identifier": "<efs-identifier>",
      "mountOptions": "<efs-mount-options>"
    }
  ],
  "buildBatchConfig": {
    "serviceRole": "<batch-service-role>",
    "combineArtifacts": <combine-artifacts>,
    "restrictions": {
      "maximumBuildsAllowed": <max-builds>,
      "computeTypesAllowed": [
        "<compute-type>"
      ]
    },
    "timeoutInMins": <batch-timeout>,
    "batchReportMode": "REPORT_AGGREGATED_BATCH" | "REPORT_INDIVIDUAL_BUILDS"
  },
  "concurrentBuildLimit": <concurrent-build-limit>
}

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 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. 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.

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 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: <bucket-name>/<object-name>.zip.
- For a ZIP file located in a subfolder in the input bucket: <bucket-name>/<subfoler-path>/<object-name>.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 .
2. 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.
2. 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 on the GitHub Help website.
3. When you use the console to create your CodeBuild project, in Source, for Source provider, choose GitHub Enterprise.
4. 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.

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.

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/<path to build> 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/<path to build>?region=$AWS_REGION"

If the build region is us-east-2, this will expand to:


https://aws.amazon.com/codebuild/<path to build>?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 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 object. In a secondary source object, the sourceIdentifier is required.

secondarySourceVersions

Optional. An array of ProjectSourceVersion 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.

artifacts

Required. A ProjectArtifacts 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. These settings include the following:

artifacts/type

Required. The type of build output artifact. Valid values are:

CODEPIPELINE
NO_ARTIFACTS
S3

artifacts/location