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 either an access token or an app password to access the source provider.
Note
GitLab and Self Managed GitLab source providers are not directly accessed by CodeBuild but instead through Amazon CodeConnections.
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
If you are using fine-grained personal access tokens, depending on your use case, your personal access token might need the following permissions:
-
Contents: Read-only: Grants access to private repositories. This permission is required if you are using private repositories as source.
-
Commit statuses: Read and write: Grants permission to create commit statuses. This permission is required if your project has webhook set up, or you have report build status feature enabled.
-
Webhooks: Read and write: Grants permission to manage webhooks. This permission is required if your project has webhook set up.
-
Pull requests: Read-only: Grants permission to access pull requests. This permission is required if your webhook has a
FILE_PATH
filter on pull request events. -
Administration: Read and write: This permission is required if you are using the self-hosted GitHub Actions runner feature with CodeBuild. For more details, see Create a registration token for a repository
and Set up self-hosted GitHub Actions runners in Amazon CodeBuild.
Note
If you want to access organization repositories, make sure you specify the organization as the resource owner of the access token.
For more information, see
Permissions required for fine-grained personal access tokens
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).
-
For Source provider, choose GitHub.
-
For Repository, choose Connect with a GitHub personal access token.
-
In GitHub personal access token, enter your GitHub personal access token.
-
Choose Save token.
Connect GitHub with an access token (CLI)
Follow these steps to use the Amazon CLI to connect your project to GitHub using an access token. For information about using the Amazon CLI with Amazon CodeBuild, see the Command line reference.
-
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,
) in a location on the local computer or instance where the Amazon CLI is installed. Modify the copied data as follows, and save your results.import-source-credentials.json
{ "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 tofalse
to prevent overwriting the repository source credentials. Set totrue
to overwrite the repository source credentials. The default value istrue
. -
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.
-
-
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 (Amazon CLI). -
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 beOAUTH
,BASIC_AUTH
, orPERSONAL_ACCESS_TOKEN
. -
The
serverType
is the type of source provider. This can beGITHUB
,GITHUB_ENTERPRISE
, orBITBUCKET
. -
The
arn
is the ARN of the token.
-
-
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 or access token
Prerequisites
Before you begin, you must add the proper permission scopes to your Bitbucket app password or access token.
For Bitbucket, your app password or access token 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 or access token must have this scope.
-
webhook: Grants access to webhooks. If your project has a webhook operation, then your app password or access token must have this scope.
For more information, see Scopes for Bitbucket Cloud REST API
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).
-
For Source provider, choose Bitbucket.
Note
CodeBuild does not support Bitbucket Server.
-
For Repository, choose Connect with a Bitbucket app password.
-
In Bitbucket username, enter your Bitbucket user name.
-
In Bitbucket app password, enter your Bitbucket app password.
-
Choose Save Bitbucket credentials.
Connect Bitbucket with an access token (console)
To use the console to connect your project to Bitbucket using an access token, do the following when you create a project. For information, see Create a build project (console).
-
For Source provider, choose Bitbucket.
Note
CodeBuild does not support Bitbucket Server.
-
For Repository, choose Connect with a Bitbucket access token.
-
In Bitbucket access token, enter your Bitbucket access token.
-
Choose Save token.
Connect Bitbucket with an app password or access token(CLI)
Follow these steps to use the Amazon CLI to connect your project to Bitbucket using an app password or access token. For information about using the Amazon CLI with Amazon CodeBuild, see the Command line reference.
-
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,
) in a location on the local computer or instance where the Amazon CLI is installed. Modify the copied data as follows, and save your results.import-source-credentials.json
{ "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 tofalse
to prevent overwriting the repository source credentials. Set totrue
to overwrite the repository source credentials. The default value istrue
. -
token
: Required value. For Bitbucket, this is either the access token or the app password. -
username
: Optional value. The Bitbucket user name whenauthType
is BASIC_AUTH. This parameter is ignored for other types of source providers or connections.
-
-
To connect your account with an app password or 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 app password, you can use
create-project
to create your CodeBuild project. For more information, see Create a build project (Amazon CLI). -
To view the connected app passwords or 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": "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 beOAUTH
,BASIC_AUTH
, orPERSONAL_ACCESS_TOKEN
. -
The
arn
is the ARN of the token.
-
-
To disconnect from a source provider and remove its app password or 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
" }