Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # Add functionality to projects with extensions in CodeCatalyst Amazon CodeCatalyst includes extensions that help you add functionality and integrate with products outside of CodeCatalyst. With extensions from the CodeCatalyst catalog, teams can customize their experiences in CodeCatalyst. **Topics** + [ ## Available third-party extensions ](#extensions-types) + [ # Extensions concepts ](extensions-concepts.md) + [ # Quickstart: Installing extensions, connecting providers, and linking resources in CodeCatalyst ](extensions-quickstart.md) + [ # Installing an extension in a space ](install-extension.md) + [ # Uninstalling an extension in a space ](uninstall-extension.md) + [ # Connecting GitHub accounts, Bitbucket workspaces, GitLab users, and Jira sites CodeCatalyst ](extensions-connect.md) + [ # Disconnecting GitHub accounts, Bitbucket workspaces, GitLab users, and Jira sites CodeCatalyst ](extensions-disconnect.md) + [ # Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst ](extensions-link.md) + [ # Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst ](extensions-unlink.md) + [ # Viewing third-party repositories and searching Jira issues in CodeCatalyst ](extensions-view-search.md) + [ # Automatically starting a workflow run after third-party repository events ](extensions-workflow-repositories.md) + [ # Restricting IP access with third-party repository providers ](extensions-restrict-ip-access.md) + [ # Blocking third-party merges when workflows fail ](extensions-block-merges.md) + [ # Linking Jira issues to CodeCatalyst pull requests ](link-jira-issues-pull-requests.md) + [ # Viewing CodeCatalyst events in Jira issues ](view-codecatalyst-events-jira.md) ## Available third-party extensions You can add particular functionality to your CodeCatalyst project depending on the extension you choose to integrate resources with. ### Integrating GitHub repositories in CodeCatalyst GitHub is a cloud-based service that helps developers store and manage their code. The **GitHub repositories** extension lets you use linked GitHub repositories in Amazon CodeCatalyst projects. You can also link GitHub repositories when creating a new CodeCatalyst project. For more information, see [Creating a project with a linked third-party repository](projects-create.md#projects-create-3p-repo). **Note** You can't use empty or archived GitHub repositories with CodeCatalyst projects. The **GitHub repositories** extension isn't compatible with GitHub Enterprise Server repositories. Once you install and configure the **GitHub repositories** extension, you will be able to: + View your GitHub repositories in the list of source repositories in CodeCatalyst + Store and manage workflow definition files in your GitHub repositories + Create, read, update, and delete files stored in linked GitHub repositories from CodeCatalyst Dev Environments + Store and index files from the linked GitHub repositories in CodeCatalyst + Create CodeCatalyst projects with existing repositories of connected GitHub accounts + Create a GitHub repository with code generated by a blueprint when creating a project with a blueprint or adding a blueprint + Start CodeCatalyst workflow runs automatically when code is pushed to linked GitHub repositories, or when pull requests are created, modified, or closed in linked GitHub repositories + Use linked GitHub repository source files in CodeCatalyst workflows + Read and execute GitHub actions in CodeCatalyst workflows + Send CodeCatalyst workflow run statuses to linked GitHub repositories, and block GitHub pull request merges based on commit statuses ### Integrating Bitbucket repositories in CodeCatalyst Bitbucket is a cloud-based service that helps developers store and manage their code. The **Bitbucket repositories** extension lets you use linked Bitbucket repositories in Amazon CodeCatalyst projects. You can also link Bitbucket repositories when creating a new CodeCatalyst project. For more information, see [Creating a project with a linked third-party repository](projects-create.md#projects-create-3p-repo). **Note** You can't use empty or archived Bitbucket repositories with CodeCatalyst projects. The **Bitbucket repositories** extension isn't compatible with Bitbucket Data Center repositories. Once you install and configure the **Bitbucket repositories** extension, you will be able to: + View your Bitbucket repositories in the list of source repositories in CodeCatalyst + Store and manage workflow definition files in your Bitbucket repositories. + Create, read, update, and delete files stored in linked Bitbucket repositories from CodeCatalyst Dev Environments + Create CodeCatalyst projects with existing repositories of connected Bitbucket accounts + Store and index files from the linked Bitbucket repositories in CodeCatalyst + Create a Bitbucket repository with code generated by a blueprint when creating a project with a blueprint or adding a blueprint + Start CodeCatalyst workflow runs automatically when code is pushed to linked Bitbucket repositories, or when pull requests are created, modified, or closed in linked Bitbucket repositories + Use your linked Bitbucket repository source files in CodeCatalyst workflows + Send CodeCatalyst workflow run statuses to linked Bitbucket repositories, and block Bitbucket pull request merges based on commit statuses ### Integrating GitLab repositories in CodeCatalyst GitLab is a cloud-based service that helps developers store and manage their code. The **GitLab repositories** extension lets you use linked GitLab project repositories in Amazon CodeCatalyst projects. You can also link GitLab project repositories when creating a new CodeCatalyst project. For more information, see [Creating a project with a linked third-party repository](projects-create.md#projects-create-3p-repo). **Note** You can't use empty or archived GitLab project repositories with CodeCatalyst projects. The **GitLab repositories** extension isn't compatible with GitLab self-managed repositories. Once you install and configure the **GitLab repositories** extension, you will be able to: + View your GitLab project repositories in the list of source repositories in CodeCatalyst + Store and manage workflow definition files in your GitLab project repositories. + Create, read, update, and delete files stored in linked GitLab project repositories from CodeCatalyst Dev Environments + Create CodeCatalyst projects with existing repositories of connected GitLab users + Store and index files from the linked GitLab project repositories in CodeCatalyst + Create a GitLab project repository with code generated by a blueprint when creating a project with a blueprint or adding a blueprint + Start CodeCatalyst workflow runs automatically when code is pushed to linked GitLab project repositories, or when pull requests are created, modified, or closed in linked GitLab project repositories + Use your linked GitLab project repository source files in CodeCatalyst workflows + Send CodeCatalyst workflow run statuses to linked GitLab project repositories, and block GitLab merge requests based on commit statuses ### Integrating Jira issues in CodeCatalyst Jira is a software application that helps agile development teams plan, assign, track, report, and manage work. The **Jira Software** extension lets you use Jira projects in Amazon CodeCatalyst projects. **Note** CodeCatalyst is only compatible with **Jira Software Cloud**. Once you install and configure the **Jira Software** extension for an Amazon CodeCatalyst project, you will be able to: + Access Jira projects from CodeCatalyst by linking them to CodeCatalyst projects + Update Jira issues with CodeCatalyst pull requests + View status and workflow runs of linked CodeCatalyst pull requests in Jira issues # Extensions concepts Here are some concepts and terms to know when working with extensions in CodeCatalyst. ## Extensions An *extension* is an add-on that you can install into your CodeCatalyst space to add new functionality to your projects and integrate with services outside of CodeCatalyst. Extensions can be browsed and installed from the CodeCatalyst catalog. ## CodeCatalyst catalog The CodeCatalyst catalog is a centralized listing of all the extensions available in CodeCatalyst. You can browse the CodeCatalyst catalog to find extensions that can improve your team's experiences in areas of CodeCatalyst such as source, workflows, and more. ## Connecting and linking Depending on the third-party resources you want to use or manage, you need to connect your GitHub account, Bitbucket workspace, or Jira project. Then, you need to link your GitHub repository, Bitbucket repository, or Jira project to your CodeCatalyst project. + **GitHub repositories**: Connect GitHub account and then link GitHub repositories. + **Bitbucket repositories**: Connect Bitbucket workspace and then link Bitbucket repositories. + **GitLab repositories**: Connect GitLab user and then link GitLab project repositories. + **Jira Software**: Connect Jira site and then link Jira projects. # Quickstart: Installing extensions, connecting providers, and linking resources in CodeCatalyst This tutorial provides a walkthrough of the following three tasks: 1. Install the **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software** extension. You're prompted in an external site to connect and provide CodeCatalyst with access to your third-party resources, which is done as part of the next step. **Important** To install the **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software** extension to your CodeCatalyst space, you must be signed in with an account that has the **Space administrator** role in the space. 1. Connect your GitHub account, Bitbucket workspace, GitLab user, or Jira site to CodeCatalyst. **Important** To connect your GitHub account, Bitbucket workspace, GitLab user, or Jira site to your CodeCatalyst space, you must be both the third-party source's administrator and the CodeCatalyst **Space administrator**. **Important** After you install a repository extension, any repositories you link to CodeCatalyst will have their code indexed and stored in CodeCatalyst. This will make the code searchable in CodeCatalyst. To better understand the data protection for your code when using linked repositories in CodeCatalyst, see [Data protection](https://docs.aws.amazon.com/codecatalyst/latest/userguide/data-protection.html) in the *Amazon CodeCatalyst User Guide*. **Note** If you're using a connection to a GitHub account, you must create a personal connection to establish identity mapping between your CodeCatalyst identity and your GitHub identity. For more information, see [Personal connections](concepts.md#personal-connection-concept) and [Accessing GitHub resources with personal connections](ipa-settings-connections.md). 1. Link your GitHub repository, Bitbucket repository, GitLab project repository, or Jira project to your CodeCatalyst project. **Important** While you can link a GitHub repository, Bitbucket repository, or GitLab project repository as a **Contributor**, you can only unlink a third-party repository as the **Space administrator** or the **Project administrator**. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). To link your Jira project to your CodeCatalyst project, you must be the CodeCatalyst **Space administrator** or CodeCatalyst **Project administrator**. **Important** CodeCatalyst doesn't support detecting changes in the default branch for linked repositories. To change the default branch for a linked repository, you must first unlink it from CodeCatalyst, change the default branch, and then link it again. For more information, see [Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-link.md). As a best practice, always make sure you have the latest version of the extension before you link a repository. **Note** A GitHub repository, Bitbucket repository, or GitLab project repository can only be linked to one CodeCatalyst project in a space. You can't use empty or archived GitHub repositories, Bitbucket repositories, or GitLab project repositories with CodeCatalyst projects. You can't link a GitHub repository, Bitbucket repository, or GitLab project repository that has the same name as a repository in a CodeCatalyst project. The **GitHub repositories** extension isn't compatible with GitHub Enterprise Server repositories. The **Bitbucket repositories** extension isn't compatible with Bitbucket Data Center repositories. The **GitLab repositories** extension isn't compatible with GitLab self-managed project repositories. You can't use the **Write description for me** or **Summarize comments** features with linked repositories. These features are only available in pull requests in CodeCatalyst. A CodeCatalyst project can only be linked to one Jira project. A Jira project can be linked to multiple CodeCatalyst projects. You can also install the **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories** extension, connect to your GitHub account, Bitbucket workspace, or GitLab user, and link third-party repositories when creating a new CodeCatalyst project. For more information, see [Creating a project with a linked third-party repository](projects-create.md#projects-create-3p-repo). **Topics** + [ ## Step 1: Install a third-party extension from the CodeCatalyst catalog ](#extensions-quickstart-install) + [ ## Step 2: Connect your third-party provider to your CodeCatalyst space ](#extensions-github-extension-get-started-connect) + [ ## Step 3: Link your third-party resources to your CodeCatalyst project ](#extensions-quickstart-link) + [ ## Next steps ](#extensions-quickstart-next-steps) ## Step 1: Install a third-party extension from the CodeCatalyst catalog The first step to using thid-party resources in CodeCatalyst is to install the **GitHub repositories** extension from the CodeCatalyst catalog. To install the extension, perform the following steps, choosing the extension for the third-party resources you want to use. **GitHub repositories**, **Bitbucket repositories**, and **GitLab repositories** allow you to use GitHub repositories, Bitbucket repositories, or GitLab project repositories in CodeCatalyst. **Jira Software** allows you to manage Jira issues in CodeCatalyst. **To install an extension from the CodeCatalyst catalog** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Navigate to the CodeCatalyst CodeCatalyst catalog by choosing the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. You can search for **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software**. You can also filter extensions based on categories. 1. (Optional) To see more details about the extension, such as the permissions the extension will have, choose the extension name. 1. Choose **Install**. Review the permissions required by the extension, and if you want to continue, choose **Install** again. After installing the extension, you are taken to the extension details page. Depending on the extension you installed, you can view and manage connected providers and linked resources. ## Step 2: Connect your third-party provider to your CodeCatalyst space After you install the **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software** extension, the next step is to connect your GitHub account, Bitbucket workspace, GitLab project repository, or Jira site to your CodeCatalyst space. **To connect your GitHub account, Bitbucket workspace, or Jira site to CodeCatalyst** + Do one of the following depending on the third-party extension you installed: + **GitHub repositories**: Connect to a GitHub account. 1. In the **Connected GitHub accounts** tab, choose **Connect GitHub account** to go to the external site for GitHub. 1. Sign in to your GitHub account using your GitHub credentials, and then choose the account where you want to install Amazon CodeCatalyst. **Tip** If you have previously connected a GitHub account to the space, you will not be prompted to reauthorize. You will instead see a dialog box asking you where you would like to install the extension if you are a member or collaborator in more than one GitHub organization, or the configuration page for the Amazon CodeCatalyst application if you only belong to one GitHub organization. Configure the application for the repository access that you want to allow, and then choose **Save**. If the **Save** button is not active, make a change to the configuration, and then try again. 1. Choose whether you want to allow CodeCatalyst to access all current and future repositories, or choose the specific GitHub repositories you want to use in CodeCatalyst. The default option is to include all GitHub repositories in the GitHub account, including future repositories that will be accessed by CodeCatalyst. 1. Review the permissions given to CodeCatalyst, and then choose **Install**. After connecting your GitHub account to CodeCatalyst, you're taken to the **GitHub repositories** extension details page, where you can view and manage connected GitHub accounts and linked GitHub repositories. + **Bitbucket repositories**: Connect to a Bitbucket workspace. 1. In the **Connected Bitbucket workspaces** tab, choose **Connect Bitbucket workspace** to go to the external site for Bitbucket. 1. Sign into your Bitbucket workspace using your Bitbucket credentials and review the permissions given to CodeCatalyst. 1. From the **Authorize for workspace** dropdown menu, choose the Bitbucket workspace you want to provide CodeCatalyst access to, and then choose **Grant access**. **Tip** If you have previously connected a Bitbucket workspace to the space, you will not be prompted to reauthorize. You will instead see a dialog asking you where you would like to install the extension if you're a member or collaborator in more than one Bitbucket workspace, or the configuration page for the Amazon CodeCatalyst application if you only belong to one Bitbucket workspace. Configure the application for the workspace access you want to allow, and then choose **Grant access**. If the **Grant access** button is not active, make a change to the configuration, and then try again. After connecting your Bitbucket workspace to CodeCatalyst, you're taken to the **Bitbucket repositories** extension details page, where you can view and manage connected Bitbucket workspaces and linked Bitbucket repositories. + **GitLab repositories**: Connect to a GitLab user. 1. Choose **Connect GitLab user** to go to the external site for GitLab. 1. Sign in to your GitLab user using your GitLab credentials and review the permissions given to CodeCatalyst. **Tip** If you have previously connected a GitLab user to the space, you will not be prompted to reauthorize. You will instead be navigated back to the CodeCatalyst console. 1. Choose **Authorize AWS Connector for GitLab**. After connecting your GitLab user to CodeCatalyst, you're taken to the **GitLab repositories** extension details page, where you can view and manage connected GitLab user and linked GitLab project repositories. + **Jira Software**: Connect a Jira site. 1. In the **Connected Jira sites** tab, choose **Connect Jira site** to go to the external site for Atlassian Marketplace. 1. Choose **Get it now** to get started with installing CodeCatalyst on your Jira site. **Note** If you previously installed CodeCatalyst to your Jira site, you will be notified. Choose **Get started** to be taken to the final step. 1. Depending on your role, do one of the following: 1. If you are a Jira site administrator, from the site dropdown menu, choose the Jira site to install the CodeCatalyst application, and then choose **Install app**. **Note** If you have one Jira site, this step won't appear, and you'll automatically be directed to the next step. 1. 1. If you aren't a Jira administrator, from the site dropdown menu, choose the Jira site to install the CodeCatalyst application, and then choose **Request app**. For more information on installing Jira apps, see [Who can install apps?](https://www.atlassian.com/licensing/marketplace#who-can-install-apps). 1. Enter the reason you need to install CodeCatalyst into the input text field or keep the default text, and then choose **Submit request**. 1. Review the actions performed by CodeCatalyst when the application is installed, and then choose **Get it now**. 1. After the application is installed, choose **Return to CodeCatalyst** to return to CodeCatalyst. After connecting your Jira site to CodeCatalyst, you can view the connected site in the **Connected Jira sites** tab of the **Jira Software** extension details page. ## Step 3: Link your third-party resources to your CodeCatalyst project The third and final step to using your GitHub repositories, Bitbucket repositories, or GitLab project repositories or manage Jira issues in CodeCatalyst is to link them to the CodeCatalyst project in which you want to use it. **To link a GitHub repository, Bitbucket repository, GitLab project repository, or Jira project to a CodeCatalyst project from the extension details page** + Do one of the following depending on the third-party extension you installed and provider you connected: + **GitHub repositories**: Link a GitHub repository. 1. In the **Linked GitHub repositories** tab, choose **Link GitHub repository**. 1. From the **GitHub account** dropdown, choose the GitHub account that contains the repository that you want to link. 1. From the **GitHub repository** dropdown, choose the repository you want to link to a CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the space. 1. (Optional) If you don't see a GitHub repository in the list of repositories, it might not have been configured for repository access in the Amazon CodeCatalyst application in GitHub. You can configure which GitHub repositories can be used in CodeCatalyst in the connected account. 1. Navigate to your [GitHub](https://github.com/) account, choose **Settings**, and then choose **Applications**. 1. In the **Installed GitHub Apps** tab, choose **Configure** for the Amazon CodeCatalyst application. 1. Do one of the following to configure access of GitHub repositories you want to link in CodeCatalyst: + To provide access to all current and future repositories, choose **All repositories**. + To provide access to specific repositories, choose **Only select repositories**, choose the **Select repositories** dropdown, and then choose a repository you want to allow to link in CodeCatalyst. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link the GitHub repository to. 1. Choose **Link**. If you no longer want to use a GitHub repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a repository is unlinked, events in that repository will not start workflow runs, and you will not be able to use that repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). + **Bitbucket repositories**: Link a Bitbucket repository. 1. In the **Linked Bitbucket repositories** tab, choose **Link Bitbucket repository**. 1. From the **Bitbucket workspace** dropdown, choose the Bitbucket workspace that contains the repository that you want to link. 1. From the **Bitbucket repository** dropdown, choose the repository you want to link to a CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the space. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link the Bitbucket repository to. 1. Choose **Link**. If you no longer want to use a Bitbucket repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a repository is unlinked, events in that repository will not start workflow runs, and you will not be able to use that repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). + **GitLab repositories**: Link a GitLab project repository. 1. In the **Linked GitLab project repositories** tab, choose **Link GitLab project repository**. 1. From the **GitLab user** dropdown, choose the GitLab user that contains the repository that you want to link. 1. From the **GitLab project repository** dropdown, choose the repository you want to link to a CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the space. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link the GitLab project repository to. 1. Choose **Link**. If you no longer want to use a GitLab project repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a project repository is unlinked, events in that project repository will not start workflow runs, and you will not be able to use that project repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). + **Jira Software**: Link a Jira project. 1. In the **Linked Jira projects** tab, choose **Link Jira project**. 1. From the **Jira site** dropdown menu, choose the Jira site that contains the project that you want to link. 1. From the **Jira project** dropdown menu, choose the project you want to link to a CodeCatalyst project. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link to a Jira project. 1. Choose **Link**. Once a Jira project is linked to a CodeCatalyst project, access to CodeCatalyst issues is disabled entirely, and **Issues** in the CodeCatalyst navigation pane will be replaced with a **Jira issues** item that links to the Jira project. ![\[CodeCatalyst issues replaced with linked Jira issues in navigation pane.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/jira-issues-nav.png) If you no longer want to use a Jira project in CodeCatalyst, you can unlink it from your CodeCatalyst project. When a Jira project is unlinked, Jira issues will not be available in the CodeCatalyst project, and CodeCatalyst **Issues** will be the issue provider again. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). You can also link your GitHub repository, Bitbucket repository, or GitLab project repository to a project from **Source repositories** in **Code**. For more information, see [Linking resources from connected third-party providers](extensions-link.md#extensions-link-resources). ## Next steps After installing the **GitHub repositories**, **Bitbucket repositories**, or **GitLab repositories** extension, connecting your resource provider, and linking your third-party repositories to your CodeCatalyst projects, you can use it in CodeCatalyst workflows and Dev Environments. You can also create third-party repositories in the connected GitHub account, Bitbucket workspace, or GitLab user with code generated from a blueprint. For more information, see [Automatically starting a workflow run after third-party repository events](extensions-workflow-repositories.md) and [Creating a Dev Environment](devenvironment-create.md). After installing the **Jira Software** extension, connecting your Jira site, linking your Jira projects to your CodeCatalyst project, and linking a pull request, updates from CodeCatalyst are reflected in your Jira project. For more information about linking pull requests to Jira issues, see [Linking Jira issues to CodeCatalyst pull requests](link-jira-issues-pull-requests.md). For more information on viewing CodeCatalyst events in Jira, see [Viewing CodeCatalyst events in Jira issues](view-codecatalyst-events-jira.md). # Installing an extension in a space You can install extensions for your CodeCatalyst space that add functionality to projects in that space. You can view the CodeCatalyst catalog by choosing the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png). To learn more about the extensions and their functionalities, see [Available third-party extensions](extensions.md#extensions-types). **Important** To install an extension, you must be signed in with an account that has the **Space administrator** role in the space. **Important** After you install a repository extension, any repositories you link to CodeCatalyst will have their code indexed and stored in CodeCatalyst. This will make the code searchable in CodeCatalyst. To better understand the data protection for your code when using linked repositories in CodeCatalyst, see [Data protection](https://docs.aws.amazon.com/codecatalyst/latest/userguide/data-protection.html) in the *Amazon CodeCatalyst User Guide*. **To install an extension from the CodeCatalyst catalog** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Navigate to the CodeCatalyst catalog by choosing the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. You can search for **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software**. You can also filter extensions based on categories. 1. (Optional) Choose the name of the extension to see more details about the extension, such as the permissions the extension will have. 1. Choose **Install**. Review the permissions required by the extension, and if you want to continue, choose **Install** again. After installing an extension, you will see the details page for the installed extension. Browse the tabs for more information about the extension. The details page is also where you will perform further configuration of the extension if needed. # Uninstalling an extension in a space You can uninstall extensions that were previously installed in your CodeCatalyst space. Uninstalling an extension may remove resources related to that extension from your CodeCatalyst space or projects. **Important** To uninstall an extension, you must be signed in with an account that has the **Space administrator** role in the space. **To uninstall an extension from your CodeCatalyst space** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Do one of the following to view a list of the installed extensions for your space: 1. Choose **Settings**, and then choose **Installed extensions**. 1. Choose the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. 1. Choose **Configure** on the extension you want to uninstall. 1. Choose **Uninstall** on the extension details page. 1. Review the information in the **Uninstall extension** dialog box. Follow the instructions, and then choose **Uninstall** to uninstall the extension. # Connecting GitHub accounts, Bitbucket workspaces, GitLab users, and Jira sites CodeCatalyst To use a GitHub repository, Bitbucket repository, or GitLab project repository or manage a Jira project in CodeCatalyst, you must first connect your third-party source to your CodeCatalyst space. To learn more about the extensions and their functionalities, see [Available third-party extensions](extensions.md#extensions-types). **Important** To connect your GitHub account, Bitbucket workspace, GitLab user, or Jira site to your CodeCatalyst space, you must be both the third-party source's administrator and the CodeCatalyst **Space administrator**. **Note** If you're using a connection to a GitHub account, you must create a personal connection to establish identity mapping between your CodeCatalyst identity and your GitHub identity. For more information, see [Personal connections](concepts.md#personal-connection-concept) and [Accessing GitHub resources with personal connections](ipa-settings-connections.md). **To connect your GitHub account, Bitbucket workspace, GitLab user, or Jira site to CodeCatalyst** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Do one of the following to view a list of the installed extensions for your space: 1. Choose **Settings**, and then choose **Installed extensions**. 1. Choose the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. 1. Choose **Configure** for one of the following extensions you want to configure: **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software**. 1. Do one of the following depending on the third-party extension you chose to configure: + **GitHub repositories**: Connect to a GitHub account. 1. In the **Connected GitHub accounts** tab, choose **Connect GitHub account** to go to the external site for GitHub. 1. Sign in to your GitHub account using your GitHub credentials, and then choose the account where you want to install Amazon CodeCatalyst. **Tip** If you have previously connected a GitHub account to the space, you will not be prompted to reauthorize. You will instead see a dialog box asking you where you would like to install the extension if you are a member or collaborator in more than one GitHub space, or the configuration page for the Amazon CodeCatalyst application if you only belong to one GitHub space. Configure the application for the repository access that you want to allow, and then choose **Save**. If the **Save** button is not active, make a change to the configuration, and then try again. 1. Choose whether you want to allow CodeCatalyst to access all current and future repositories, or choose the specific GitHub repositories you want to use in CodeCatalyst. The default option is to include all GitHub repositories in the GitHub account, including future repositories that will be accessed by CodeCatalyst. 1. Review the permissions given to CodeCatalyst, and then choose **Install**. After connecting your GitHub account to CodeCatalyst, you're taken to the **GitHub repositories** extension details page, where you can view and manage connected GitHub accounts and linked GitHub repositories. + **Bitbucket repositories**: Connect to a Bitbucket workspace. 1. In the **Connected Bitbucket workspaces** tab, choose **Connect Bitbucket workspace** to go to the external site for Bitbucket. 1. Sign into your Bitbucket workspace using your Bitbucket credentials and review the permissions given to CodeCatalyst. 1. From the **Authorize for workspace** dropdown menu, choose the Bitbucket workspace you want to provide CodeCatalyst access to, and then choose **Grant access**. **Tip** If you have previously connected a Bitbucket workspace to the space, you will not be prompted to reauthorize. You will instead see a dialog asking you where you would like to install the extension if you're a member or collaborator in more than one Bitbucket workspace, or the configuration page for the Amazon CodeCatalyst application if you only belong to one Bitbucket workspace. Configure the application for the workspace access you want to allow, and then choose **Grant access**. If the **Grant access** button is not active, make a change to the configuration, and then try again. After connecting your Bitbucket workspace to CodeCatalyst, you're taken to the **Bitbucket repositories** extension details page, where you can view and manage connected Bitbucket workspaces and linked Bitbucket repositories. + **GitLab repositories**: Connect to a GitLab user. 1. Choose **Connect GitLab user** to go to the external site for GitLab. 1. Sign in to your GitLab user using your GitLab credentials and review the permissions given to CodeCatalyst. **Tip** If you have previously connected a GitLab user to the space, you will not be prompted to reauthorize. You will instead be navigated back to the CodeCatalyst console. 1. Choose **Authorize AWS Connector for GitLab**. After connecting your GitLab user to CodeCatalyst, you're taken to the **GitLab repositories** extension details page, where you can view and manage connected GitLab user and linked GitLab project repositories. + **Jira Software**: Connect a Jira site. 1. In the **Connected Jira sites** tab, choose **Connect Jira site** to go to the external site for Atlassian Marketplace. 1. Choose **Get it now** to get started with installing CodeCatalyst on your Jira site. **Note** If you previously installed CodeCatalyst to your Jira site, you will be notified. Choose **Get started** to be taken to the final step. 1. Depending on your role, do one of the following: 1. If you are a Jira site administrator, from the site dropdown menu, choose the Jira site to install the CodeCatalyst application, and then choose **Install app**. **Note** If you have one Jira site, this step won't appear, and you'll automatically be directed to the next step. 1. 1. If you aren't a Jira administrator, from the site dropdown menu, choose the Jira site to install the CodeCatalyst application, and then choose **Request app**. For more information on installing Jira apps, see [Who can install apps?](https://www.atlassian.com/licensing/marketplace#who-can-install-apps). 1. Enter the reason you need to install CodeCatalyst into the input text field or keep the default text, and then choose **Submit request**. 1. Review the actions performed by CodeCatalyst when the application is installed, and then choose **Get it now**. 1. After the application is installed, choose **Return to CodeCatalyst** to return to CodeCatalyst. After connecting your Jira site to CodeCatalyst, you can view the connected site in the **Connected Jira sites** tab of the **Jira Software** extension details page. If you no longer want to use GitHub repositories, Bitbucket repositories, or GitLab project repositories, or manage Jira issues in CodeCatalyst, you can disconnect your third-party source. When a GitHub account, Bitbucket workspace, or GitLab user is disconnected, events in the third-party repositories will not start workflow runs, and you will not be able to use those repositories with CodeCatalyst Dev Environments. When a Jira site is disconnected, Jira issues from the site's projects will not be available in the CodeCatalyst projects, and CodeCatalyst **Issues** will be the issue provider again. For more information, see [Disconnecting GitHub accounts, Bitbucket workspaces, GitLab users, and Jira sites CodeCatalyst](extensions-disconnect.md). # Disconnecting GitHub accounts, Bitbucket workspaces, GitLab users, and Jira sites CodeCatalyst If you no longer want to use GitHub repositories, Bitbucket repositories, or GitLab project repositories, or manage Jira issues in CodeCatalyst, you can disconnect your third-party source. Once a GitHub account, Bitbucket workspace, or GitLab user is disconnected, events in the repositories will not start workflow runs, and you will not be able to use those repositories with CodeCatalyst Dev Environments. When a Jira site is disconnected, Jira issues from the site's projects will not be available in the CodeCatalyst projects, and CodeCatalyst **Issues** will be the issue provider again. **Note** To disconnect a GitHub account, you must first unlink all linked GitHub repositories from that account. To disconnect a Bitbucket workspace, you must first unlink all linked Bitbucket repositories from that workspace. To disconnect a GitLab user, you must first unlink all linked GitLab project repositories from that workspace. To disconnect a Jira site, you must first unlink all linked Jira projects from that account. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). **To disconnect a GitHub project, Bitbucket workspace, GitLab user, or Jira site** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Do one of the following to view a list of the installed extensions for your space: 1. Choose **Settings**, and then choose **Installed extensions**. 1. Choose the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. 1. Choose **Configure** for one of the following extensions you want to configure: **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software**. 1. Do one of the following depending on the third-party extension you chose to configure: + **GitHub repositories**: Disonnect to a GitHub account. In the **Connected GitHub accounts** tab, choose the GitHub account you want to disconnect, and then choose **Disconnect GitHub account**. + **Bitbucket repositories**: Disonnect to a Bitbucket workspace. In the **Connected Bitbucket workspaces** tab, choose the Bitbucket workspace you want to disconnect, and then choose **Disconnect Bitbucket workspace**. + **GitLab repositories**: Disonnect to a GitLab user. In the **Connected GitLab users** tab, choose the GitLab user you want to disconnect, and then choose **Disconnect GitLab user**. + **Jira Software**: Disonnect to a Jira site. In the **Connected Jira sites** tab, choose the Jira site you want to disconnect, and then choose **Disconnect Jira site**. 1. In the **Disconnect** dialog box, review the effects of disconnecting the account. 1. Enter **disconnect** into the text input field, and then choose **Disconnect**. # Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst Before you can use a GitHub repository, Bitbucket repository, or GitLab project repository, or manage a Jira project, you must connect the third-party source that the repository or project belongs to with your CodeCatalyst space. For more information, see [Connecting GitHub accounts, Bitbucket workspaces, GitLab users, and Jira sites CodeCatalyst](extensions-connect.md). You can use linked GitHub repositories, Bitbucket repositories, or GitLab project repositories in workflows, where events in the linked repositories start workflows that might build, test, or deploy code, depending on the workflow configuration. Workflow configuration files for workflows that use linked GitHub or Bitbucket repositories are stored in the linked repositories. Linked repositories can also be used with Dev Environments to create, update, and delete files in the linked repositories. You can link a GitHub repository, Bitbucket repository, or GitLab project repository to a CodeCatalyst project from either the details page of the **GitHub repositories**, **Bitbucket repositories**, or **GitLab repositories** extension, or from the **Source repositories** view in **Code** in the project itself. **Important** While you can link a GitHub or Bitbucket repository as a **Contributor**, you can only unlink a third-party repository as the **Space administrator** or the **Project administrator**. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). **Important** After you install a repository extension, any repositories you link to CodeCatalyst will have their code indexed and stored in CodeCatalyst. This will make the code searchable in CodeCatalyst. To better understand the data protection for your code when using linked repositories in CodeCatalyst, see [Data protection](https://docs.aws.amazon.com/codecatalyst/latest/userguide/data-protection.html) in the *Amazon CodeCatalyst User Guide*. **Important** CodeCatalyst doesn't support detecting changes in the default branch for linked repositories. To change the default branch for a linked repository, you must first unlink it from CodeCatalyst, change the default branch, and then link it again. As a best practice, always make sure you have the latest version of the extension before you link a repository. You can use linked Jira projects to manage issues and to link CodeCatalyst pull requests to a Jira issue. Summary status of a pull request and the status of associated CodeCatalyst workflow events are reflected in your Jira issue. **Important** To link your Jira project to your CodeCatalyst project, you must be the CodeCatalyst **Space administrator** or CodeCatalyst **Project administrator**. **Note** A GitHub repository, Bitbucket repository, or GitLab project repository can only be linked to one CodeCatalyst project in a space. You can't use empty or archived GitHub repositories, Bitbucket repositories, or GitLab project repositories with CodeCatalyst projects. You can't link a GitHub repository, Bitbucket repository, or GitLab repository that has the same name as a repository in a CodeCatalyst project. The **GitHub repositories** extension isn't compatible with GitHub Enterprise Server repositories. The **Bitbucket repositories** extension isn't compatible with Bitbucket Data Center repositories. The **GitLab repositories** extension isn't compatible with GitLab self-managed project repositories. You can't use the **Write description for me** or **Summarize comments** features with linked repositories. These features are only available in pull requests in CodeCatalyst. A CodeCatalyst project can only be linked to one Jira project. A Jira project can be linked to multiple CodeCatalyst projects. **Topics** + [ ## Linking resources from connected third-party providers ](#extensions-link-resources) + [ ## Linking a third-party repository to during CodeCatalyst project creation ](#extensions-link-repositories-creation) ## Linking resources from connected third-party providers **To link a GitHub repository, Bitbucket repository, GitLab project repository, or Jira project to a CodeCatalyst project from the extension details page** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Do one of the following to view a list of the installed extensions for your space space: 1. Choose **Settings**, and then choose **Installed extensions**. 1. Choose the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. 1. Choose **Configure** for one of the following extensions: **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software**. 1. Do one of the following depending on the third-party extension you chose to configure: + **GitHub repositories**: Link a GitHub repository. 1. In the **Linked GitHub repositories** tab, choose **Link GitHub repository**. 1. From the **GitHub account** dropdown, choose the GitHub account that contains the repository that you want to link. 1. From the **GitHub repository** dropdown, choose the repository you want to link to a CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the space. 1. (Optional) If you don't see a GitHub repository in the list of repositories, it might not have been configured for repository access in the Amazon CodeCatalyst application in GitHub. You can configure which GitHub repositories can be used in CodeCatalyst in the connected account. 1. Navigate to your [GitHub](https://github.com/) account, choose **Settings**, and then choose **Applications**. 1. In the **Installed GitHub Apps** tab, choose **Configure** for the Amazon CodeCatalyst application. 1. Do one of the following to configure access of GitHub repositories you want to link in CodeCatalyst: + To provide access to all current and future repositories, choose **All repositories**. + To provide access to specific repositories, choose **Only select repositories**, choose the **Select repositories** dropdown, and then choose a repository you want to allow to link in CodeCatalyst. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link the GitHub repository to. 1. Choose **Link**. If you no longer want to use a GitHub repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a repository is unlinked, events in that repository will not start workflow runs, and you will not be able to use that repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). + **Bitbucket repositories**: Link a Bitbucket repository. 1. In the **Linked Bitbucket repositories** tab, choose **Link Bitbucket repository**. 1. From the **Bitbucket workspace** dropdown, choose the Bitbucket workspace that contains the repository that you want to link. 1. From the **Bitbucket repository** dropdown, choose the repository you want to link to a CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the space. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link the Bitbucket repository to. 1. Choose **Link**. If you no longer want to use a Bitbucket repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a repository is unlinked, events in that repository will not start workflow runs, and you will not be able to use that repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). + **GitLab repositories**: Link a GitLab project repository. 1. In the **Linked GitLab project repositories** tab, choose **Link GitLab project repository**. 1. From the **GitLab user** dropdown, choose the GitLab user that contains the project repository that you want to link. 1. From the **GitLab project repository** dropdown, choose the repository you want to link to a CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the space. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link the GitLab project repository to. 1. Choose **Link**. If you no longer want to use a GitLab project repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a project repository is unlinked, events in that project repository will not start workflow runs, and you will not be able to use that project repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). + **Jira Software**: Link a Jira project. 1. In the **Linked Jira projects** tab, choose **Link Jira project**. 1. From the **Jira site** dropdown menu, choose the Jira site that contains the project that you want to link. 1. From the **Jira project** dropdown menu, choose the project you want to link to a CodeCatalyst project. 1. From the **CodeCatalyst project** dropdown menu, choose the CodeCatalyst project you want to link to a Jira project. 1. Choose **Link**. Once a Jira project is linked to a CodeCatalyst project, access to CodeCatalyst issues is disabled entirely, and **Issues** in the CodeCatalyst navigation pane will be replaced with a **Jira issues** item that links to the Jira project. ![\[CodeCatalyst issues replaced with linked Jira issues in navigation pane.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/jira-issues-nav.png) If you no longer want to use a Jira project in CodeCatalyst, you can unlink it from your CodeCatalyst project. When a Jira project is unlinked, Jira issues will not be available in the CodeCatalyst project, and CodeCatalyst **Issues** will be the issue provider again. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). **To link a GitHub repository, Bitbucket repository, or GitLab project repository to a CodeCatalyst project from the source repositories page in a project** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst project. 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose **Add repository**, and then choose **Link repository**. 1. From the **Repository provider** dropdown menu, choose one of the following third-party repository providers: **GitHub**, **Bitbucket**, **GitLab**. 1. Do one of the following depending on the third-party repository provider you chose to link: + **GitHub repositories**: Link a GitHub repository. 1. From the **GitHub account** dropdown menu, choose the GitHub account that contains the repository that you want to link. 1. From the **GitHub repository** dropdown menu, choose the GitHub repository you want to link your CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the Amazon CodeCatalyst. 1. (Optional) If you don't see a GitHub repository in the list of repositories, it might not have been configured for repository access in the Amazon CodeCatalyst application in GitHub. You can configure which GitHub repositories can be used in CodeCatalyst in the connected account. 1. Navigate to your [GitHub](https://github.com/) account, choose **Settings**, and then choose **Applications**. 1. In the **Installed GitHub Apps** tab, choose **Configure** for the Amazon CodeCatalyst application. 1. Do one of the following to configure access of GitHub repositories you want to link in CodeCatalyst: + To provide access to all current and future repositories, choose **All repositories**. + To provide access to specific repositories, choose **Only select repositories**, choose the **Select repositories** dropdown, and then choose a repository you want to allow to link in CodeCatalyst. + **Bitbucket repositories**: Link a Bitbucket repository. 1. From the **Bitbucket workspace** dropdown menu, choose the Bitbucket workspace that contains the repository that you want to link. 1. From the **Bitbucket repository** dropdown menu, choose the Bitbucket repository you want to link your CodeCatalyst project. **Tip** If the name of the repository is greyed out, you can't link that repository because it has already been linked to another project in the Amazon CodeCatalyst. + **GitLab repositories**: Link a GitLab project repository. 1. From the **GitLab user** dropdown menu, choose the GitLab user that contains the project repository that you want to link. 1. From the **GitLab project repository** dropdown menu, choose the GitLab project repository you want to link your CodeCatalyst project. **Tip** If the name of the project repository is greyed out, you can't link that project repository because it has already been linked to another project in the Amazon CodeCatalyst. 1. Choose **Link**. If you no longer want to use a GitHub repository, Bitbucket repository, or GitLab project repository in CodeCatalyst, you can unlink it from a CodeCatalyst project. When a repository is unlinked, events in that repository will not start workflow runs, and you will not be able to use that repository with CodeCatalyst Dev Environments. For more information, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). After linking your GitHub repository, Bitbucket repository, or GitLab project repository to your CodeCatalyst project, you can use it in CodeCatalyst workflows and Dev Environments. You can also use the linked repositories with Amazon Q Developer, blueprints, and more. For more information, see [Automatically starting a workflow run after third-party repository events](extensions-workflow-repositories.md) and [Creating a Dev Environment](devenvironment-create.md). After linking your Jira project to your CodeCatalyst project, and linking a pull request, updates from CodeCatalyst are reflected in your Jira project. For more information about linking pull requests to Jira issues, see [Linking Jira issues to CodeCatalyst pull requests](link-jira-issues-pull-requests.md). For more information on viewing CodeCatalyst events in Jira, see [Viewing CodeCatalyst events in Jira issues](view-codecatalyst-events-jira.md). ## Linking a third-party repository to during CodeCatalyst project creation You can link a GitHub repository, Bitbucket repository, or GitLab project respository to a new CodeCatalyst project when creating the new CodeCatalyst project. For more information, see [Creating a project with a linked third-party repository](projects-create.md#projects-create-3p-repo). # Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst If you no longer want to use a GitHub repository, Bitbucket repository, or GitLab project repository, or manage a Jira project in CodeCatalyst, you can unlink the repository or project from your CodeCatalyst project. Unlinking a GitHub repository, Bitbucket repository, or GitLab project repository doesn't delete the repository or make any changes to it. It doesn't delete any workflow configuration files stored in that linked repository. However, once you unlink a GitHub repository, Bitbucket repository, or GitLab project repository, events in that repository will no longer start workflow runs, and you can't use the repository with Dev Environments. You can unlink a GitHub repository, Bitbucket repository, or GitLab project repository from a CodeCatalyst project from either the details page of the **GitHub repositories**, **Bitbucket repositories**, or **GitLab repositories** extension, or from the **Source repositories** view in **Code** in the project itself. Unlinking a Jira project doesn't delete the project, including planning items or development information, or make any changes to it. However, once you unlink a Jira project, the project's Jira issues will no longer be available to link to the CodeCatalyst project, and CodeCatalyst **Issues** will be the issue provider again. **Important** To unlink your GitHub repository, Bitbucket repository, or Gitlab project repository from your CodeCatalyst project, you must be the **Space administrator** or the **Project administrator**. **To unlink a GitHub repository, Bitbucket repository, GitLab project repository, or Jira project in a CodeCatalyst project from the extension details page** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space. 1. Do one of the following to view a list of the installed extensions for your space: 1. Choose **Settings**, and then choose **Installed extensions**. 1. Choose the **Catalog** icon ![\[The CodeCatalyst catalog icon in the top navigation bar in CodeCatalyst.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/integrations/marketplace-icon.png) in the top menu. 1. Choose **Configure** for one of the following extensions you want to configure: **GitHub repositories**, **Bitbucket repositories**, **GitLab repositories**, or **Jira Software**. 1. Do one of the following depending on the third-party extension you chose to configure: + **GitHub repositories**: Unlink a GitHub repository. In the **GitHub repositories** tab, choose the GitHub repository you want to unlink, and then choose **Unlink GitHub repository**. + **Bitbucket repositories**: Unlink a Bitbucket repository. In the **Bitbucket repositories** tab, choose the Bitbucket repository you want to unlink, and then choose **Unlink Bitbucket repository**. + **GitLab repositories**: Unlink a GitLab project repository. In the **GitLab project repositories** tab, choose the GitLab project repository you want to unlink, and then choose **Unlink GitLab project repository**. + **Jira Software**: Unlink a Jira project. In the **Jira projects** tab, choose the Jira project you want to unlink, and then choose **Unlink Jira project**. 1. In the **Unlink** dialog box, review the effects of unlinking the repository. 1. Enter **unlink** into the text input field and choose **Unlink**. **To unlink a GitHub repository, Bitbucket repository, or GitLab project repository in a CodeCatalyst project from the source repositories page** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst project. 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose the radio button of the repository you want to unlink, and then choose **Unlink repository**. 1. Review the information in the dialog box. Follow the instructions, and then choose **Unlink** to unlink the repository. # Viewing third-party repositories and searching Jira issues in CodeCatalyst After linking GitHub repositories, Bitbucket repositories, or GitLab project repositories, you can view them in CodeCatalyst to confirm and configure the resources. You can also search for linked Jira issues in CodeCatalyst. **Topics** + [ ## Viewing third-party repositories in CodeCatalyst ](#extensions-view-repositories) + [ ## Searching Jira issues in CodeCatalyst ](#extensions-search-issues) ## Viewing third-party repositories in CodeCatalyst You can view the linked GitHub repositories, Bitbucket repositories, or GitLab project repositories in the list of source repositories for your project or from the **GitHub repositories**, **Bitbucket repositories**, or **GitLab repositories** extension details page. Choosing them from the list of repositories doesn't open them in CodeCatalyst. Instead, they open in the third-party repository provider, where you can view and work on the code in the linked repository. **To view linked GitHub repositories, Bitbucket repositories, or GitLab project repositories in CodeCatalyst** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst project. 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. **To view linked GitHub repositories, Bitbucket repositories, or GitLab project repositories from the extension details page** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst space, and then choose the **Installed extensions** tab. 1. Depending on the third-party repositories you want to view, do one of the following: + In **GitHub repositories**, choose **Configure**, and then choose **Linked GitHub repositories** to view all GitHub repositories connected to CodeCatalyst projects in your CodeCatalyst space. + In **Bitbucket repositories**, choose **Configure**, and then choose **Linked Bitbucket repositories** to view all Bitbucket repositories connected to CodeCatalyst projects in your CodeCatalyst space. + In **GitLab repositories**, choose **Configure**, and then choose **Linked GitLab project repositories** to view all GitLab project repositories connected to CodeCatalyst projects in your CodeCatalyst space. The GitHub repositories, Bitbucket repositories, or GitLab project repositories that are linked to your CodeCatalyst project are shown in the list. Choose the GitHub repository, Bitbucket repository, or GitLab project repository to view and edit files in the third-party repository provider. **Note** If a workflow uses a GitHub repository, Bitbucket repository, or GitLab project repository in a source action, changes you make to the workflow YAML in the visual editor or the YAML editor in CodeCatalyst will be automatically committed and pushed to the third-party repository. ## Searching Jira issues in CodeCatalyst After linking a Jira project, you can search the linked Jira project for issues using the CodeCatalyst global search bar. You can also search for Jira issues in CodeCatalyst while linking to the issues from a pull request. For more information about linking Jira issues to a CodeCatalyst pull request, see [Linking Jira issues to CodeCatalyst pull requests](link-jira-issues-pull-requests.md). **To search for Jira issues in linked Jira projects** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst project. 1. In the global search bar, search a linked Jira project for issues or Jira issues you want to link to a pull request. # Automatically starting a workflow run after third-party repository events You can use a linked GitHub repository, Bitbucket repository, or GitLab project repository as the source for a workflow, where changes to a specified branch in a linked GitHub repository, Bitbucket repository, or GitLab project repository automatically start a workflow run. A *workflow* is an automated procedure that describes how to build, test, and deploy your code as part of a continuous integration and continuous delivery (CI/CD) system. A workflow defines a series of steps, or *actions*, to take during a workflow run. A workflow also defines the events, or *triggers*, that cause the workflow to start. To set up a workflow, you create a *workflow definition file* using the CodeCatalyst console's [visual or YAML editor](https://docs.aws.amazon.com//codecatalyst/latest/userguide/flows.html#workflow.editors). **Tip** For a quick look at how you might use workflows in a project, [create a project with a blueprint](https://docs.aws.amazon.com//codecatalyst/latest/userguide/projects-create.html#projects-create-console-template). Each blueprint deploys a functioning workflow that you can review, run, and experiment with. When you configure a workflow to use a linked GitHub repository, Bitbucket repository, or GitLab project repository, the workflow configuration file is stored in that GitHub repository, Bitbucket repository, or GitLab project repository. The workflow configuration is a YAML file that defines the workflow name, triggers, resources, artifacts, and actions. For more information about the workflow configuration file, see [Workflow YAML definition](workflow-reference.md). The workflow configuration file must be in the `./codecatalyst/workflows/` directory in your GitHub repository, Bitbucket repository, or GitLab project repository. You can use the workflow editor to create and configure workflows. For more information see [Getting started with workflows](workflows-getting-started.md) and [Connecting source repositories to workflows](workflows-sources.md). ## Adding triggers to start workflow runs You can configure a CodeCatalyst workflow to automatically start a run when code is pushed to the specified branch of your GitHub or Bitbucket repository. To start a workflow run automatically, add a trigger to the `Triggers` section of the workflow configuration file. ### Example: A simple code push trigger The following example shows a trigger that starts a workflow run whenever code is pushed to any branch in your source repository. ``` Triggers: - Type: PUSH ``` ### Example: A simple pull request trigger The following example shows a trigger that starts a workflow run whenever a pull request is created against any branch in your source repository. ``` Triggers: - Type: PULLREQUEST Events: - OPEN ``` For more information, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). # Restricting IP access with third-party repository providers You can restrict access to your GitHub repositories, Bitbucket repositories, or GitLab project repositories based on IP addresses by setting up rules or configurations. You can do this through the third-party provider's settings or access control features. Depending on which third-party repository provider you're using, see one of the following: + The Amazon CodeCatalyst **GitHub repositories** extension is compatible with [ GitHub Enterprise Cloud IP access restrictions](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization). When configuring a GitHub Enterprise Cloud organization to restrict access to specific IP addresses, you can also [enable GitHub apps to configure the allow list](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps), which will let CodeCatalyst register its IP addresses automatically with GitHub. Alternatively, you can [manually add the CodeCatalyst IP addresses](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address). + The Amazon CodeCatalyst **Bitbucket repositories** extension is compatible with [ Bitbucket Cloud Premium access restrictions](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/). When configuring a Bitbucket Cloud Premium workspace to restrict access to specific IP addresses, you can also [add IP addresses or network blocks for a set of IP addresses to an allowlist](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/#Allowlisting-IP-addresses). + The Amazon CodeCatalyst **GitLab repositories** extension is compatible with [ GitLab IP address restrictions](https://docs.gitlab.com/ee/administration/reporting/ip_addr_restrictions.html). When configuring a GitLab Premium or Ultimate group to restrict access to specific IP addresses, you can also [add IP addresses or network blocks for a set of IP addresses to an allowlist](https://docs.gitlab.com/ee/user/group/access_and_permissions.html). If the CodeCatalyst IP addresses aren't in a third-party repository's allowlist, the Amazon CodeCatalyst app won't be able to access your third-party repositories. For more information, see [IP addresses used by third-party repositories extension](#codecatalyst-ip-address). ## IP addresses used by third-party repositories extension The following IP addresses are used by the third-party extensions to access your third-party resources: + **GitHub repositories**: ``` us-west-2 52.32.242.246 54.148.176.49 35.164.118.94 eu-west-1 34.241.64.10 34.246.255.80 3.248.38.7 ``` + **Bitbucket repositories** and **GitLab repositories**: ``` us-west-2 35.160.210.199 54.71.206.108 54.71.36.205 eu-west-1 34.242.64.82 52.18.37.201 54.77.75.62 ``` # Blocking third-party merges when workflows fail After linking a GitHub or Bitbucket repository to CodeCatalyst, you can add CodeCatalyst workflows for pull requests. Similarly, after linking a GitLab project repository to CodeCatalyst you can add CodeCatalyst workflows for merge requests. One or more workflow runs can occur on a specific commit, and the run status of each workflow in CodeCatalyst is also reflected as part of the commit status in GitHub, Bitbucket, or GitLab. When a new commit is pushed, new workflow [run statuses](https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-view-run.html#workflows-view-run-status) are reflected in GitHub, Bitbucket, or GitLab for that new commit. If you run a workflow again for a commit, the new workflow run status overrides the previous status for that commit and workflow. You can set branch protection rules in GitHub or Bitbucket to block a pull request merge, or in GitLab to block a merge request, when the latest commit has a failed workflow run status. With branch protection rules, the status of the latest commit affects the ability to merge a pull request in GitHub, Bitbucket, or GitLab. To learn more about workflows, see [Running a workflow](workflows-working-runs.md) and [Starting a workflow run automatically using triggers](workflows-add-trigger.md). Depending on which third-party repository provider you're using, see the following: + **GitHub repositories**: GitHub’s documentation [About status checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) and [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). + **Bitbucket repositories**: Bitbucket’s documentation for [Using branch permissions](https://confluence.atlassian.com/bitbucketserver/using-branch-permissions-776639807.html) and [Take control with branch permissions in Bitbucket Cloud](https://bitbucket.org/blog/take-control-with-branch-restrictions). + **GitLab repositories**: GitLab’s documentation for [Auto merge](https://docs.gitlab.com/ee/user/project/merge_requests/auto_merge.html) and [Protected branches](https://docs.gitlab.com/ee/user/project/protected_branches.html). # Linking Jira issues to CodeCatalyst pull requests You can link pull requests that are created in a CodeCatalyst source repository to Jira issues. After linking a Jira issue, the issue is displayed as a property of the pull request. As a result, pull request events, workflow events, and deployment events are sent to Jira and added to the Jira issue. Pull requests can be linked to one or more Jira issues. You can only link pull requests that are in a CodeCatalyst source repository, not those in a third-party repository like GitHub. Before you can link Jira issues to a pull request, your Jira project must be linked to the CodeCatalyst project. For more information about linking a Jira project to a CodeCatalyst project, see [Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-link.md). **Note** You can't create a pull request without a source repository with two branches in your CodeCatalyst project. For more information on pull requests, see [ Working with pull requests in CodeCatalyst](source-pull-requests.md). **To link Jira issues to a CodeCatalyst pull request** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst project. 1. In the navigation pane, choose **Code**, and then choose **Pull requests**. 1. Choose **Create pull request** to enter the pull request details. 1. From the **Source repository** drop-down menu, choose the source repository in which you want to link a pull request. 1. From the **Source branch** drop-down menu, choose the branch that contains the changes you want reviewed. 1. From the **Destination branch** drop-down menu, choose the branch where you want to merge reviewed changes. 1. In the **Pull request title** text input field, enter the title of your pull requests. 1. Choose **Link issues** for the **Jira issues - *optional*** field, choose the drop-down, and search the Jira issues you want to add from the linked Jira project. 1. Select the Jira issues you want to add to the pull request. 1. Choose **Create** to create the pull request. Once you link Jira issues to a CodeCatalyst pull request, a summary of the pull request is available. The summary includes workflow runs, linked issues, required reviewers, optional reviewers, and the author. **Note** **Assignee** and **Created by** information associated with the Jira issue is not available in CodeCatalyst. After linking a pull request, the synced CodeCatalyst project and Jira project allow updates from CodeCatalyst to be reflected in your Jira project. The status of the linked pull request and any workflow events related to the pull request will show up in the Jira issue when viewing it in Jira. For more information on viewing CodeCatalyst events in Jira, see [Viewing CodeCatalyst events in Jira issues](view-codecatalyst-events-jira.md). # Viewing CodeCatalyst events in Jira issues If your CodeCatalyst projects and Jira projects are linked, the summary status of the pull request and the status of associated CodeCatalyst workflow events are reflected in your Jira issue. For example, if you close or merge a pull request in CodeCatalyst, the status update is reflected in the Jira issue. CodeCatalyst workflow CI/CD events related to a CodeCatalyst pull request are synchronized, so a successful workflow run would be sent to the Jira issue as well. **To view CodeCatalyst events in a Jira issue** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your CodeCatalyst project. 1. In the CodeCatalyst navigation pane, choose **Code**, choose **Pull requests**, and then choose the pull request with the Jira issue that you want to view in your Jira project. 1. In the **Additional info** pane, choose the Jira issue that you want to view in your Jira project. 1. From the **Details** pane in the Jira project, choose **pull request** listed for **Development** to see details of the pull request. 1. (Optional) To see the latest builds, choose the **Builds** tab. 1. (Optional) To see the development status, choose the **Deployments** tab.