CodeBuild supports sourcing access tokens to third party providers from your secrets in AWS Secrets Manager or through AWS CodeConnections connections. You can set your secret or connection as the default credential for interactions with a specified third party provider such as GitHub, GitHub Enterprise, or Bitbucket.
You can set your source credentials at three different levels:
-
Account level credentials for all projects: These are default credentials for all projects in an AWS account. They will be used on a project when no project or source level credentials are specified.
-
Source level credentials for a specific repository: This is when a Secrets Manager secret or CodeConnections connection is defined on a project source. These credentials will only be used for operations on the specified source repository. This allows you to set up multiple access tokens with different permission scopes in the same project, and not use the default account level credentials.
-
Project level fallback credentials: You can set a project level fallback credential by using
NO_SOURCE
as primary source type and define a secret or connection on it. This is can be used when you have multiple sources on a project, but want to use the same credentials for them, or when you don't want to use the default account level credentials for your project.
Topics
Step 1: Create a Secrets Manager secret or a CodeConnections connection
Use the following instructions to create a Secrets Manager secret or a CodeConnections connection:
Step 2: Grant CodeBuild project IAM role access to Secrets Manager secrets
Note
Before you continue, you must have access to the token created in Secrets Manager or CodeConnections.
To grant CodeBuild project IAM role access to Secrets Manager or CodeConnections, you must add the following IAM policy.
To grant CodeBuild project IAM role access
-
Create an IAM role for your CodeBuild project by following the instructions to Allow CodeBuild to interact with other AWS services for your CodeBuild project.
-
Do one of the following:
-
Add the following IAM policy to your CodeBuild project role to grant access to your secret.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": [ "
<secret-arn>
" ] } ] }(Optional) If you're using AWS KMS customer managed keys to encrypt a Secrets Manager secret, you can add the following policy statement to grant access.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt" ], "Resource": "
<kms-key-arn>
", "Condition": { "StringEquals": { "kms:EncryptionContext:SecretARN": "<secret-arn>
" } } } ] } -
Add the following IAM policy to your CodeBuild project role to grant access to your connection.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codeconnections:GetConnectionToken", "codeconnections:GetConnection" ], "Resource": [
<connection-arn>
] } ] }
-
Step 3: Configure Secrets Manager or CodeConnections tokens
You can set your source credentials at three different levels with either Secrets Manager or CodeConnections tokens.
Configure Secrets Manager or CodeConnections tokens as account level credentials
You can configure a Secrets Manager secret or CodeConnections connection as an account level credential and use it in a project.
To configure a connection as an account level credential in the AWS Management Console
-
For Source provider, choose Bitbucket, GitHub, or GitHub Enterprise.
-
For Credential, do one of the following:
-
Choose Default source credential to use your account's default source credential to apply to all projects.
-
If you aren't connected to your source provider, choose Manage default source credential.
-
For Credential type, choose a credential type.
-
If you chose CodeConnections, choose to use an existing connection or create a new connection.
If you chose a different credential type, for Service choose which service you'd like to use to store your token and do the following:
-
If you chose to use Secrets Manager, you can choose to use an existing secret connection or create a new secret and choose Save. For more information how to create a new secret, see Create and store a token in a Secrets Manager secret.
-
If you chose to use CodeBuild, enter your token or your username and app password, and choose Save.
-
-
-
Choose Custom source credential to use a custom source credential to override your account's default settings.
-
For Credential type, choose a credential type.
-
In Connection, choose to use an existing connection or create a new connection.
-
-
You can now use the token in your build project and run it. For more information, see Create a build project in AWS CodeBuild and Run AWS CodeBuild builds manually.
Configure multiple tokens as source level credentials
To use Secrets Manager secrets or CodeConnections connections as source level credentials, directly reference the token in CodeBuild project, and start a build.
To configure multiple tokens as source level credentials in the AWS Management Console
-
For Source provider, choose GitHub.
-
For Credential, do one of the following:
-
Choose Default source credential to use your account's default source credential to apply to all projects.
-
If you aren't connected to GitHub, choose Manage default source credential.
-
For Credential type, choose GitHub App.
-
In Connection, choose to use an existing connection or create a new connection.
-
-
Choose Custom source credential to use a custom source credential to override your account's default settings.
-
For Credential type, choose GitHub App.
-
In Connection, choose to use an existing connection or create a new connection.
-
-
-
Choose Add source and repeat the process of choosing your source provider and credentials.
Set a project level source credential fallback
To set up project level source credential fallback, use NO_SOURCE
for your project's primary source and reference the token.
aws codebuild create-project \ --name
<project-name>
\ --service-role<service-role-name>
\ --artifacts type=NO_ARTIFACTS \ --environment "type=LINUX_CONTAINER, computeType=BUILD_GENERAL1_SMALL, image=aws/codebuild/amazonlinux-x86_64-standard:5.0" \ --service-role<service-role-name>
\ --source "type=NO_SOURCE, auth={type=SECRETS_MANAGER,resource=<secret-or-connection-arn>
}, buildspec=<buildspec>
" --secondary-sources "type=GITHUB, location=<github-repository>
, sourceIdentifier=secondary" aws codebuild start-build --region<aws-region>
--project-name<project_name>
When using NO_SOURCE
, a buildspec typically is provided within the source model
as it is not directly configured to use an external source to fetch the buildspec.
Commonly, a NO_SOURCE
source will handle cloning all relevant repositories from within the
buildspec. To ensure the configured credentials are available for those operations, you can enable the
git-credential-helper
option in the buildspec.
env:
git-credential-helper: yes
During the build, CodeBuild will then read the AuthServer
field from the configured token
and use the token credentials for all git requests to that particular third party source provider.
Additional setup options
You can configure Secrets Manager account level credentials by using AWS CloudFormation templates. You can use the following AWS CloudFormation template to set an account level credential:
Parameters:
GitHubToken:
Type: String
NoEcho: true
Default: placeholder
Resources:
CodeBuildAuthTokenSecret:
Type: AWS::SecretsManager::Secret
Properties:
Description: CodeBuild auth token
Name: codebuild-auth-token
SecretString:
!Join
- ''
- - '{"ServerType":"GITHUB","AuthType":"PERSONAL_ACCESS_TOKEN","Token":"'
- !Ref GitHubToken
- '"}'
Tags:
- Key: codebuild:source:provider
Value: github
- Key: codebuild:source:type
Value: personal_access_token
CodeBuildSecretsManagerAccountCredential:
Type: AWS::CodeBuild::SourceCredential
Properties:
ServerType: GITHUB
AuthType: SECRETS_MANAGER
Token: !Ref CodeBuildAuthTokenSecret
Note
If you're also creating a project in the same stack, use the AWS CloudFormation attribute DependsOn
to ensure the AccountCredential
is created before the project.
You can also configure Secrets Manager multiple source level credentials by using AWS CloudFormation templates. You can use the following AWS CloudFormation template to use multiple tokens to pull in multiple sources:
Parameters:
GitHubTokenOne:
Type: String
NoEcho: true
Default: placeholder
GitHubTokenTwo:
Type: String
NoEcho: true
Default: placeholder
Resources:
CodeBuildSecretsManagerProject:
Type: AWS::CodeBuild::Project
Properties:
Name: codebuild-multitoken-example
ServiceRole: <service-role>
Environment:
Type: LINUX_CONTAINER
ComputeType: BUILD_GENERAL1_SMALL
Image: aws/codebuild/amazonlinux-x86_64-standard:5.0
Source:
Type: GITHUB
Location: <github-repository-one>
Auth:
Type: SECRETS_MANAGER
Resource: !Ref CodeBuildAuthTokenSecretOne
SecondarySources:
- Type: GITHUB
Location: <github-repository-two>
Auth:
Type: SECRETS_MANAGER
Resource: !Ref CodeBuildAuthTokenSecretTwo
SourceIdentifier: secondary
Artifacts:
Type: NO_ARTIFACTS
LogsConfig:
CloudWatchLogs:
Status: ENABLED
CodeBuildProjectIAMRoleSecretAccess:
Type: AWS::IAM::RolePolicy
Properties:
RoleName: <role-name>
PolicyName: CodeBuildProjectIAMRoleSecretAccessPolicy
PolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Action:
- secretsmanager:GetSecretValue
Resource:
- !Ref CodeBuildAuthTokenSecretOne
- !Ref CodeBuildAuthTokenSecretTwo
CodeBuildAuthTokenSecretOne:
Type: AWS::SecretsManager::Secret
Properties:
Description: CodeBuild auth token one
Name: codebuild-auth-token-one
SecretString:
!Join
- ''
- - '{"ServerType":"GITHUB","AuthType":"PERSONAL_ACCESS_TOKEN","Token":"'
- !Ref GitHubTokenOne
- '"}'
Tags:
- Key: codebuild:source:provider
Value: github
- Key: codebuild:source:type
Value: personal_access_token
CodeBuildAuthTokenSecretTwo:
Type: AWS::SecretsManager::Secret
Properties:
Description: CodeBuild auth token two
Name: codebuild-auth-token-two
SecretString:
!Join
- ''
- - '{"ServerType":"GITHUB","AuthType":"PERSONAL_ACCESS_TOKEN","Token":"'
- !Ref GitHubTokenTwo
- '"}'
Tags:
- Key: codebuild:source:provider
Value: github
- Key: codebuild:source:type
Value: personal_access_token