# Access your source provider in CodeBuild For GitHub or GitHub Enterprise Server, you use a personal access token, a Secrets Manager secret, a connection, or an OAuth app to access the source provider. For Bitbucket, you use either an access token, an app password, a Secrets Manager secret, a connection, or an OAuth app to access the source provider. **Topics** + [ # Create and store a token in a Secrets Manager secret ](asm-create-secret.md) + [ # GitHub and GitHub Enterprise Server access in CodeBuild ](access-tokens-github-overview.md) + [ # Bitbucket access in CodeBuild ](access-tokens-bitbucket-overview.md) + [ # GitLab access in CodeBuild ](access-tokens-gitlab-overview.md) # Create and store a token in a Secrets Manager secret If you choose to use to store your access token using Secrets Manager, you can use either an existing secret connection or create a new secret. To create a new secret, do the following: ------ #### [ AWS Management Console ] **To create a Secrets Manager secret in the AWS Management Console** 1. For **Source provider**, choose **Bitbucket**, **GitHub**, or **GitHub Enterprise**. 1. For **Credential**, do one of the following: + Choose **Default source credential** to use your account's default source credential to apply to all projects. 1. If you aren't connected to your source provider, choose **Manage default source credential**. 1. For **Credential type**, choose a credential type other than **CodeConnections**. 1. For **Service**, choose **Secrets Manager** and for **Secrets** choose **New secret**. 1. In **Secret name**, enter the name of your secret. 1. In **Secret description - optional**, enter a description for your secret. 1. Depending on the source provider you chose, enter your token or username and app password and choose **Save**. + Choose **Custom source credential** to use a custom source credential to override your account's default settings. 1. For **Credential type**, choose a credential type other than **CodeConnections**. 1. In **Connection**, choose **Create a secret**. 1. In **Secret name**, enter the name of your secret. 1. In **Secret description - optional**, enter a description for your secret. 1. Depending on the source provider you chose, enter your token or username and app password, and choose **Create**. ------ #### [ AWS CLI ] **To create a Secrets Manager secret in the AWS CLI** + Open a terminal (Linux, macOS, or Unix) or command prompt (Windows). Use the AWS CLI to run the Secrets Manager **create-secret** command. ``` aws secretsmanager create-secret --region \ --name '' \ --description '' \ --secret-string '{ "ServerType":"", "AuthType":"", "Token":"" }' \ --tags Key=codebuild:source,Value='' \ Key=codebuild:source:type,Value= \ Key=codebuild:source:provider,Value= ``` The Secrets Manager secrets that CodeBuild accept must be in the same account and AWS Region as the CodeBuild project and must be in the following JSON format: ``` { "ServerType": ServerType, "AuthType: AuthType, "Token": string, "Username": string // Optional and is only used for Bitbucket app password } ``` [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/asm-create-secret.html) Additionally, CodeBuild uses the following resource tags on the secret to ensure the secrets are easily selectable when creating or editing projects. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/asm-create-secret.html) ------ # GitHub and GitHub Enterprise Server access in CodeBuild For GitHub, you can use a personal access token, an OAuth app, a Secrets Manager secret, or a GitHub App connection to access the source provider. For GitHub Enterprise Server, you can use a personal access token, a Secrets Manager secret, or a GitHub App connection to access the source provider. **Topics** + [ # GitHub App connections for GitHub and GitHub Enterprise Server ](connections-github-app.md) + [ # GitHub and GitHub Enterprise Server access token ](access-tokens-github.md) + [ # GitHub OAuth app ](oauth-app-github.md) # GitHub App connections for GitHub and GitHub Enterprise Server You can use GitHub App to connect with CodeBuild. GitHub App connections are supported through [AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html). The source provider access enables you to trigger a build by subscribing to [GitHub webhook events](github-webhook.md) using [ CreateWebhook](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_CreateWebhook.html), or to use [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md) in CodeBuild. **Note** CodeConnections is available in fewer regions than CodeBuild. You can use cross-region connections in CodeBuild. Connections created in opt-in regions, cannot be used in other regions. For more information, see [AWS CodeConnections endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/codestar_connections.html). **Topics** + [ ## Step 1: Create a connection to GitHub App (console) ](#connections-github-console) + [ ## Step 2: Grant CodeBuild project IAM role access to use the connection ](#connections-github-role-access) + [ ## Step 3: Configure CodeBuild to use the new connection ](#connections-github-account-credential) + [Troubleshooting the GitHub App](#connections-github-troubleshooting) ## Step 1: Create a connection to GitHub App (console) Use these steps to use the CodeBuild console to add a connection for your project in GitHub. **To create a connection to GitHub** + Follow the instructions in the *Developer Tools User Guide* for [Create a connection to GitHub](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html). **Note** Instead of creating or using an existing connection in your account, you can use a connection shared from another AWS account. For more information, see [Share connections with AWS accounts](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html). ## Step 2: Grant CodeBuild project IAM role access to use the connection You can grant CodeBuild project IAM role access to use the GitHub tokens vended by your connection. **To grant CodeBuild project IAM role access** 1. Create an IAM role for your CodeBuild project by following the instructions to [Allow CodeBuild to interact with other AWS services](setting-up-service-role.md) for your CodeBuild project. 1. While following the instructions, add the following IAM policy to your CodeBuild project role to grant access to the connection. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codeconnections:GetConnectionToken", "codeconnections:GetConnection" ], "Resource": [ "arn:aws:iam::*:role/Service*" ] } ] } ``` ------ ## Step 3: Configure CodeBuild to use the new connection You can configure a connection as an account level credential and use it in a project. ------ #### [ AWS Management Console ] **To configure a connection as an account level credential in the AWS Management Console** 1. For **Source provider**, choose **GitHub**. 1. For **Credential**, do one of the following: + Choose **Default source credential** to use your account's default source credential to apply to all projects. 1. If you aren't connected to GitHub, choose **Manage default source credential**. 1. For **Credential type**, choose **GitHub App**. 1. 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. 1. For **Credential type**, choose **GitHub App**. 1. In **Connection**, choose to use an existing connection or create a new connection. ------ #### [ AWS CLI ] **To configure a connection as an account level credential in the AWS CLI** + Open a terminal (Linux, macOS, or Unix) or command prompt (Windows). Use the AWS CLI to run the **import-source-credentials** command, specifying the `--auth-type`, `--server-type`, and `--token` for your connection. Use the following command: ``` aws codebuild import-source-credentials --auth-type CODECONNECTIONS --server-type GITHUB --token ``` ------ You can also set up multiple tokens for your CodeBuild projects. For more information, see [Configure multiple tokens as source level credentials](multiple-access-tokens.md#asm-source-credential). ## Troubleshooting problems with the GitHub App The following information can help you troubleshoot common issues with the GitHub App. **Topics** + [ ### Install the AWS Connector for GitHub app in an undesired region ](#connections-github-troubleshooting.undesired-region) + [ ### The GitHub App connection doesn't have access to repositories ](#connections-github-troubleshooting.repo-access) + [ ### The AWS service's IAM role is missing necessary IAM permissions. ](#connections-github-troubleshooting.iam-permissions) ### Install the AWS Connector for GitHub app in an undesired region **Issue:** You installed the AWS Connector for GitHub from the GitHub Marketplace, but the connection was created in an undesired region. If you attempt to reconfigure the app on the GitHub website, it won't work because the app is already installed on your GitHub account. **Possible cause:** The app is already installed in your GitHub account, so you can only reconfigure the app permissions. **Recommended solution:** You can create a new connection with the installation ID in the desired region. 1. Open the CodeConnections console at [https://console.aws.amazon.com/codesuite/settings/connections](https://console.aws.amazon.com/codesuite/settings/connections) and navigate to the desired region using the region selector in the AWS console navigation bar. 1. Follow the instructions in the *Developer Tools User Guide* for [Create a connection to GitHub](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html). **Note** Since you've already installed the AWS Connector for GitHub app, you can choose it instead of installing a new app. ### The GitHub App connection doesn't have access to repositories **Issue:** An AWS service using the connection, such as CodeBuild or CodePipeline, reports that it doesn't have access to the repository or the repository doesn't exist. Some possible error messages include: + `Authentication required for primary source.` + `Unable to create webhook at this time. Please try again later.` + `Failed to create webhook. GitHub API limit reached. Please try again later.` ***Possible cause:** You might have been using the GitHub app and haven't granted the webhook permission scope.* **Recommended solution:** To grant the required permission scope, follow the instructions in [ Navigating to the GitHub App you want to review or modify](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#navigating-to-the-github-app-you-want-to-review-or-modify) to configure the installed app. Under the permissions section, you'll see the app doesn't have webhooks permission, and there is an option for you to review the newly requested permissions. Review and accept the new permissions. For more infomation, see [ Approving updated permissions for a GitHub App](https://docs.github.com/en/apps/using-github-apps/approving-updated-permissions-for-a-github-app). ***Possible cause:** The connection was working as expected, but suddenly doesn’t have access to the repositories.* **Possible solution:** Start by reviewing your [ authorizations](https://docs.github.com/en/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps) and your [ installations](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps), then verify the GitHub App is authorized and installed. If the GitHub App installation is suspended, then you need to unsuspended it. If the GitHub App is not authorized for a [UAT (User Access Token)](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) connection, or not installed for an [ IAT (Installation Access Token)](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) connection, the existing connection is not usable any more, and you will need to create a new connection. Note that reinstalling the GitHub App will not revive the previous connection that was associated to the old installation. **Possible solution:** If the connection is a UAT connection, make sure the connection is not concurrently being used, such as a being used in multiple CodeBuild concurrent runs of build. This is because GitHub immediately invalidates a previously issued UAT if an expiring token is refreshed by the connection. If you need to use UAT connection for multiple concurrent CodeBuild builds, you can create multiple connections and use each connection independently. **Possible solution:** If the UAT connection hasn't been used in the past 6 months, the connection will be invalidated by GitHub. To fix this, create a new connection. ***Possible cause:** You might have been using a UAT connection without installing the app.* **Recommended solution:** Though creating a UAT connection doesn't require associating the connection with a GitHub App installation, an installation is required for the repository to be accessible. Follow the instructions to [ review installations](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps) to make sure the GitHub App is installed. If it is not installed, navigate to the [GitHub App's page](https://github.com/marketplace/aws-connector-for-github) to install the app. For more information about UAT's access, see [About user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#about-user-access-tokens). ### The AWS service's IAM role is missing necessary IAM permissions. **Issue:** You see any of the following error messages: + `Access denied to connection ` + `Failed to get access token from ` **Recommended solution:** Typically you use a connection with an AWS service, such as CodePipeline or CodeBuild. When you give the AWS service an IAM role, the AWS service can use the role's permission to act on your behalf. Make sure the IAM role has necessary permission. For more information about the necessary IAM permission, see [Grant CodeBuild project IAM role access to use the connection](#connections-github-role-access) and [Identity and access management for AWS CodeStar Notifications and CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/security-iam.html) in the *Developer Tools console User Guide*. # 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\$1hook**: Grants full control of repository hooks. This scope is not required if your token has the `repo` scope. + **admin:org\$1hook**: Grants full control of organization hooks. This scope is only required if you are using the organization webhook feature. 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. 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](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-a-repository) and [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md). **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](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28) 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.md#create-project-console). 1. For **Source provider**, choose **GitHub**. 1. For **Credential**, do one of the following: + Choose to use account credentials to apply your account's default source credential to all projects. 1. If you aren't connected to GitHub, choose **Manage account credential**. 1. For **Credential type**, choose **Personal access token**. + If you chose to use account level credentials for **Service**, choose which service you'd like to use to store your token and do the following: 1. If you choose to use **Secrets Manager**, you can choose to use an existing secret connection or create a new secret, and then choose **Save**. For more information how to create a new secret, see [Create and store a token in a Secrets Manager secret](asm-create-secret.md). 1. If you choose to use **CodeBuild**, enter your GitHub personal access token, and then choose **Save**. + Select **Use override credentials for this project only** to use a custom source credential to override your account's credential settings. 1. From the populated credential list, choose one of the options under **Personal access token**. 1. You can also create new personal access token by selecting **create a new personal access token connection** in the description. ## 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, BITBUCKET, GITHUB\$1ENTERPRISE, GITLAB, and GITLAB\$1SELF\$1MANAGED. + *auth-type*: Required value. The type of authentication used to connect to a repository. Valid values are OAUTH, BASIC\$1AUTH, PERSONAL\$1ACCESS\$1TOKEN, CODECONNECTIONS, and SECRETS\$1MANAGER. For GitHub, only PERSONAL\$1ACCESS\$1TOKEN is allowed. BASIC\$1AUTH is only allowed with Bitbucket app password. + *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 personal access token or app password. For the auth-type CODECONNECTIONS, this is the connection ARN. For the auth-type SECRETS\$1MANAGER, this is the secret ARN. + *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.md#create-project-cli). 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`, `PERSONAL_ACCESS_TOKEN`, `CODECONNECTIONS`, or `SECRETS_MANAGER`. + The `serverType` is the type of source provider. This can be `GITHUB`, `GITHUB_ENTERPRISE`, `BITBUCKET`, `GITLAB`, or `GITLAB_SELF_MANAGED`. + 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" } ``` # GitHub OAuth app ## Connect GitHub using OAuth (console) To use the console to connect your project to GitHub using an OAuth app, do the following when you create a project. For information, see [Create a build project (console)](create-project.md#create-project-console). 1. For **Source provider**, choose **GitHub**. 1. For **Credential**, do one of the following: + Choose to use account credentials to apply your account's default source credential to all projects. 1. If you aren't connected to GitHub, choose **Manage account credential**. 1. For **Credential type**, choose **OAuth app**. + If you chose to use account level credentials for **Service**, choose which service you'd like to use to store your token and do the following: 1. If you choose to use **Secrets Manager**, you can choose to use an existing secret connection or create a new secret, and then choose **Save**. For more information how to create a new secret, see [Create and store a token in a Secrets Manager secret](asm-create-secret.md). 1. If you choose to use **CodeBuild** and then choose **Save**. + Select **Use override credentials for this project only** to use a custom source credential to override your account's credential settings. 1. From the populated credential list, choose one of the options under **OAuth app**. 1. You can also create new OAuth app token by selecting **create a new Oauth app token connection** in the description. To review your authorized OAuth apps, navigate to [Applications](https://github.com/settings/applications) on GitHub, and verify that an application named `AWS CodeBuild (region)` owned by [aws-codesuite](https://github.com/aws-codesuite) is listed. # Bitbucket access in CodeBuild For Bitbucket, you use either an access token, an app password, an OAuth app, or a Bitbucket connection to access the source provider. **Topics** + [ # Bitbucket App connections ](connections-bitbucket-app.md) + [ # Bitbucket app password or access token ](access-tokens-bitbucket.md) + [ # Bitbucket OAuth app ](oauth-app-bitbucket.md) # Bitbucket App connections You can use Bitbucket to connect with CodeBuild. Bitbucket App connections are supported through [AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html). **Note** CodeConnections is available in less regions than CodeBuild. You can use cross-region connections in CodeBuild. Connections created in opt-in regions, cannot be used in other regions. For more information, see [AWS CodeConnections endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/codestar_connections.html). **Topics** + [ ## Step 1: Create a connection to Bitbucket (console) ](#connections-bitbucket-console) + [ ## Step 2: Grant CodeBuild project IAM role access to use the connection ](#connections-bitbucket-role-access) + [ ## Step 3: Configure CodeBuild to use the new connection ](#connections-bitbucket-account-credential) ## Step 1: Create a connection to Bitbucket (console) Use these steps to use the CodeBuild console to add a connection for your project in Bitbucket. **To create a connection to Bitbucket** + Follow the instructions in the *Developer Tools User Guide* for [Create a connection to Bitbucket](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-bitbucket.html). **Note** Instead of creating or using an existing connection in your account, you can use a connection shared from another AWS account. For more information, see [Share connections with AWS accounts](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html). ## Step 2: Grant CodeBuild project IAM role access to use the connection You can grant CodeBuild project IAM role access to use the Bitbucket tokens vended by your connection. **To grant CodeBuild project IAM role access** 1. Create an IAM role for your CodeBuild project by following the instructions to [Allow CodeBuild to interact with other AWS services](setting-up-service-role.md) for your CodeBuild project. 1. While following the instructions, add the following IAM policy to your CodeBuild project role to grant access to the connection. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "codeconnections:GetConnectionToken", "codeconnections:GetConnection" ], "Resource": [ "arn:aws:iam::*:role/Service*" ] } ] } ``` ------ ## Step 3: Configure CodeBuild to use the new connection You can configure a connection as an account level credential and use it in a project. ------ #### [ AWS Management Console ] **To configure a connection as an account level credential in the AWS Management Console** 1. For **Source provider**, choose **Bitbucket**. 1. For **Credential**, do one of the following: + Choose **Default source credential** to use your account's default source credential to apply to all projects. 1. If you aren't connected to Bitbucket, choose **Manage default source credential**. 1. For **Credential type**, choose **CodeConnections**. 1. 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. 1. For **Credential type**, choose **CodeConnections**. 1. In **Connection**, choose to use an existing connection or create a new connection. ------ #### [ AWS CLI ] **To configure a connection as an account level credential in the AWS CLI** + Open a terminal (Linux, macOS, or Unix) or command prompt (Windows). Use the AWS CLI to run the **import-source-credentials** command, specifying the `--auth-type`, `--server-type`, and `--token` for your connection. Use the following command: ``` aws codebuild import-source-credentials --auth-type CODECONNECTIONS --server-type BITBUCKET --token ``` ------ For more information on setting up multiple tokens in your CodeBuild project, see [Configure multiple tokens as source level credentials](multiple-access-tokens.md#asm-source-credential). # 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. + **account**: Grants read access to the user's account information. 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.md#create-project-console). 1. For **Source provider**, choose **Bitbucket**. 1. For **Credential**, do one of the following: + Choose to use account credentials to apply your account's default source credential to all projects. 1. If you aren't connected to Bitbucket, choose **Manage account credential**. 1. For **Credential type**, choose **App password**. + If you chose to use account level credentials for **Service**, choose which service you'd like to use to store your token and do the following: 1. If you choose to use **Secrets Manager**, you can choose to use an existing secret connection or create a new secret, and then choose **Save**. For more information how to create a new secret, see [Create and store a token in a Secrets Manager secret](asm-create-secret.md). 1. If you choose to use **CodeBuild**, enter your Bitbucket username and app password, and then choose **Save**. + Select **Use override credentials for this project only** to use a custom source credential to override your account's credential settings. 1. From the populated credential list, choose one of the options under **App password**. 1. You can also create new App password token by selecting **create a new app password connection** in the description. ## 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)](create-project.md#create-project-console). 1. For **Source provider**, choose **Bitbucket**. 1. For **Credential**, do one of the following: + Choose to use account credentials to apply your account's default source credential to all projects. 1. If you aren't connected to Bitbucket, choose **Manage account credential**. 1. For **Credential type**, choose **Personal access token**. + If you chose to use account level credentials for **Service**, choose which service you'd like to use to store your token and do the following: 1. If you choose to use **Secrets Manager**, you can choose to use an existing secret connection or create a new secret, and then choose **Save**. For more information how to create a new secret, see [Create and store a token in a Secrets Manager secret](asm-create-secret.md). 1. If you choose to use **CodeBuild**, enter your Bitbucket personal access token, and then choose **Save**. + Select **Use override credentials for this project only** to use a custom source credential to override your account's credential settings. 1. From the populated credential list, choose one of the options under **Personal access token**. 1. You can also create new personal access token by selecting **create a new personal access token connection** in the description. ## Connect Bitbucket with an app password or access token(CLI) Follow these steps to use the AWS CLI to connect your project to Bitbucket using an app password or 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": "BITBUCKET", "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, BITBUCKET, GITHUB\$1ENTERPRISE, GITLAB, and GITLAB\$1SELF\$1MANAGED. + *auth-type*: Required value. The type of authentication used to connect to a repository. Valid values are OAUTH, BASIC\$1AUTH, PERSONAL\$1ACCESS\$1TOKEN, CODECONNECTIONS, and SECRETS\$1MANAGER. For GitHub, only PERSONAL\$1ACCESS\$1TOKEN is allowed. BASIC\$1AUTH is only allowed with Bitbucket app password. + *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 personal access token or app password. For the auth-type CODECONNECTIONS, this is the connection ARN. For the auth-type SECRETS\$1MANAGER, this is the secret ARN. + *username*: Optional value. This parameter is ignored for GitHub and GitHub Enterprise Server source providers. 1. 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 (AWS CLI)](create-project.md#create-project-cli). 1. 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 be `OAUTH`, `BASIC_AUTH`, `PERSONAL_ACCESS_TOKEN`, `CODECONNECTIONS`, or `SECRETS_MANAGER`. + The `serverType` is the type of source provider. This can be `GITHUB`, `GITHUB_ENTERPRISE`, `BITBUCKET`, `GITLAB`, or `GITLAB_SELF_MANAGED`. + The `arn` is the ARN of the token. 1. 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" } ``` # Bitbucket OAuth app ## Connect Bitbucket using OAuth (console) To use the console to connect your project to Bitbucket using an OAuth app, do the following when you create a project. For information, see [Create a build project (console)](create-project.md#create-project-console). 1. For **Source provider**, choose **Bitbucket**. 1. For **Credential**, do one of the following: + Choose to use account credentials to apply your account's default source credential to all projects. 1. If you aren't connected to Bitbucket, choose **Manage account credential**. 1. For **Credential type**, choose **OAuth app**. + If you chose to use account level credentials for **Service**, choose which service you'd like to use to store your token and do the following: 1. If you choose to use **Secrets Manager**, you can choose to use an existing secret connection or create a new secret, and then choose **Save**. For more information how to create a new secret, see [Create and store a token in a Secrets Manager secret](asm-create-secret.md). 1. If you choose to use **CodeBuild** and then choose **Save**. + Select **Use override credentials for this project only** to use a custom source credential to override your account's credential settings. 1. From the populated credential list, choose one of the options under **OAuth app**. 1. You can also create new OAuth app token by selecting **create a new Oauth app token connection** in the description. To review your authorized OAuth apps, navigate to [Application authorizations](https://bitbucket.org/account/settings/app-authorizations/) on Bitbucket, and verify that an application named `AWS CodeBuild (region)` is listed. # GitLab access in CodeBuild For GitLab, you use a GitLab connection to access the source provider. **Topics** + [ ## Connect CodeBuild to GitLab ](#connections-gitlab) ## Connect CodeBuild to GitLab Connections allow you to authorize and establish configurations that associate your third-party provider with your AWS resources using AWS CodeConnections. To associate your third-party repository as a source for your build project, you use a connection. To add a GitLab or GitLab Self Managed source provider in CodeBuild, you can choose either to: + Use the CodeBuild console **Create build project** wizard or **Edit Source** page to choose the **GitLab** or **GitLab Self Managed** provider option. See [Create a connection to GitLab (console)](#connections-gitlab-console) to add the source provider. The console helps you create a connections resource. + Use the CLI to create your connections resources, see [Create a connection to GitLab (CLI)](#connections-gitlab-cli) to create a connections resource with the CLI. **Note** You can also create a connection using the Developer Tools console under **Settings**. See [Create a Connection](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create.html). **Note** By authorizing this connection installation in GitLab, you grant our service permissions to process your data by accessing your account, and you can revoke the permissions at any time by uninstalling the application. ### Create a connection to GitLab This section describes how to connect GitLab to CodeBuild. For more information about GitLab connections, see [Connect CodeBuild to GitLab](#connections-gitlab). Before you begin: + You must have already created an account with GitLab. **Note** Connections only provide access to repositories owned by the account that was used to create and authorize the connection. **Note** You can create connections to a repository where you have the **Owner** role in GitLab, and then the connection can be used with the repository with resources such as CodeBuild. For repositories in groups, you do not need to be the group owner. + To specify a source for your build project, you must have already created a repository on GitLab. **Topics** + [ #### Create a connection to GitLab (console) ](#connections-gitlab-console) + [ #### Create a connection to GitLab (CLI) ](#connections-gitlab-cli) #### Create a connection to GitLab (console) Use these steps to use the CodeBuild console to add a connection for your project (repository) in GitLab. **Note** Instead of creating or using an existing connection in your account, you can use a connection shared from another AWS account. For more information, see [Share connections with AWS accounts](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-share.html). **To create or edit your build project** 1. Sign in to the CodeBuild console. 1. Choose one of the following. + Choose to create a build project. Follow the steps in [Create a build project (console)](create-project.md#create-project-console) to complete the first screen and in the **Source** section, under **Source Provider**, choose **GitLab**. + Choose to edit an existing build project. Choose **Edit**, and then choose **Source**. In the **Edit Source** page, under **Source provider**, choose **GitLab**. 1. Choose one of the following: + Under **Connection**, choose ** Default connection**. Default connection applies a default GitLab connection across all projects. + Under **Connection**, choose ** Custom connection**. Custom connection applies a custom GitLab connection that overrides your account's default settings. 1. Do one of the following: + Under **Default connection** or **Custom connection**, if you have not already created a connection to your provider, choose **Create a new GitLab connection**. Proceed to step 5 to create the connection. + Under **Connection**, if you have already created a connection to your provider, choose the connection. Proceed to step 10. **Note** If you close the pop-up window before a GitLab connection is created, you need to refresh the page. 1. To create a connection to a GitLab repository, under **Select a provider**, choose **GitLab**. In **Connection name**, enter the name for the connection that you want to create. Choose **Connect to GitLab**. ![\[Console screenshot showing connection option selected for GitLab.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/connections-create-gitlab.png) 1. When the sign-in page for GitLab displays, log in with your credentials, and then choose **Sign in**. 1. If this is your first time authorizing the connection, an authorization page displays with a message requesting authorization for the connection to access your GitLab account. Choose **Authorize**. ![\[Screenshot showing the message to authorize the connection for your GitLab account.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/gitlab-authorization.png) 1. The browser returns to the connections console page. Under **GitLab connection settings**, the new connection is shown in **Connection name**. 1. Choose **Connect**. After a GitLab connection is successfully created, a success banner will be displayed at the top. 1. On the **Create build project** page, in the **Default connection** or **Custom connection** drop-down list, make sure your connection ARN is listed. If not, choose the refresh button to have it appear. 1. In **Repository**, choose the name of your project in GitLab by specifying the project path with the namespace. For example, for a group-level repository, enter the repository name in the following format: `group-name/repository-name`. For more information about the path and namespace, see the `path_with_namespace` field in [https://docs.gitlab.com/ee/api/projects.html\$1get-single-project](https://docs.gitlab.com/ee/api/projects.html#get-single-project). For more information about the namespace in GitLab, see [https://docs.gitlab.com/ee/user/namespace/](https://docs.gitlab.com/ee/user/namespace/). **Note** For groups in GitLab, you must manually specify the project path with the namespace. For example, for a repository named `myrepo` in a group `mygroup`, enter the following: `mygroup/myrepo`. You can find the project path with the namespace in the URL in GitLab. 1. In **Source version - optional**, enter a pull request ID, branch, commit ID, tag, or reference and a commit ID. For more information, see [Source version sample with AWS CodeBuild](sample-source-version.md). **Note** We recommend that you choose Git branch names that don't look like commit IDs, such as `811dd1ba1aba14473856cee38308caed7190c0d` or `5392f7`. This helps you avoid Git checkout collisions with actual commits. 1. In **Git clone depth - optional**, you can create a shallow clone with a history truncated to the specified number of commits. If you want a full clone, choose **Full**. 1. In **Build Status - optional**, 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). #### Create a connection to GitLab (CLI) You can use the AWS Command Line Interface (AWS CLI) to create a connection. To do this, use the **create-connection** command. **Important** A connection created through the AWS CLI or AWS CloudFormation is in `PENDING` status by default. After you create a connection with the CLI or CloudFormation, use the console to edit the connection to make its status `AVAILABLE`. **To create a connection** + Follow the instructions in the *Developer Tools console User Guide* for [Create a connection to GitLab (CLI)](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-gitlab.html#connections-create-gitlab-cli).