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). # Store and collaborate on code with source repositories in CodeCatalyst CodeCatalyst source repositories are Git repositories hosted in Amazon CodeCatalyst. You can use source repositories in CodeCatalyst to securely store, version, and manage assets for a project. Assets in a CodeCatalyst repository can include: + documents + source code + binary files CodeCatalyst also uses the source repository for a project to store configuration information for your project, such as workflow configuration files. You can have more than one source repository in a CodeCatalyst project. For example, you might want to have separate source repositories for front-end source code, back-end source code, utilities, and documentation. Here is one possible workflow for working with code in source repositories, pull requests, and Dev Environments in CodeCatalyst: Mary Major creates a web application project in CodeCatalyst using a blueprint, which creates a source repository with sample code in it. She invites her friends Li Juan, Saanvi Sarkar, and Jorge Souza to work on the project with her. Li Juan looks at the sample code in the source repository and decides to make some quick changes to add a test to the code. Li creates a Dev Environment, chooses AWS Cloud9 as the IDE, and specifies a new branch, *test-code*. The Dev Environment opens. Li quickly adds the code, then commits and pushes the branch with the changes to the source repository in CodeCatalyst. Li then creates a pull request. As part of creating that pull request, Li adds Jorge Souza and Saanvi Sarkar as reviewers to ensure that the code is reviewed. While reviewing the code, Jorge Souza remembers that he has his own project repository on GitHub that contains a prototype of the app they're working on. He asks Mary Major to install and configure the extension that will allow him to link the GitHub repository to the project as an additional source repository. Mary reviews the repository on GitHub and works with Jorge to configure the GitHub extension so that he can link the GitHub repository as an additional source repository for the project. CodeCatalyst source repositories support the standard functionality of Git and work with your existing Git-based tools. You can create and use personal access tokens (PATs) as an application-specific password when cloning and working with source repositories from a Git client or integrated development environments (IDEs). These PATs are associated with your CodeCatalyst user identity. For more information, see [Grant users repository access with personal access tokens](ipa-tokens-keys.md). CodeCatalyst source repositories support pull requests. This is a simple way for you and other project members to review and comment on code changes before you merge them from one branch to another. You can view the changes in the CodeCatalyst console and comment on lines of code. Pushes to branches in a CodeCatalyst source repository can automatically start a run in a workflow, where changes can be built, tested, and deployed. If your source repository was created as part of a project using a project template, one or more workflows are configured for you as part of the project. You can add additional workflows for repositories at any time. The YAML configuration files for workflows in a project are stored in the source repositories configured in the source action for those workflows. For more information, see [Getting started with workflows](workflows-getting-started.md). **Topics** + [ # Source repository concepts ](source-concepts.md) + [ # Setting up for working with source repositories ](source-setting-up.md) + [ # Getting started with CodeCatalyst source repositories and the Single-page application blueprint ](source-getting-started.md) + [ # Storing source code in repositories for a project in CodeCatalyst ](source-repositories.md) + [ # Organizing your source code work with branches in Amazon CodeCatalyst ](source-branches.md) + [ # Managing source code files in Amazon CodeCatalyst ](source-files.md) + [ # Reviewing code with pull requests in Amazon CodeCatalyst ](source-pull-requests.md) + [ # Understanding changes in source code with commits in Amazon CodeCatalyst ](source-commits.md) + [ # Quotas for source repositories in CodeCatalyst ](source-quotas.md) # Source repository concepts Here are some concepts to know about as you work with CodeCatalyst source repositories. **Topics** + [ ## Projects ](#project-concept) + [ ## Source repositories ](#source-repository-concept) + [ ## Dev Environments ](#devenvironment-concept) + [ ## Personal access tokens (PATs) ](#personal-access-token-concept) + [ ## Branches ](#branches-concept) + [ ## Default branches ](#default-branch-concept) + [ ## Commits ](#commits-concept) + [ ## Pull requests ](#pull-request-concept) + [ ## Revisions ](#revision-concept) + [ ## Workflows ](#workflow-concept) ## Projects A *project* represents a collaborative effort in CodeCatalyst that supports development teams and tasks. After you have a project, you can add, update, or remove users and resources, customize your project dashboard, and monitor the progress of your team's work. You can have multiple projects within a space. Source repositories are specific to the projects where you create or link them in a space. You can't share a repository between projects, and you can't link a repository to more than one project in a space. Users with the **Contributor** or **Project administrator** role in a project can interact with the source repositories associated with that project according to the permissions granted to those roles. For more information, see [Granting access with user roles](ipa-roles.md). ## Source repositories A *source repository* is where you securely store code and files for your project. It also stores the version history of your files. By default, a source repository is shared with the other users in your CodeCatalyst project. You can have more than one source repository for a project. You can create source repositories for projects in CodeCatalyst, or you can choose to link an existing source repository hosted by another service if that service is supported by an installed extension. For example, you can link a GitHub repository to a project after you install the **GitHub Repositories** extension. For more information, see [Storing source code in repositories for a project in CodeCatalyst](source-repositories.md) and [Quickstart: Installing extensions, connecting providers, and linking resources in CodeCatalyst](extensions-quickstart.md). ## Dev Environments A *Dev Environment* is a cloud-based development environment that you can use in CodeCatalyst to quickly work on the code stored in the source repositories of your project. The project tools and application libraries included in your Dev Environment are defined by a devfile in the source repository of your project. If you do not have a devfile in your source repository, a default devfile will be applied automatically. The default devfile includes tools for the most frequently used programming languages and frameworks. By default, a Dev Environment is configured to have a 2-core processor, 4 GB of RAM, and 16 GiB of persistent storage. You can choose to clone an existing branch of your source repository into your Dev Environment, or you can choose to create a new branch as part of creating the Dev Environment. ## Personal access tokens (PATs) A *personal access token* (PAT) is similar to a password. It is associated with your user identity for use across all spaces and projects in CodeCatalyst. You use PATs to access CodeCatalyst resources that include integrated development environments (IDEs) and Git-based source repositories. PATs represent you in CodeCatalyst and you can manage them in your user settings. A user can have more than one PAT. Personal access tokens only display once. As a best practice, be sure to store them securely on your local computer. By default, PATs expire after one year. When working with integrated development environments (IDEs), PATs are the equivalent of a Git password. Provide the PAT when asked for a password when setting up your IDE to work with a Git repository. For more information about how to connect your IDE with a Git-based repository, see the documentation for your IDE. ## Branches A *branch* is a pointer or reference to a commit in Git and in CodeCatalyst. You can use branches to organize your work. For example, you can use branches to work on a new or different version of files without affecting files in other branches. You can use branches to develop new features, store a specific version of your project, and more. A source repository can have one branch or many branches. When you create a project using a template, the source repository created for the project contains sample files in a branch called **main**. The **main** branch is the default branch for the repository. ## Default branches Source repositories in CodeCatalyst have a default branch regardless of how you create them. If you choose to create a project using a template, the source repository created for that project includes a README.md file in addition to sample code, workflow definitions, and other resources. If you create a source repository without using a template, a README.md file is added for you as a first commit and a default branch is created for you as part of creating the repository. This default branch is named *main*. This default branch is the one used as the base or default branch in local repositories (repos) when users clone the repository. You can change which branch is used as the default branch. For more information, see [Managing the default branch for a repository](source-branches-default-branch.md). You can't delete the default branch for a source repository. Search results only include results from the default branch. ## Commits A *commit* is a change to a file or set of files. In the Amazon CodeCatalyst console, a commit saves your changes and pushes them to a source repository. The commit includes information about the change, including the identity of the user who made the change, the time and date of the change, the commit title, and any message included about the change. For more information, see [Understanding changes in source code with commits in Amazon CodeCatalyst](source-commits.md). In the context of a source repository in CodeCatalyst, commits are snapshots of the contents and changes to the contents of your repository. You can also add Git tags to commits, to identify specific commits. ## Pull requests A *pull request* is the primary way you and other users review, comment on, and merge code changes from one branch to another in a source repository. You can use pull requests to review code changes collaboratively for minor changes or fixes, major feature additions, or new versions of your released software. In a pull request, you can review the changes between the source and destination branches or the differences between revisions of those branches. You can add comments to individual lines of code changes as well as comments on the pull request overall. **Tip** While you are creating a pull request, the difference displayed is the difference between the tip of the source branch and the tip of the destination branch. Once the pull request has been created, the displayed difference will be between the revision of the pull request you choose and the commit that was the tip of the destination branch when you created the pull request. For more information about differences and merge bases in Git, see [git-merge-base](https://git-scm.com/docs/git-merge-base) in the Git documentation. ## Revisions A *revision* is an updated version of a pull request. Each push to the source branch of a pull request creates a revision that contains the changes made in the commits included in that push. You can view the differences between revisions of a pull request in addition to the differences between the source and destination branches. For more information, see [Reviewing code with pull requests in Amazon CodeCatalyst](source-pull-requests.md). ## Workflows 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. A source repository can also store the configuration files and other information for workflows, notifications, issues, and other configuration information for the project. The configuration files are created and stored in the source repository when you create resources that require configuration files, or when you specify the repository as a source action for a workflow. If you create a project from a blueprint, you will have configuration files already stored in the source repository created for you as part of the project. This configuration information is stored in a folder named `.codecatalyst` in the default branch of your repository. Whenever you create a branch of the default branch, you create a copy of this folder and its configuration in addition to all the other files and folders in that branch. # Setting up for working with source repositories When you work with source repositories in Amazon CodeCatalyst on your local machine, you can use Git either on its own or in a supported integrated development environment (IDE) to make code changes and push and pull your code. As a best practice, we recommend that you use the latest versions of Git and other software. **Note** If you use Dev Environments, you do not have to install Git. A recent version of Git is included in your Dev Environment. **Version compatibility information for CodeCatalyst** | Component | Version | | --- | --- | | Git | latest | ## Install Git To work with files, commits, branches, and other information in source repositories from a Git client without an IDE, install Git on your local machine. To install Git, we recommend websites such as [Git Downloads](http://git-scm.com/downloads). ## Create a personal access token To clone source repositories to your local machine or to your preferred IDE, you must create a personal access token (PAT). **To create a personal access token (PAT)** 1. In the top menu bar, choose your profile badge, and then choose **My settings**. **Tip** You can also find your user profile by going to the members page for a project or space and choosing your name from the members list. 1. In **PAT name**, enter a descriptive name for your PAT. 1. In **Expiration date**, leave the default date or choose the calendar icon to select a custom date. The expiration date defaults to one year from the current date. 1. Choose **Create**. You can also create this token when you choose **Clone repository** for a source repository. 1. Save the PAT secret in a secure location. **Important** The PAT secret only displays once. You cannot retrieve it after you close the window. # Getting started with CodeCatalyst source repositories and the Single-page application blueprint Follow the steps in this tutorial to learn how to work with source repositories in Amazon CodeCatalyst. The quickest way to get started working with source repositories in Amazon CodeCatalyst is to create a project using a template. When you create a project using a template, resources are created for you, including a source repository that includes sample code. You can use this repository and code example to learn how to: + View a project's source repositories and browse their contents + Create a Dev Environment with a new branch where you can work on code + Change a file, and commit and push your changes + Create a pull request and review your code changes with other project members + See the workflow for your project automatically build and test the changes in the source branch of the pull request + Merge your changes from your source branch into the destination branch and close the pull request + See the merged changes automatically built and deployed To get the most out of this tutorial, invite others to your project so you can work together on a pull request. You can also explore additional features in CodeCatalyst, such as creating issues and associating them with a pull request, or configuring notifications and getting alerts when the associated workflow runs. For a full exploration of CodeCatalyst, see [Getting started tutorials](getting-started-topnode.md). ## Creating a project with a blueprint Creating a project is the first step in being able to work together. You can use a blueprint to create your project, which will also create a source repository with sample code and a workflow that will automatically build and deploy your code when you change it. In this tutorial, we'll walk you through a project created with the **Single-page application** blueprint, but you can follow the procedures for any project with a source repository. Make sure to choose an IAM role or add an IAM role if you don't have one as part of creating the project. We recommend that you use the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** service role for this project. If you already have a project, you can skip ahead to [Viewing the repositories for a project](#source-getting-started-source-view). **Note** Only users with the Space administrator or **Power user** role can create projects in CodeCatalyst. If you do not have this role and you need a project to work on for this tutorial, ask someone with one of these roles to create a project for you and add you to the created project. For more information, see [Granting access with user roles](ipa-roles.md). **To create a project with a blueprint** 1. In the CodeCatalyst console, navigate to the space where you want to create a project. 1. On the space dashboard, choose **Create project**. 1. Choose **Start with a blueprint**. **Tip** You can choose to add a blueprint by giving **Amazon Q** your project requirements to have Amazon Q suggest a blueprint to you. For more information, see [Using Amazon Q to choose a blueprint when creating a project or adding functionality](getting-started-project-assistance.md#getting-started-project-assistance-create-apply-bp) and [Best practices when using Amazon Q to create projects or add functionality with blueprints](projects-create.md#projects-create-amazon-q). This feature is only available in the US West (Oregon) Region. This functionality requires that generative AI features are enabled for the space. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html). 1. From the **CodeCatalyst blueprints** or **Space blueprints** tab, choose a blueprint, and then choose **Next**. 1. Under **Name your project**, enter the name that you want to assign to your project and its associated resource names. The name must be unique within your space. 1. (Optional) By default, the source code created by the blueprint is stored in a CodeCatalyst repository. Alternatively, you can choose to store the blueprint's source code in a third-party repository. For more information, see [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md). **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. Do one of the following depending on the third-party repository provider you want to use: + **GitHub repositories**: Connect a GitHub account. Choose the **Advanced** dropdown menu, choose GitHub as the repository provider, and then choose the GitHub account where you want to store the source code created by the blueprint. **Note** If you're connecting 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). + **Bitbucket repositories**: Connect a Bitbucket workspace. Choose the **Advanced** dropdown menu, choose Bitbucket as the repository provider, and then choose the Bitbucket workspace where you want to store the source code created by the blueprint. + **GitLab repositories**: Connect a GitLab user. Choose the **Advanced** dropdown menu, choose GitLab as the repository provider, and then choose the GitLab user where you want to store the source code created by the blueprint. 1. Under **Project resources**, configure the blueprint parameters. Depending on the blueprint, you may have the option to name the source repository name. 1. (Optional) To view definition files with updates based on the project parameter selections you made, choose **View code** or **View workflow** from **Generate project preview**. 1. (Optional) Choose **View details** from the blueprint's card to view specific details about the blueprint, such as an overview of the blueprint's architecture, required connections and permissions, and the kind of resources the blueprint creates. 1. Choose **Create project**. The project overview page opens as soon as you create a project or accept an invitation to a project and complete the sign-in process. The project overview page for a new project contains no open issues or pull requests. You can optionally choose to create an issue and assign it to yourself. You can also choose to invite someone else to your project. For more information, see [Creating an issue in CodeCatalyst](issues-create-issue.md) and [Inviting a user to a project](projects-members.md#projects-members-add). ## Viewing the repositories for a project As a member of a project, you can view the source repositories for the project. You can also choose to create additional repositories. If someone with the **Space administrator** role has installed and configured the **GitHub repositories**, **Bitbucket repositories**, or **GitLab repositories** extension, you can also add links to third-party repositories in the GitHub accounts, Bitbucket workspaces, or GitLab users configured for the extension. For more information, see [Creating a source repository](source-repositories-create.md) and [Quickstart: Installing extensions, connecting providers, and linking resources in CodeCatalyst](extensions-quickstart.md). **Note** For projects created with the Single-page application blueprint, the default name for the source repository that contains the sample code is ***spa-app***. **To navigate to the source repositories for a project** 1. Navigate to your project, and do one of the following: + On the summary page for your project, choose the repository you want from the list, and then choose **View repository**. + In the navigation pane, choose **Code**, and then choose **Source repositories**. In **Source repositories**, choose the name of the repository from the list. You can filter the list of repositories by typing part of the repository name in the filter bar. 1. On the home page for the repository, view the contents of the repository and information about the associated resources such as the number of pull requests and workflows. By default, the contents for the default branch are shown. You can change the view by choosing a different branch from the drop-down list. The overview page for the repository includes information about the workflows and pull requests that are configured for the branches of this repository and its files. If you just created the project, the initial workflows to build, test, and deploy the code will still be running, as they take a few minutes to complete. You can view the related workflows and their status by choosing the number beneath **Related workflows**, but this opens the **Workflows** page in **CI/CD**. For this tutorial, stay on the overview page and explore the code in the repository. The contents of the `README.md` file are rendered on this page below the repository files. In **Files**, the contents of the default branch are shown. You can change the file view to show the contents of another branch if you have one. The `.codecatalyst` folder contains code used for other parts of the project, such as workflow YAML files. To view the content of folders, choose the arrow next to the folder name to expand it. For example, choose the arrow next to `src` to view the files for the single-page web application contained in that folder. To view the contents of a file, choose it from the list. This will open **View files**, where you can browse the contents of multiple files. You can edit single files in the console as well, but to edit multiple files, you'll want to create a Dev Environment. ## Creating a Dev Environment You can add and change files in a source repository in the Amazon CodeCatalyst console. However, to work effectively with multiple files and branches, we recommend using a Dev Environment or cloning the repository to your local computer. In this tutorial, we'll create an AWS Cloud9 Dev Environment with a branch named **develop**. You can choose a different branch name, but by naming the branch **develop**, a workflow will automatically run to build and test your code when you create a pull request later in this tutorial. **Tip** If you decide to clone a repository locally instead of or in addition to using a Dev Environment, make sure that you have Git on your local computer or that your IDE includes Git. For more information, see [Setting up for working with source repositories](source-setting-up.md). **To create a Dev Environment with a new branch** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to the project where you want to create a Dev Environment. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, choose **Source repositories**, and choose the repository for which you want to create a Dev Environment. 1. On the repository home page, choose **Create Dev Environment**. 1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](devenvironment-create.md#devenvironment-supported-ide) for more information. 1. Choose the repository to clone, choose **Work in new branch**, enter a branch name into the **Branch name** field, and choose a branch off of which to create the new branch from the **Create branch from** drop-down menu. 1. Optionally, add an alias for the Dev Environment. 1. Optionally, choose the **Dev Environment configuration** edit button to edit the Dev Environment's compute, storage, or timeout configuration. 1. Choose **Create**. While your Dev Environment is being created, the Dev Environment status column will display **Starting**, and the status column will display **Running** once the Dev Environment has been created. A new tab will open with your Dev Environment in the IDE of your choice. You can edit code and commit and push your changes. Once you've created the Dev Environment, you can edit files, commit your changes, and push your changes to the **test** branch. For this tutorial, edit the content between the `

` tags in `App.tsx` file in the `src` folder to change the text that's displayed on the webpage. Commit and push your change, and then return to the CodeCatalyst tab. ## To make and push a change from an AWS Cloud9 Dev Environment 1. In AWS Cloud9, expand the side navigation menu to browse the files. Expand `src`, and open `App.tsx`. 1. Make a change the text inside the `

` tags. 1. Save the file, and then commit and push your changes by using the Git menu. Alternatively, in the terminal window, commit and push your changes with the **git commit** and **git push** commands. ``` git commit -am "Making an example change" git push ``` **Tip** You might need to change directories in the terminal to the Git repository directory before you can successfully run the Git commands. ## Creating a pull request You can use pull requests to review code changes collaboratively for minor changes or fixes, major feature additions, or new versions of your released software. In this tutorial, you will create a pull request to review the changes you made to the *test* branch compared to the **main** branch. Creating a pull request in a project created with a template will also start a run of its associated workflows, if any. **To create a pull request** 1. Navigate to your project. 1. Do one of the following: + In the navigation pane, choose **Code**, choose **Pull requests**, and then choose **Create pull request**. + On the repository home page, choose **More**, and then choose **Create pull request**. + On the project page, choose **Create pull request**. 1. In **Source repository**, make sure that the specified source repository is the one that contains the committed code. This option only appears if you did not create the pull request from the repository's main page. 1. In **Destination branch**, choose the branch to merge the code into after it is reviewed. 1. In **Source branch**, choose the branch that contains the committed code. 1. In **Pull request title**, enter a title that helps other users understand what needs to be reviewed and why. 1. (Optional) In **Pull request description**, provide information such as a link to issues or a description of your changes. **Tip** You can choose **Write description for me** to have CodeCatalyst automatically generate a description of the changes contained in the pull request. You can make changes to the automatically generated description after you add it to the pull request. This functionality requires that generative AI features are enabled for the space and is not available for pull requests in linked repositories. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html). 1. (Optional) In **Issues**, choose **Link issues**, and then either choose an issue from the list or enter its ID. To unlink an issue, choose the unlink icon. 1. (Optional) In **Required reviewers**, choose **Add required reviewers**. Choose from the list of project members to add them. Required reviewers must approve the changes before the pull request can be merged into the destination branch. **Note** You cannot add a reviewer as both a required reviewer and an optional reviewer. You cannot add yourself as a reviewer. 1. (Optional) In **Optional reviewers**, choose **Add optional reviewers**. Choose from the list of project members to add them. Optional reviewers do not have to approve the changes as a requirement before the pull request can be merged into the destination branch. 1. Review the differences between the branches. The difference displayed in a pull request is the changes between the revision in the source branch and the merge base, which is the head commit of the destination branch at the time the pull request was created. If no changes display, the branches might be identical, or you might have chosen the same branch for both the source and the destination. 1. When you are satisfied that the pull request contains the code and changes you want reviewed, choose **Create**. **Note** After you create the pull request, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resources, such as files, by using the @ sign followed by the name of the file. You can view information about associated workflows started by the creation of this pull request by choosing **Overview** and then reviewing the information in the **Pull request details** area under **Workflow runs**. To view the workflow run, choose the run. **Tip** If you named your branch something other than **develop**, a workflow will not automatically run to build and test your changes. If you want to configure that, edit the YAML file for the **onPullRequestBuildAndTest** workflow. For more information, see [Creating a workflow](workflows-create-workflow.md). You can comment on this pull request and ask other project members to comment on it. You can also choose to add or change optional or required reviewers. You can choose to make more changes to the source branch for the repository, and see how those committed changes create revisions for the pull request. For more information, see [Reviewing a pull request](pull-requests-review.md), [Updating a pull request](pull-requests-update.md), [Reviewing code with pull requests in Amazon CodeCatalyst](source-pull-requests.md), and [Viewing workflow run status and details](workflows-view-run.md) . ## Merging a pull request Once a pull request has been reviewed and has received approvals from required reviewers, you can merge its source branch to the destination branch in the CodeCatalyst console. Merging a pull request will also start a run of the changes through any workflows associated with the destination branch. In this tutorial, you'll merge the test branch into main, which will start a run of the **onPushToMainDeployPipeline** workflow. **To merge a pull request (console)** 1. In **Pull requests**, choose the pull request you created in the previous step. In the pull request, choose **Merge**. 1. Choose from the available merge strategies for the pull request. Optionally select or deselect the option to delete the source branch after merging the pull request, and then choose **Merge**. After the merge completes, the status of the pull request changes to **Merged** and no longer appears in the default view of pull requests. The default view shows pull requests with a status of **Open**. You can still view a merged pull request, but you cannot approve it or change its status. **Note** If the **Merge** button is not active, or you see the **Not mergeable** label, either a required reviewer has not yet approved the pull request, or the pull request cannot be merged in the CodeCatalyst console. A reviewer who has not approved a pull request is indicated by a clock icon in **Overview** in the **Pull request details** area. If all required reviewers have approved the pull request but the **Merge** button is still not active, you might have a merge conflict, or you have exceeded the storage quota for the space. You can resolve merge conflicts for the destination branch in a Dev Environment, push the changes, and then merge the pull request, or you can resolve conflicts and merge locally, and then push the commit that contains the merge to CodeCatalyst. For more information, see [Merging a pull request (Git)](pull-requests-merge.md#pull-requests-merge-git) and your Git documentation. ## Viewing the deployed code Now it's time to view the originally deployed code that was in the default branch, and your merged changes once they are automatically built, tested, and deployed. To do so, you can return to the overview page for the repository and choose the number next to the related workflows icon, or in the navigation pane, choose **CI/CD**, and then choose **Workflows**. **To view the deployed code** 1. In **Workflows**, in `onPushToMainDeployPipeline`, expand **Recent runs**. **Note** This is the default name of the workflow for projects created with the **Single-page application** blueprint. 1. The most recent run is the one started by your merged pull request commit to the `main` branch and will likely show a status of **In progress**. Choose a successfully completed run from the list to open the details of that run. 1. Choose **Variables**. Copy the value for **AppURL**. This is the URL for the deployed single page web application. Open a new browser tab and paste in the value to view the built and deployed code. Leave the tab open. 1. Return to the list of workflow runs and wait for the most recent run to complete. When it does, return to the tab you opened to view the web application and refresh your browser. You should see the changes that you made in your merged pull request. ## Cleaning up resources Once you've explored working with a source repository and pull request, you might want to remove any resources you don't need. You cannot delete pull requests, but you can close them. You can delete any branches you created. If you no longer need the source repository or the project, you can also delete those resources. For more information, see [Deleting a source repository](source-repositories-delete.md) and [Deleting a project](projects-delete.md). # Storing source code in repositories for a project in CodeCatalyst A source repository is where you securely store code and files for your project. It also stores your source history, from the first commit through the latest changes. If you choose a blueprint that includes a source repository, that repository also contains the configuration files and other information for workflows and notifications for the project. This configuration information is stored in a folder named **.codecatalyst**. You can create a source repository in CodeCatalyst either by creating a project with a blueprint that creates a source repository as part of creating a project, or by creating a source repository in an existing project. Project users will automatically see and be able to use the repositories you create for a project. You can also choose to link a Git repository hosted on GitHub, Bibucket, or GitLab to your project. When you do so, your project users can view and access that linked repository in the list of repositories for the project. **Note** Before you can link the repository, you must install the extension for the service that hosts it. You cannot link an archived repository. While you can link an empty repository, you can't use it in CodeCatalyst until you have initialized it with an initial commit that creates a default branch. For more information, see [Installing an extension in a space](install-extension.md). By default, a source repository is shared with other members of your Amazon CodeCatalyst project. You can create additional source repositories for a project or link repositories to the project. All members of a project can view, add, edit, and delete files and folders in the project's source repositories. To quickly work on code in a source repository, you can create a Dev Environment that clones a specified repository and branch into it where you can work on the code in the integrated development environment (IDE) you choose for the Dev Environment. You can clone a source repository on your local computer and pull and push changes between your local repo and the remote repository in CodeCatalyst. You can also work with source repositories by configuring access to them in your preferred IDE as long as that IDE supports credential management. Repository names must be unique within a CodeCatalyst project. **Topics** + [ # Creating a source repository ](source-repositories-create.md) + [ # Cloning an existing Git repository into a source repository ](source-repositories-add-existing.md) + [ # Linking a source repository ](source-repositories-link.md) + [ # Viewing a source repository ](source-repositories-view.md) + [ # Editing the settings for a source repository ](source-repositories-edit.md) + [ # Cloning a source repository ](source-repositories-clone.md) + [ # Deleting a source repository ](source-repositories-delete.md) # Creating a source repository When you create a project using a blueprint in Amazon CodeCatalyst, CodeCatalyst creates a source repository for you. That source repository contains sample code in addition to configuration information for the workflows and other resources created for you. This is the recommended way to get started with repositories in CodeCatalyst. You can choose to create repositories for a project. Those repositories will contain a **README.md** file that you can edit or delete at any time. Depending on your choices when you create a source repository, repositories might also contain a `.gitignore` file. If you want to clone an existing Git repository into a CodeCatalyst source repository, consider creating an empty repository instead. This repository will be unavailable for use in CodeCatalyst until you add content to it, which you can do with a few simple Git commands. Alternatively, you can add content to the empty repository directly from the CodeCatalyst console. Alternatively, you can link a source repository in a supported Git repository provider. For more information, see [Linking a source repository](source-repositories-link.md). **To create a source repository** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your project. 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose **Add repository**, and then choose **Create repository**. 1. In **Repository name**, provide a name for the repository. In this guide, we use *codecatalyst-source-repository*, but you can choose a different name. Repository names must be unique within a project. For more information about requirements for repository names, see [Quotas for source repositories in CodeCatalyst](source-quotas.md). 1. (Optional) In **Description**, add a description for the repository that will help other users in the project understand what the repository is used for. 1. Choose **Create repository (default)**. This option creates a repository that includes a default branch and a README.md file. Unlike an empty repository, you can use this repository as soon as it's created. 1. In **Default branch**, leave the name as *main* unless you have a reason to choose a different name. The examples in this guide all use the name *main* for the default branch. 1. (Optional) Add a `.gitignore` file for the type of code you plan to push. 1. Choose **Create**. **Note** CodeCatalyst adds a `README.md` file to your repository when you create it. CodeCatalyst also creates an initial commit for the repository in a default branch named **main**. You can edit or delete the README.md file, but you can't delete the default branch. **To create an empty source repository** 1. In the CodeCatalyst console, navigate to the project where you want to create an empty repository. 1. On the summary page for your project, in **Source repositories**, choose **Add repository**, and then choose **Create repository**. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose **Add repository**, and then choose **Create repository**. 1. In **Repository name**, provide a name for the repository. In this guide, we use *codecatalyst-source-repository*, but you can choose a different name. Repository names must be unique within a project. For more information about requirements for repository names, see [Quotas for source repositories in CodeCatalyst](source-quotas.md). 1. (Optional) In **Description**, add a description for the repository that will help other users in the project understand what the repository is used for. 1. Choose **Create empty repository**, and then choose **Create**. # Cloning an existing Git repository into a source repository You can clone an existing Git repository to an empty source repository in Amazon CodeCatalyst. This is a quick way to get started in CodeCatalyst with code that was previously hosted in another Git repository provider. You can clone the contents of the repository by creating a mirror clone and then pushing the mirror to CodeCatalyst. Alternatively, if you have a local repo of the repository whose contents you want to add to CodeCatalyst, you can add the CodeCatalyst source repository as another remote to the local repo, and then push to the empty source repository. Both approaches are equally valid. Using a mirror clone not only maps branches, it maps all refs. It's a simple and clean way to create a working copy of the repository in CodeCatalyst. Adding a remote to a local repo that points to an empty CodeCatalyst source repository will add the repository contents to CodeCatalyst, but it will also allow you to make pushes from the local repo to both the CodeCatalyst source repository and the original Git remote repository. This can be useful if you want to maintain the code in different remote repositories, but can lead to conflicts if other developers are committing code to only one of the remotes. The following procedures use basic Git commands to accomplish this task. There are many ways to accomplish tasks in Git, including cloning. For more information, see the [Git documentation.](https://git-scm.com/docs/git-clone) **Important** You must create an empty repository in CodeCatalyst before you can clone content to it. You must also have a personal access token. For more information, see [To create an empty source repository](source-repositories-create.md#source-repositories-create-empty) and [Create a personal access token](source-setting-up.md#source-setting-up-pat). **To use `git clone --mirror` to clone an existing Git repository into CodeCatalyst** 1. In the CodeCatalyst console, navigate to the project where you created an empty repository. 1. On the summary page for your project, choose the empty repository from the list, and then choose **View repository**. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the name of the empty repository from the list of source repositories for the project. 1. Copy the HTTPS clone URL of the empty repository. You'll need this for pushing the mirror clone. For example, if you named the source repository MyExampleRepo in the MyExampleProject project in the ExampleCorp space, and your user name is LiJuan, your clone URL might look like the following: ``` https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo ``` 1. At a command line or terminal window, use the `git clone --mirror` command to create a mirror clone of the Git repository you want to clone to CodeCatalyst. For example, if you want to create a mirror clone of the codecatalyst-blueprints repository in GitHub, you would enter the following command: ``` git clone --mirror https://github.com/aws/codecatalyst-blueprints.git ``` 1. Change directories to the directory where you made the clone. ``` cd codecatalyst-blueprints.git ``` 1. Run the **git push** command, specifying the URL and name of the destination CodeCatalyst source repository and the **--all** option. (This is the URL you copied in Step 3.) For example: ``` git push https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo --all ``` **To add a remote and push a local repo into CodeCatalyst** 1. In the CodeCatalyst console, navigate to the project where you created an empty repository. 1. On the summary page for your project, choose the empty repository from the list, and then choose **View repository**. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the name of the empty repository from the list of source repositories for the project. 1. Copy the HTTPS clone URL of the empty repository. You'll need this for pushing the mirror clone. For example, if you named the source repository MyExampleRepo in the MyExampleProject project in the ExampleCorp space, and your user name is LiJuan, your clone URL might look like the following: ``` https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo ``` 1. At a command line or terminal window, change directories to the local repo you want to push to CodeCatalyst. 1. Run the git remote -v command to see the existing remotes for the local repository. For example, if you are cloning a local repo of a AWS CodeCommit repository named **MyDemoRepo** in the US East (Ohio) Region, your command output might look like this: ``` origin https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyDemoRepo (fetch) origin https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyDemoRepo (push) ``` Copy the remote URL if you want to continue using the repository. 1. Use the `git remote remove` command to remove the CodeCommit repository URLs for fetch and push for origin: ``` git remote remove origin ``` 1. Use the **git remote add** command to add the CodeCatalyst source repository URL as the fetch and push remote for your local repo. For example: ``` git remote add origin https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo ``` This replaces the CodeCommit repository push URL with CodeCatalyst source repository URL, but does not change the fetch URL. So if you run the git remote -v command again, you'll see that you're now pulling (fetch) code from the CodeCommit remote repository, but you're configured to push changes from your local repo to the CodeCatalyst source repository: ``` origin https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyDemoRepo (fetch) origin https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo (push) ``` You can optionally add back the CodeCommit remote URL if you want to push to both repositories with the `git remote set-url` command: ``` git remote set-url --add --push origin https://git-codecommit.us-east-2.amazonaws.com/v1/repos/MyDemoRepo ``` 1. Run the `git push` command to push the local repo to all configured push remotes. Alternatively, run the **git push -u -origin** command, specifying the **--all** option to push the local repo to both repositories. For example: ``` git push -u -origin --all ``` **Tip** Depending on your version of Git, --all might not work to push all branches of the local repo to the empty repository. You might have to check out and push each branch separately. # Linking a source repository When linking a source repository to a project, you can include repositories that have a CodeCatalyst extension for the service that hosts the repository, if that extension is installed for your space. Only users with the Space administrator role can install extensions. Once the extension is installed, you can link to repositories configured for access by that extension. For more information, see [Installing an extension in a space](install-extension.md) or follow [Linking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-link.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*. You can link a repository to only one project in a space. You cannot link an archived repository. While you can link an empty repository, you can't use it in CodeCatalyst until you have initialized it with an initial commit that creates a default branch. Additionally: + 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. 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). **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. **To link a source repository** 1. Navigate to the project where you want to link a repository. **Note** Before you can link a repository, a user with the Space administrator role must first install the extension for the provider that hosts the repository. For more information, see [Installing an extension in a space](install-extension.md). 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** or **Bitbucket**. 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 account you want to link your CodeCatalyst project. 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. 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). # Viewing a source repository You can view the source repositories associated with a project in Amazon CodeCatalyst. For source repositories in CodeCatalyst, the overview page for a repository provides a quick overview of information and activity in that repository, including: + The description of the repository, if any + The number of branches in the repository + The number of open pull requests for the repository + The number of related workflows for the repository + The files and folders in the default branch, or the branch that you choose + The title, author, and date of the last commit to the displayed branch + The contents of the README.md file rendered in Markdown, if any README.md file is included This page also provides links to the commits, branches, and pull requests for the repository, as well as a quick way to open, view, and edit individual files. **Note** You cannot view this information about linked repositories in the CodeCatalyst console. To view information about linked repositories, choose the link in the list of repositories to open that repository in the service that hosts it. **To navigate to the source repositories for a project** 1. Navigate to your project, and do one of the following: + On the summary page for your project, choose the repository you want from the list, and then choose **View repository**. + In the navigation pane, choose **Code**, and then choose **Source repositories**. In **Source repositories**, choose the name of the repository from the list. You can filter the list of repositories by typing part of the repository name in the filter bar. 1. On the home page for the repository, view the contents of the repository and information about the associated resources such as the number of pull requests and workflows. By default, the contents for the default branch are shown. You can change the view by choosing a different branch from the drop-down list. **Tip** You can also quickly navigate to your project's repositories by choosing **See project code** from the project summary page. # Editing the settings for a source repository You can manage the settings for your repository, including editing the description of a repository, choosing the default branch, creating and managing branch rules, and creating and managing approval rules for pull requests in CodeCatalyst. This can help project members understand what the repository is used for, and help you enforce best practices and processes used by the team. **Note** You can't edit the name of a source repository. You can't edit the name, description, or other information for a linked repository in CodeCatalyst. To modify information about a linked repository, you must edit it in the provider that hosts the linked repository. For more information, see the documentation for the service that hosts the linked repository. **To edit the settings of a repository** 1. In the CodeCatalyst console, navigate to the project that contains the source repository whose settings you want to edit. 1. On the summary page for your project, choose the repository you want from the list, and then choose **View repository**. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the name of the repository from the list of source repositories for the project. 1. On the overview page for the repository, choose **More**, and then choose **Manage settings**. 1. Do one or more of the following: + Edit the description of the repository and then choose **Save**. + To change the default branch for the repository, in **Default branch**, choose **Edit**. For more information, see [Managing the default branch for a repository](source-branches-default-branch.md). + To add, remove, or change a rule for what project roles have permission to perform certain actions in a branch, in **Branch rules**, choose **Edit**. For more information, see [Manage allowed actions for a branch with branch rules](source-branches-branch-rules.md). + To add, remove, or change an approval rule for merging pull reuqests to a branch, in **Approval rules**, choose **Edit**. For more information, see [Managing requirements for merging a pull request with approval rules](source-pull-requests-approval-rules.md). # Cloning a source repository To work effectively with multiple files, branches, and commits in source repositories, clone the source repository to your local computer and use a Git client or an integrated development environment (IDE) to make changes. Commit and push your changes to the source repository in order to work with CodeCatalyst features such as issues and pull requests. You can also choose to create a Dev Environment to work on code. Creating a Dev Environment automatically clones the repository and branch you specify into the Dev Environment. **Note** You cannot clone linked repositories in the CodeCatalyst console or create Dev Environments for them. To clone a linked repository locally, choose the link in the list of repositories to open that repository in the service that hosts it, and then clone it. For more information, see the documentation for the service that hosts the linked repository. **To create a Dev Environment from a source repository** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose the source repository where you want to work on code. 1. Choose **Create Dev Environment**. 1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](devenvironment-create.md#devenvironment-supported-ide) for more information. 1. Do one of the following: + Choose **Work in existing branch**, and then choose a branch from the **Existing branch** drop-down menu. + Choose **Work in new branch**, enter a branch name into the **Branch name** field, and choose a branch off of which to create the new branch from the **Create branch from** drop-down menu. 1. Optionally add a name for the Dev Environment or edit its configuration. 1. Choose **Create**. **To clone a source repository** 1. Navigate to your project. 1. On the summary page for your project, choose the repository you want from the list, and then choose **View repository**. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the name of the repository from the list of source repositories for the project. You can filter the list of repositories by typing part of the repository name in the filter bar. 1. 1. Choose **Clone repository**. Copy the clone URL for the repository. **Note** If you do not have a personal access token (PAT), choose **Create token**. Copy the token and save it in a secure location. You will use this PAT when prompted for a password by your Git client or integrated development environment (IDE). 1. Do one of the following: + To clone a repository to your local computer, open a terminal or command line and run the **git clone** command with the clone URL after the command. For example: ``` git clone https://LiJuan@git.us-west-2.codecatalyst.aws/v1/ExampleCorp/MyExampleProject/MyExampleRepo ``` When prompted for a password, paste the PAT you saved earlier. **Note** If your operating system provides credential management or you have installed a credential management system, you only need to provide the PAT once. If not, you might have to provide the PAT for every Git operation. As a best practice, make sure that your credential management system securely stores your PAT. Do not include the PAT as part of the clone URL string. + To clone a repository using an IDE, follow the documentation for your IDE. Choose the option to clone a Git repository and provide the URL. When prompted for a password, provide the PAT. # Deleting a source repository If a source repository for an Amazon CodeCatalyst project is no longer needed, you can delete it. Deleting a source repository also deletes any project information stored in the repository. If any workflows depend on the source repository, those workflows will be deleted from the list of project workflows after the repository is deleted. Issues that reference the source repository will not be deleted or altered, but any links to the source repository added to issues will fail once the repository is deleted. **Important** Deleting a source repository cannot be undone. After you delete a source repository, you are no longer able to clone it, pull data from it, or push data to it. Deleting a source repository does not delete any local copies of that repository (local repos). To delete a local repo, use your local computer's directory and file management tools. **Note** You cannot delete a linked repository in the CodeCatalyst console. To delete a linked repository, choose the link in the list of repositories to open that repository in the service that hosts it, and then delete it. For more information, see the documentation for the service that hosts the linked repository. To remove a linked repository from a project, see [Unlinking GitHub repositories, Bitbucket repositories, GitLab project repositories, and Jira projects in CodeCatalyst](extensions-unlink.md). **To delete a source repository** 1. Navigate to the project that contains the source repository you want to delete. 1. On the summary page for your project, choose the repository you want from the list, and then choose **View repository**. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the name of the repository from the list of source repositories for the project. 1. On the home page for the repository, choose **More**, choose **Manage settings**, and then choose **Delete repository**. 1. Review the branch, pull request, and related workflow information to help ensure that you are not deleting a repository that is still in use or has unfinished work. If you want to continue, type **delete**, and then choose **Delete**. # Organizing your source code work with branches in Amazon CodeCatalyst In Git, branches are pointers or references to a commit. In development, they're a convenient way to organize your work. You can use branches to separate work on a new or different version of files without affecting work in other branches. You can use branches to develop new features, store a specific version of your project, and more. You can configure rules for branches in source repositories to limit certain actions on a branch to specific roles in that project. Source repositories in Amazon CodeCatalyst have contents and a default branch regardless of how you create them. Linked repositories might not have a default branch or content, but are not usable by CodeCatalyst until you initialize them and create a default branch. When you create a project using a blueprint, CodeCatalyst creates a source repository for that project that includes a README.md file, sample code, workflow definitions, and other resources. When you create a source repository without using a blueprint, a README.md file is added for you as a first commit, and a *default branch* is created for you. This default branch is named *main*. This default branch is the one used as the base or default branch in local repositories (repos) when users clone the repository. **Note** You can't delete the default branch. The first branch created for a source repository is the default branch for that repository. Additionally, search only displays results from the default branch. You can't search for code in other branches. Creating a repository in CodeCatalyst also creates a first commit, which creates a *default branch* with a README.md file included in it. The name of that default branch is *main*. This is the default branch name used in the examples in this guide. **Topics** + [ # Creating a branch ](source-create-delete-branch.md) + [ # Managing the default branch for a repository ](source-branches-default-branch.md) + [ # Manage allowed actions for a branch with branch rules ](source-branches-branch-rules.md) + [ # Git commands for branches ](source-branches-git.md) + [ # Viewing branches and details ](source-branches-view.md) + [ # Deleting a branch ](source-branches-delete.md) # Creating a branch You can use the CodeCatalyst console to create branches in a CodeCatalyst repository. The branches you create will be visible to other users the next time they pull changes from the repository. **Tip** You can also create branches as part of creating a Dev Environment to work on your code. For more information, see [Creating a Dev Environment](devenvironment-create.md). You can also use Git to create branches. For more information, see [Common Git commands for branches](source-branches-git.md#source-branches-git-table). **To create a branch (console)** 1. In the CodeCatalyst console, navigate to the project where your source repository resides. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose the repository where you want to create a branch. 1. On the overview page of the repository, choose **More**, and then choose **Create branch**. 1. Enter a name for the branch. 1. Choose a branch to create the branch from, and then choose **Create**. # Managing the default branch for a repository You can specify which branch to use as the *default branch* in a source repository in Amazon CodeCatalyst. All source repositories in CodeCatalyst have contents and a default branch regardless of how you create them. If you use a blueprint to create a project, the default branch in the source repository created for that project is named *main*. The contents of the default branch are displayed automatically on the overview page for that repository. **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. The default branch is treated a little differently than all other branches in a source repository. It has a special label next to its name, **Default**. The default branch is the one used as the base or default branch in local repositories (repos) when users clone the repository to local computers with a Git client. It is also the default used when creating workflows for storing workflow YAML files, and for storing information for issues. When using search in CodeCatalyst, only the default branch of a repository is searched. Because the default branch is fundamental to so many aspects of projects, you cannot delete a branch if it is specified as the default branch. However, you can choose to use a different branch as the default branch. If you do, any [branch rules](source-branches-branch-rules.md) that were applied to the former default branch will be applied automatically to the branch you specify as the default branch. **Note** You must have the Project administrator role to change the default branch for source repositories in CodeCatalyst projects. This does not apply to linked repositories. **To view and change the default branch for a repository** 1. Navigate to the project where your repository resides. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to view the settings, including the default branch. 1. On the overview page of the repository, choose **More**, and then choose **Manage settings**. 1. In **Default branch**, the name of the branch specified as the default branch is displayed along with a label called **Default** next to the name. This same label appears next to the branch name in the list of branches in **Branches**. 1. To change the default branch, choose **Edit**. **Note** You must have the Project administrator role in the project to change the default branch. 1. Choose the name of the branch you want to make the default branch from the drop-down list and then choose **Save**. # Manage allowed actions for a branch with branch rules When you create a branch, certain actions are allowed for that branch based on the permissions for that role. You can change what actions are allowed for a specific branch by configuring branch rules. Branch rules are based on the role a user has in your project. You can choose to limit some predefined actions, such as pushing commits to a branch, to users with a particular role in a project. This can help you protect specific branches in a project by limiting which roles are allowed to perform certain actions. For example, if you configure a branch rule to only allow users with the **Project administrator** role to merge or push to that branch, users with other roles in the project will not be able to make changes to the code in the that branch. You should carefully consider all the implications of creating a rule for a branch. For example, if you choose to limit pushes to a branch to users with the **Project administrator** role, users with the **Contributor** role will not be able to create or edit workflows in that branch, because the workflow YAML is stored in that branch, and those users cannot commit and push changes to the YAML. As a best practice, test any branch rules after you create them in order to make sure that they do not have any impacts that you did not intend. You can also use branch rules in conjunction with approval rules for pull requests. For more information, see [Managing requirements for merging a pull request with approval rules](source-pull-requests-approval-rules.md). **Note** You must have the Project administrator role to manage branch rules for source repositories in CodeCatalyst projects. You cannot create branch rules for linked repositories. You can only create branch rules that are more restrictive than the default permissions for the role. You cannot create branch rules that are more permissive than what a user's role in the project allows. For example, you cannot create a branch rule that allows users with the Reviewer role to push to the branch. Branch rules that are applied to the default branch of your source repository will behave a little differently than branch rules applied to other branches. Any rule applied to the default branch will be automatically applied to any branch you specify as the default branch. The branch that was formerly set as the default branch will still keep the rules applied to it, except that it will no longer have protection against deletion. That protection is only applied to the current default branch. Branch rules have two states, **Standard** and **Custom**. **Standard** indicates that the actions allowed on a branch are those that match the permissions for the role the user has in CodeCatalyst for branch actions. To learn more about what roles have which permissions, see [Granting access with user roles](ipa-roles.md). **Custom** indicates that one or more branch actions have actions that have a specific list of roles allowed to perform that action that differ from the default permissions granted by a user's roe in the project. **Note** If you create a branch rule to restrict one or more actions for a branch, the **Delete the branch** action is automatically set to only allow users with the Project administrator role to delete that branch. The following table lists the actions and the default settings for roles allowed to perform these actions on a branch. **Branch actions and roles** | **Branch action** | Roles allowed to perform this action when no branch rules are applied | | --- | --- | | Merge to the branch (this includes merging a pull request to the branch) | Project administrator, Contributor | | Push to the branch | Project administrator, Contributor | | Delete the branch | Project administrator, Contributor | | Delete the branch (default branch) | Not allowed | You cannot delete branch rules, but you can update them to allow actions from all the roles that would be allowed to perform this action on a branch, which effectively removes the rule. **Note** You must have the Project administrator role to configure branch rules for source repositories in CodeCatalyst projects. This does not apply to linked repositories. Linked repositories do not support the branch rules in CodeCatalyst. **To view and edit branch rules for a repository** 1. Navigate to the project where your repository resides. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to view branch rules. 1. On the overview page of the repository, choose **Branches**. 1. In the **Branch rules** column, view the status of rules for each branch of the repository. **Standard** indicates that the rules for branch action are the default ones for any branch created in a source repository and match the permissions granted to those roles in a project. **Custom** indicates that one or more branch actions have rules that restrict one or more actions allowed for that branch to a different set of roles. To view the specifics of the branch rules for a branch, choose the word **Standard** or **Custom** next to the branch you want to review. 1. To create or change a branch rule, choose **Manage settings**. On the settings page for the source repository, in **Branch rules**, choose **Edit**. 1. In **Branch**, choose the name of the branch for which you want to configure a rule from the drop-down list. For each of the allowed action types, choose the roles you want to allow to perform that action from the drop-down list, and then choose **Save**. # Git commands for branches You can use Git to create, manage, and delete branches in the clone of the source repository you have on your computer (your local repo) or in your Dev Environments, and then commit and push your changes to your CodeCatalyst source repository (the remote repository). For example: **Common Git commands for branches** | | | | --- |--- | | Lists all branches in the local repo with an asterisk (`*`) displayed next to your current branch. | `git branch` | | Pulls information about all existing branches in the remote repository to the local repo. | `git fetch` | | Lists all branches in the local repo and remote tracking branches in the local repo. | `git branch -a` | | Lists only remote tracking branches in the local repo. | `git branch -r` | | Creates a branch in the local repo using the specified branch name. This branch will not appear in the remote repository until you commit and push the change. | `git branch branch-name` | | Creates a branch in the local repo using the specified branch name, and then switches to it. | `git checkout -b branch-name` | | Switches to another branch in the local repo using the specified branch name. | `git checkout other-branch-name` | | Pushes a branch from the local repo to the remote repository using the local repo's specified nickname for the remote repository and the specified branch name. Also sets up upstream tracking information for the branch in the local repo. | `git push -u remote-name branch-name` | | Merges changes from another branch in the local repo to the current branch in the local repo. | `git merge from-other-branch-name` | | Deletes a branch in the local repo unless it contains work that has not been merged. | `git branch -d branch-name` | | Deletes a branch in the remote repository using the specified nickname the local repo has for the remote repository and the specified branch name. (Note the use of the colon (`:`).) Alternatively, specify `--delete` as part of the command. | `git push remote-name :branch-name` `git push remote-name --delete branch-name` | For more information, see your Git documentation. # Viewing branches and details You can view information about remote branches in Amazon CodeCatalyst, including specifics of the files, folders, and most recent commit for a specific branch, in the Amazon CodeCatalyst console. You can also use Git commands and your local operating system to view this information for remote and local branches. **To view branches (console)** 1. In the CodeCatalyst console, navigate to the project that contains the source repository where you want to view branches. Choose **Code**, choose **Source repositories**, and then choose the source repository. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to view a branch. 1. The default branch of the repository is displayed. You can see a list of files and folders in the branch, information about the most recent commit, and the contents of the README.md file, if it exists in the branch. To view the information for a different branch, choose it from the drop-down list of branches for the repository. 1. To view all the branches for a repository, choose **View all**. The Branches page displays information about the name, most recent commit, and rules for each branch. For information about how to use Git and your operating system to view branches and details, see [Common Git commands for branches](source-branches-git.md#source-branches-git-table), your Git documentation, and your operating system documentation. # Deleting a branch If you no longer need a branch, you can delete it. For example, if you've merged a branch with a feature change into the default branch and that feature has been released, you might want to delete the original feature branch, as the changes are already part of the default branch. Keeping the number of branches low can help users find the branch that contains the changes they want to work on. When you delete a branch, copies of that branch remain in the clones of the repository on local computers until users pull and synchronize those changes. **To delete a branch (console)** 1. Navigate to the project where your repository resides. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to delete a branch. 1. On the overview page of the repository, choose the drop-down selector next to the branch name, and then choose **View all**. 1. Choose the branch that you want to delete and then choose **Delete branch**. **Note** You cannot delete the default branch for a repository. 1. A confirmation dialog box appears. It shows the repository, number of open pull requests, and number of workflows associated with the branch. 1. To confirm deletion of the branch, type **delete** into the text box, and then choose **Delete**. You can also use Git to delete branches. For more information, see [Common Git commands for branches](source-branches-git.md#source-branches-git-table). # Managing source code files in Amazon CodeCatalyst In Amazon CodeCatalyst, a file is a version-controlled, self-contained piece of information available to you and other users of the source repository and branch where the file is stored. You can organize your repository files with a directory structure. CodeCatalyst automatically tracks every committed change to a file. You can store different versions of a file in different repository branches. To add or edit multiple files in a source repository, you can use a Git client, a Dev Environment, or an integrated development environment (IDE). To add or edit a single file, you can use the CodeCatalyst console. **Topics** + [ # Creating or adding a file ](source-files-create.md) + [ # Viewing a file ](source-files-view.md) + [ # Viewing the history of changes to a file ](source-files-view-history.md) + [ # Editing a file ](source-files-edit.md) + [ # Renaming or deleting a file ](source-files-delete.md) # Creating or adding a file To create and add files to a source repository, you can use the Amazon CodeCatalyst console, a Dev Environment, a connected integrated development environment (IDE), or a Git client. The CodeCatalyst console includes a code editor for creating files. This editor is a convenient way to create or edit a simple file, such as a README.md file, in a branch in a repository. When working on more than one file, consider [creating a Dev Environment](devenvironment-create.md). **To create a Dev Environment from a source repository** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose the source repository where you want to work on code. 1. Choose **Create Dev Environment**. 1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](devenvironment-create.md#devenvironment-supported-ide) for more information. 1. Do one of the following: + Choose **Work in existing branch**, and then choose a branch from the **Existing branch** drop-down menu. + Choose **Work in new branch**, enter a branch name into the **Branch name** field, and choose a branch off of which to create the new branch from the **Create branch from** drop-down menu. 1. Optionally add a name for the Dev Environment or edit its configuration. 1. Choose **Create**. **To create a file in the CodeCatalyst console** 1. Navigate to the project where you want to create a file. For more information about how to navigate to a repository, see [Viewing a source repository](source-repositories-view.md). 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to create the file. 1. (Optional) Choose the branch where you want to create the file, if you want to create the file in a different branch than the default branch. 1. Choose **Create file**. 1. Enter the name of the file in **File name**. Add the contents of the file in the editor. **Tip** If you want to create the file in a sub-folder or subdirectory of the root of the branch, include that structure as part of the file name. When you are satisfied with your changes, choose **Commit**. 1. In **File name**, review the name of the file and make any changes you might want to it. Optionally choose the branch where you want to create the file from the list of available branches in **Branch**. In **Commit message**, optionally enter a brief but informative description of why you made this change. This will be displayed as the basic commit information for the commit that adds the file to the source repository. 1. Choose **Commit** to commit and push the file to the source repository. You can also add files to a source repository by cloning it to your local computer and using a Git client or connected integrated development environment (IDE) to push your files and changes. **Note** If you want to add a Git submodule, you must use a Git client or a Dev Environment and run the **git submodule add** command. You cannot add or view Git submodules in the CodeCatalyst console or view the differences in Git submodules in pull requests. For more information about Git submodules, see the [Git documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules). **To add a file using a Git client or connected integrated development environment (IDE)** 1. Clone your source repository to your local computer. For more information, see [Cloning a source repository](source-repositories-clone.md). 1. Create files in your local repo or copy files into your local repo. 1. Create and push a commit by doing one of the following: + If you are using a Git client, at the terminal or command line, run the **git add** command, specifying the names of the files you want to add. Alternatively, to add all added or changed files, run the **git add** command followed by either a single or double period to indicate whether you want to include all the changes at the current directory level (single period) or all changes in the current directory and all subdirectories (double period). To commit the changes, run the **git commit -m** command and provide a commit message. To push your changes to the source repository in CodeCatalyst, run **git push**. For more information about Git commands, see your Git documentation and [Git commands for branches](source-branches-git.md). + If you are using a Dev Environment or an IDE, create files and add files in the IDE, and then commit and push your changes. For more information, see see [Write and modify code with Dev Environments in CodeCatalystWrite and modify code with Dev Environments](devenvironment.md) or consult your IDE documentation. # Viewing a file You can view the files in your source repository in the Amazon CodeCatalyst console. You can view the files in the default branch and in any other branches. File contents might vary depending on the branch you choose to view. **To view files in the CodeCatalyst console** 1. Navigate to the project where you want to view files. For more information, see [Viewing a source repository](source-repositories-view.md). 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to view files. 1. A list of files and folders are displayed for the default branch. Files are indicated by a paper icon, while folders are indicated by a folder icon. 1. Do any of the following: + To view files and folders in a different branch, choose it from the list of branches. + To expand a folder, choose it from the list. 1. To view the contents of a specific file, choose it from the list. The contents of the file will be displayed in the branch. To view the contents of the file in a different branch, choose the branch you want from the branch selector. **Tip** When viewing the contents of a file, you can choose additional files to view from **View files**. To edit a file, choose **Edit**. You can view multiple files in the console. You can also view files that you have cloned to your local computer using a Git client or an integrated development environment (IDE). For more information, see the documentation for your Git client or IDE. **Note** You cannot view Git submodules in the CodeCatalyst console. For more information about Git submodules, see the [Git documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules). # Viewing the history of changes to a file You can view the the history of changes to a file in your source repository in the Amazon CodeCatalyst console. This can help you understand the changes made to the file by various commits to the branch where you choose to view the history of the file. For example, if you view the history of changes to the **readme.md** file in the **main** branch of the source repository, you will see a list of commits that included changes to that file in that branch. **Note** You can't view the history of a file in a linked repository in the CodeCatalyst console. # To view the history of a file in the CodeCatalyst console 1. Navigate to the project where you want to view the history of a file. For more information, see [Viewing a source repository](source-repositories-view.md). 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose the repository where you want to view the history of a file. Choose the branch where you want to view the history the file, and then choose the file from the list. Choose **View history**. 1. Review the list of commits that included changes to this file in the specified branch. To view the details of the changes included in a particular commit, choose the commit message for that commit in the list. The differences between that commit and its parent commit are displayed. 1. To review the history of changes to the file in another branch, use the branch selector to change views to that branch, choose the file from the file list, and then choose **View history**. **Note** You cannot view the history of changes to Git submodules in the CodeCatalyst console. For more information about Git submodules, see the [Git documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules). # Editing a file You can edit individual files in the Amazon CodeCatalyst console. To edit multiple files at once, either create a Dev Environment or clone the repository and make your changes using a Git client or integrated development environment (IDE). For more information, see [Write and modify code with Dev Environments in CodeCatalystWrite and modify code with Dev Environments](devenvironment.md) or [Cloning a source repository](source-repositories-clone.md). **To edit a file in the CodeCatalyst console** 1. Navigate to the project where you want to edit a file. For more information about how to navigate to a repository, see [Viewing a source repository](source-repositories-view.md). 1. Choose the repository where you want to edit the file. Choose **View branches** and then choose the branch you want to work in. Choose the file from the list of files and folders in that branch. The contents of the file are displayed. 1. Choose **Edit**. 1. In the editor, edit the contents of the file and then choose **Commit**. Optionally, in **Commit changes**, add more information about the change in **Commit message**. When you are satisfied with your changes, choose **Commit**. # Renaming or deleting a file You can rename or delete files in a Dev Environment, locally on your computer, or in an integrated development environment (IDE). Once you have renamed or deleted the files, commit and push those changes to the source repository. You can't rename or delete files in the Amazon CodeCatalyst console. # Reviewing code with pull requests in Amazon CodeCatalyst A pull request is the primary way you and other project members can review, comment on, and merge code changes from one branch to another. You can use pull requests to review code changes collaboratively for minor changes or fixes, major feature additions, or new versions of your released software. If you use issues to track work on your project, you can link specific issues to pull requests to help you track what issues are being addressed by the code changes in the pull request. When you create, update, comment on, merge, or close a pull request, an email is automatically sent to the author of the pull request as well as any required or optional reviewers for the pull request. **Tip** You can configure what pull request events you that will receive emails about as part of your profile. For more information, see [Sending Slack and email notifications from CodeCatalyst](notifications-manage.md). Pull requests require two branches in a source repository: a source branch that contains the code that you want reviewed, and a destination branch, where you want to merge the reviewed code. The source branch contains the AFTER commit, which is the commit that contains the changes you want to merge into the destination branch. The destination branch contains the BEFORE commit, which represents the state of the code before the pull request branch is merged into the destination branch. **Note** While you are creating a pull request, the difference displayed is the difference between the tip of the source branch and the tip of the destination branch. Once you create the pull request, the displayed difference will be between the revision of the pull request you choose and the commit that was the tip of the destination branch when you created the pull request. For more information about differences and merge bases in Git, see [git-merge-base](https://git-scm.com/docs/git-merge-base) in the Git documentation. While a pull request is created for a specific source repository and branches, you can create, view, review, and close them as part of working with your project. You do not have to view the source repository in order to view and work with pull requests. A pull request state is set to **Open** when you create it. The pull request remains open until you either merge it in the CodeCatalyst console, which changes the state to **Merged**, or close it, which changes the state to **Closed**. When your code has been reviewed, you can change the pull request state in one of several ways: + Merge the pull request in the CodeCatalyst console. The code in the source branch of the pull request will be merged into the destination branch. The pull request status will change to **Merged**. It can't be changed back to **Open**. + Merge the branches locally and push your changes, and then close the pull request in the CodeCatalyst console. + Use the CodeCatalyst console to close the pull request without merging. This will change the status to **Closed**, and it will not merge the code from the source branch into the destination branch. Before you create a pull request: + Commit and push the code changes you want reviewed to a branch (the source branch). + Set up notifications for your project, so other users can be notified about any workflows that run when you create a pull request. (This step is optional but recommended.) **Topics** + [ # Creating a pull request ](pull-requests-create.md) + [ # Viewing pull requests ](pull-requests-view.md) + [ # Managing requirements for merging a pull request with approval rules ](source-pull-requests-approval-rules.md) + [ # Reviewing a pull request ](pull-requests-review.md) + [ # Updating a pull request ](pull-requests-update.md) + [ # Merging a pull request ](pull-requests-merge.md) + [ # Closing a pull request ](pull-requests-close.md) # Creating a pull request Creating pull requests helps other users see and review your code changes before you merge them into another branch. First, you create a branch for your code changes. This is referred to as the source branch for a pull request. After you commit and push changes to the repository, you can create a pull request that compares the contents of the source branch to the contents of the destination branch. You can create a pull request in the Amazon CodeCatalyst console from a specific branch, from the pull requests page, or from the project overview. Creating a pull request from a specific branch automatically provides the repository name and source branch on the pull request creation page. When you create a pull request, you will automatically receive emails about any updates to the pull request, as well as when the pull request is merged or closed. **Note** While you are creating a pull request, the difference displayed is the difference between the tip of the source branch and the tip of the destination branch. Once the pull request has been created, the displayed difference will be between the revision of the pull request you choose and the commit that was the tip of the destination branch when you created the pull request. For more information about differences and merge bases in Git, see [git-merge-base](https://git-scm.com/docs/git-merge-base) in the Git documentation. You can use the **Write description for me** feature when creating pull requests to have Amazon Q automatically create a description of the changes contained in a pull request. When you choose this option, Amazon Q analyzes the differences between the source branch that contains the code changes and the destination branch where you want to merge these changes. It then creates a summary of what those changes are, as well as its best interpretation of the intent and effect of those changes. This feature is only available in the US West (Oregon) Region for CodeCatalyst pull requests. The **Write description for me** feature is not available for pull requests in linked repositories. **Note** **Powered by Amazon Bedrock**: AWS implements [automated abuse detection](https://docs.aws.amazon.com//bedrock/latest/userguide/abuse-detection.html). Because the **Write description for me**, **Create content summary**, **Recommend tasks**, **Use Amazon Q to create or add features to a project**, and **Assign issues to Amazon Q** feature with Amazon Q Developer Agent for software development features are built on Amazon Bedrock, users can take full advantage of the controls implemented in Amazon Bedrock to enforce safety, security, and the responsible use of artificial intelligence (AI). **To create a pull request** 1. Navigate to your project. 1. Do one of the following: + In the navigation pane, choose **Code**, choose **Pull requests**, and then choose **Create pull request**. + On the repository home page, choose **More**, and then choose **Create pull request**. + On the project page, choose **Create pull request**. 1. In **Source repository**, make sure that the specified source repository is the one that contains the committed code. This option only appears if you did not create the pull request from the repository's main page. 1. In **Destination branch**, choose the branch to merge the code into after it is reviewed. 1. In **Source branch**, choose the branch that contains the committed code. 1. In **Pull request title**, enter a title that helps other users understand what needs to be reviewed and why. 1. (Optional) In **Pull request description**, provide information such as a link to issues or a description of your changes. **Tip** You can choose **Write description for me** to have CodeCatalyst automatically generate a description of the changes contained in the pull request. You can make changes to the automatically generated description after you add it to the pull request. This functionality requires that generative AI features are enabled for the space and is not available for pull requests in linked repositories. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html). 1. (Optional) In **Issues**, choose **Link issues**, and then either choose an issue from the list or enter its ID. To unlink an issue, choose the unlink icon. 1. (Optional) In **Required reviewers**, choose **Add required reviewers**. Choose from the list of project members to add them. Required reviewers must approve the changes before the pull request can be merged into the destination branch. **Note** You cannot add a reviewer as both a required reviewer and an optional reviewer. You cannot add yourself as a reviewer. 1. (Optional) In **Optional reviewers**, choose **Add optional reviewers**. Choose from the list of project members to add them. Optional reviewers do not have to approve the changes as a requirement before the pull request can be merged into the destination branch. 1. Review the differences between the branches. The difference displayed in a pull request is the changes between the revision in the source branch and the merge base, which is the head commit of the destination branch at the time the pull request was created. If no changes display, the branches might be identical, or you might have chosen the same branch for both the source and the destination. 1. When you are satisfied that the pull request contains the code and changes you want reviewed, choose **Create**. **Note** After you create the pull request, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resources, such as files, by using the @ sign followed by the name of the file. **To create a pull request from a branch** 1. Navigate to the project where you want to create a pull request. 1. In the navigation pane, choose **Source repositories**, and then choose the repository that contains the branch where you have code changes to review. 1. Choose the drop-down arrow next to the default branch name, and then choose the branch you want from the list. To view all the branches for a repository, choose **View all**. 1. Choose **More**, and then choose **Create pull request**. 1. The repository and the source branch are preselected for you. In **Destination branch**, choose the branch where you will merge the code once it has been reviewed. In **Pull request title**, enter a title that will help other project users understand what must be reviewed and why. Optionally, provide more information in **Pull request description**, such as pasting in a link to related issues in CodeCatalyst, or adding a description of the changes you made. **Note** Workflows that are configured to run for pull request create events will run after the pull request is created, if the destination branch for the pull request matches one of the branches specified in the workflow. 1. Review the differences between the branches. If no changes are displayed, the branches might be identical, or you might have chosen the same branch for both the source and the destination. 1. (Optional) In **Issues**, choose **Link issues**, and then either choose an issue from the list or enter its ID. To unlink an issue, choose the unlink icon. 1. (Optional) In **Required reviewers**, choose **Add required reviewers**. Choose from the list of project members to add them. Required reviewers must approve the changes before the pull request can be merged into the destination branch. **Note** You can't add a reviewer as both required and optional. You can't add yourself as a reviewer. 1. (Optional) In **Optional reviewers**, choose **Add optional reviewers**. Choose from the list of project members to add them. Optional reviewers do not have to approve the changes before the pull request can be merged into the destination branch. 1. When you are satisfied that the pull request contains the changes that you want reviewed and includes the required reviewers, choose **Create**. If you have any workflows configured to run where the branch matches the destination branch in the pull request, you will see information about those workflow runs in **Overview** in the **Pull request details** area after the pull request is created. For more information, see [Adding triggers to workflows](workflows-add-trigger-add.md). # Viewing pull requests You can view pull requests for a project in the Amazon CodeCatalyst console. The project summary page displays all open pull requests for a project. To view all pull requests regardless of state, navigate to the pull requests page for your project. When viewing a pull request, you can choose to have a summary of all comments left on changes to the pull request created for you. **Note** **Powered by Amazon Bedrock**: AWS implements [automated abuse detection](https://docs.aws.amazon.com//bedrock/latest/userguide/abuse-detection.html). Because the **Write description for me**, **Create content summary**, **Recommend tasks**, **Use Amazon Q to create or add features to a project**, and **Assign issues to Amazon Q** feature with Amazon Q Developer Agent for software development features are built on Amazon Bedrock, users can take full advantage of the controls implemented in Amazon Bedrock to enforce safety, security, and the responsible use of artificial intelligence (AI). **To view open pull requests** 1. Navigate to the project where you want to view pull requests. 1. On the project page, open pull requests are displayed, including information about who created the pull request, what repository contains the branches for the pull request, and the date the pull request was created. You can filter the open pull request view by source repository. 1. To view all pull requests, choose **View all**. You can use the selectors to choose between the options. For example, to view all pull requests, choose **Any status** and **Any author**. Alternatively, in the navigation pane, choose **Code**, and then choose **Pull requests**, and then use the selectors to refine your view. 1. On the **Pull requests** page, you can sort pull requests by ID, title, status, and more. To customize what information and how much information is displayed on the pull requests page, choose the gear icon. 1. To view a specific pull request, choose it from the list. 1. To view the status of workflows runs associated with this pull request, if any, choose **Overview** and review the information in the **Pull request details** area of the pull request under **Workflow runs**. A workflow run will occur if the workflow is configured with pull request create or revision events, and if the destination branch requirements in the workflow match the destination branch specified in the pull request. For more information, see [Adding triggers to workflows](workflows-add-trigger-add.md). 1. To view linked issues, if any, choose **Overview** and review the information in the **Pull request details** under **Issues**. If you want to view a linked issue, choose its ID from the list. 1. (Optional) To create a summary of comments left on the code changes in revisions of the pull request, choose **Create content summary**. The summary will not include any comments left on the overall pull request. **Note** This functionality requires that generative AI features are enabled for the space, is not available for linked repositories, and is only available in the US West (Oregon) Region. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html). 1. To view the code changes in the pull request, choose **Changes**. You can quickly view how many files have changes in the pull request, and what files in the pull request have comments on them, in **Files changed**. The number of comments shown next to a folder indicates the number of comments on files in that folder. Expand the folder to view the number of comments for each file in the folder. You can also view any comments left on specific lines of code. **Note** Not all changes in a pull request can be displayed in the console. For example, you cannot view Git submodules in the console, so you cannot view differences in a submodule in a pull request. Some differences might be too large to display. For more information, see [Quotas for source repositories in CodeCatalyst](source-quotas.md) and [Viewing a fileViewing the history of changes to a file](source-files-view.md). 1. To view quality reports for this pull request, choose **Reports**. **Note** A workflow must be configured to generate reports in order for them to show up in your pull requests. For more information, see [Testing with workflowsTesting with workflows](test-workflow-actions.md). # Managing requirements for merging a pull request with approval rules When you create a pull request, you can choose to add required or optional reviewers to that individual pull request. However, you can also create requirements that all pull requests must meet when merging to a specific destination branch. These requirements are called approval rules. Approval rules are configured for branches in a repository. When you create a pull request whose destination branch has an approval rule configured for it, the requirements for that rule must be met in addition to approvals from any required reviewers before you can merge the pull request to that branch. Creating approval rules can help you maintain quality standards for merges to branches such as your default branch. Approval rules that are applied to the default branch of your source repository will behave a little differently than approval rules applied to other branches. Any rule applied to the default branch will be automatically applied to any branch you specify as the default branch. The branch that was formerly set as the default branch will still keep the rules applied to it. When you create approval rules, you should consider how that rule will be met by your project users both in the present and in the future. For example, if you have six users in your project, and you create an approval rule that requires five approvals before it can be merged to the destination branch, you have effectively created a rule that requires everyone except the person who created the pull requets to approve that pull request before it can be merged. **Note** You must have the Project administrator role to create and manage approval rules in CodeCatalyst projects. You cannot create approval rules for linked repositories. You cannot delete approval rules, but you can update them to require zero approvals, which effectively removes the rule. **To view and edit approval rules for destination branches for pull requests** 1. Navigate to the project where your repository resides. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to view approval rules. 1. On the overview page of the repository, choose **Branches**. 1. In the **Approval rules** column, choose **View** to see the status of any rules for each branch of the repository. In **Minimum number of approvals**, the number corresponds to the number of approvals required before a pull request can be merged to that branch. 1. To create or change an approval rule, choose **Manage settings**. On the settings page for the source repository, in **Approval rules**, choose **Edit**. **Note** You must have the **Project administrator** role to edit approval rules. 1. In **Branch**, choose the name of the branch for which you want to configure an approval rule from the drop-down list. In **Minimum number of approvals**, enter a number, and then choose **Save**. # Reviewing a pull request You can use the Amazon CodeCatalyst console to collaboratively review and comment on the changes included in a pull request. You can add comments to individual lines of code in the difference between the source and destination branches, or in the difference between revisions of the pull request. You can choose to create a summary of comments left on the code changes in the pull request to help you quickly understand the feedback left by other users. You can also choose to create a Dev Environment to work on code. **Note** **Powered by Amazon Bedrock**: AWS implements [automated abuse detection](https://docs.aws.amazon.com//bedrock/latest/userguide/abuse-detection.html). Because the **Write description for me**, **Create content summary**, **Recommend tasks**, **Use Amazon Q to create or add features to a project**, and **Assign issues to Amazon Q** feature with Amazon Q Developer Agent for software development features are built on Amazon Bedrock, users can take full advantage of the controls implemented in Amazon Bedrock to enforce safety, security, and the responsible use of artificial intelligence (AI). **Tip** You can configure what pull request events you that will receive emails about as part of your profile. For more information, see [Sending Slack and email notifications from CodeCatalyst](notifications-manage.md). Pull requests show what the difference will be between the revision of the pull request and the commit that was the tip of the destination branch when you created the pull request. This is called the merge base. For more information about differences and merge bases in Git, see [git-merge-base](https://git-scm.com/docs/git-merge-base) in the Git documentation. **Tip** When working in the console, particularly if you have had a pull request open for a while, consider refreshing your browser to ensure you have the latest revision available for a pull request before you start to review it. **To review a pull request in the CodeCatalyst console** 1. Navigate to your project. 1. Navigate to the pull requests by doing one of the following: + If the pull request is listed on the project page, choose it from the list. + If the pull request is not listed on the project page, choose **View all**. Use the filters and sort to find the pull request, and then choose it from the list. + In the navigation pane, choose **Code**, and then choose **Pull requests**. 1. Choose the pull request you want to review from the list. You can filter the list of pull requests by typing part of its name in the filter bar. 1. In **Overview**, you can review the name and title of the pull request. You can create and view comments left on the pull request itself. You can also view the details of the pull request, including information about workflow runs, linked issues, reviewers, the author of the pull request, and feasible merge strategies. **Note** Comments left on specific lines of code appear in **Changes**. 1. (Optional) To add a comment that applies to the entire pull request, expand **Comments on pull request**, and then choose **Create comment**. 1. (Optional) To view a summary of all comments left on changes in revisions of this pull request, choose **Create comment summary**. **Note** This functionality requires that generative AI features are enabled for the space and is only available in the US West (Oregon) Region. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html). 1. In **Changes**, you can see the differences between the destination branch and the most recent revision of the pull request. If there is more than one revision, you can change what revisions are compared in the difference between them. For more information about revisions, see [Revisions](source-concepts.md#revision-concept). **Tip** You can quickly view how many files have changes in the pull request, and what files in the pull request have comments on them, in **Files changed**. The number of comments shown next to a folder indicates the number of comments on files in that folder. Expand the folder to view the number of comments for each file in the folder. 1. To change the way differences are displayed, choose between **Unified** and **Split**. 1. To add a comment to a line in the pull request, go to the line you want to comment on. Choose the comment icon that appears for that line, enter a comment, and then choose **Save**. 1. To view changes between revisions in a pull request, or between its source and destination branches, choose from the available options in **Comparing**. Comments on lines in revisions are preserved in those revisions. 1. If you’ve configured your workflow to generate a code coverage report on pull request triggers, you can view the line and branch coverage findings in the relevant pull request. To hide code coverage findings, choose **Hide code coverage**. For more information, see [Code coverage reports](test-workflow-actions.md#test-code-coverage-reports). 1. If you want to make code changes to the pull request, you can create a Dev Environment from the pull request. Choose **Create Dev Environment**. Optionally add a name for the Dev Environment or edit its configuration and then choose **Create**. 1. In **Reports**, you can view the quality reports in this pull request. If there is more than one revision, you can change what revisions are compared in the difference between them. You can filter the reports by name, status, workflow, action, and type. **Note** A workflow must be configured to generate reports in order for them to show up in your pull requests. For more information, see [Configuring quality reports in an action](test-config-action.md). 1. To view a specific report, choose it from the list. For more information, see [Testing with workflowsTesting with workflows](test-workflow-actions.md). 1. If you are listed as a reviewer of this pull request and want to approve the changes, make sure that you are viewing the most recent revision, and then choose **Approve**. **Note** All required reviewers must approve a pull request before it can be merged. # Updating a pull request You can make it easier for other project members to review code by updating the pull request. You can update a pull request to change its reviewers, its links to issues, the title of the pull request, or its description. For example, you might want to change the required reviewers for a pull request to remove someone who's away on vacation, and add someone else. You can also update a pull request with further code changes by pushing commits to the source branch of an open pull request. Each push to the source branch of a pull request in the CodeCatalyst source repository creates a revision. Project members can view the differences between revisions in a pull request. **To update the reviewers for a pull request** 1. Navigate to the project where you want to update the reviewers of a pull request. 1. On the project page, under **Open pull requests**, choose the pull request where you want to update reviewers. Alternatively, in the navigation pane, choose **Code**, choose **Pull requests**, and then choose the pull request you want to update. 1. (Optional) In **Overview**, in the **Pull request details** area, choose the plus sign to add required or optional reviewers. Choose the **X** next to a reviewer to remove them as an optional or required reviewer. 1. (Optional) In **Overview**, in the **Pull request details** area, choose **Link issues** to link an issue to the pull request, and then either choose an issue from the list or enter its ID. To unlink an issue, choose the unlink icon next to the issue you want to unlink. **To update files and code in the source branch of a pull request** 1. To update multiple files, either [create a Dev Environment](devenvironment-create.md), or clone the repository and its source branch and use a Git client or an integrated development environment (IDE) to make changes to the files in the source branch. Commit and push the changes to the source branch in the CodeCatalyst source repository to automatically update the pull request with the changes. For more information, see [Cloning a source repository](source-repositories-clone.md) and [Understanding changes in source code with commits in Amazon CodeCatalyst](source-commits.md). 1. To update an individual file in a source branch, you can use a Git client or IDE as you would for multiple files. You can also edit it directly in the CodeCatalyst console. For more information, see [Editing a file](source-files-edit.md). **To update the title and description of a pull request** 1. Navigate to the project where you want to update the title or description of a pull request. 1. The project page displays open pull requests, including information about who created the pull request, what repository contains the branches for the pull request, and when the pull request was created. You can filter the open pull request view by source repository. Choose the pull request that you want to change from the list. 1. To view all pull requests, choose **View all**. Alternatively, in the navigation pane, choose **Code**, and then choose **Pull requests**. Use the filter box or sort functions to find the pull request you want to change, and then choose it. 1. In **Overview**, choose **Edit**. 1. Change the title or description, and then choose **Save**. # Merging a pull request After your code has been reviewed and all required reviewers have approved it, you can merge a pull request in the CodeCatalyst console using a supported merge strategy, such as fast-forward. Not all merge strategies supported in the CodeCatalyst console are available as choices for all pull requests. CodeCatalyst evaluates the merge and only allows you to choose between merge strategies that are available in the console and capable of merging the source branch into the destination branch. You can also merge a pull request with your choice of Git merge strategies by running the **git merge** command on your local computer or a Dev Environment to merge the source branch into the destination branch. You can then push those changes in the destination branch to the source repository in CodeCatalyst. **Note** Merging the branch and pushing the changes in Git does not automatically close the pull request. If you have the Project administrator role, you can also choose to merge a pull request that has not yet met all the requirements for approvals and approval rules. ## Merging a pull request (console) You can merge a pull request in the CodeCatalyst console if there are no merge conflicts between the source and destination branches and if all required reviewers have approved the pull request. If there are conflicts, or if the merge can't be completed, the merge button is inactive, and a **Not mergeable** label is displayed. In that case, you must obtain approval from any required approvers, resolve conflicts locally if necessary, and push those changes before you can merge. Merging a pull request will automatically send an email to the creator of the pull request as well as any required or optional reviewers. It will not automatically close or change the status of any issues linked to the pull request. **Tip** You can configure what pull request events you that will receive emails about as part of your profile. For more information, see [Sending Slack and email notifications from CodeCatalyst](notifications-manage.md). **To merge a pull request** 1. Navigate to the project where you want to merge a pull request. 1. On the project page, under **Open pull requests**, choose the pull request you want to merge. If you do not see the pull request, choose **View all pull requests** and then choose it from the list. Alternatively, in the navigation pane, choose **Code**, choose **Pull requests**, and then choose the pull request you want to merge. Choose **Merge**. 1. Choose from the available merge strategies for the pull request. Optionally, select or deselect the option to delete the source branch after merging the pull request, and then choose **Merge**. **Note** If the **Merge** button is inactive, or you see the **Not mergeable** label, either required reviewers have not yet approved the pull request, or the pull request can't be merged in the CodeCatalyst console. A reviewer who has not approved a pull request is indicated by a clock icon in the **Pull request details** area in **Overview**. If all required reviewers have approved the pull request but the **Merge** button is still inactive, you might have a merge conflict. Choose the underlined **Not mergeable** label to see more details about why the pull request can't be merged. You can resolve merge conflicts for the destination branch in a Dev Environment or the CodeCatalyst console and then merge the pull request, or you can resolve conflicts and merge locally, and then push the commit that contains the merge to the source branch in CodeCatalyst. For more information, see [Merging a pull request (Git)](#pull-requests-merge-git) and your Git documentation. ## Override merge requirements If you have the **Project administrator** role, you can choose to merge a pull request that has not yet met all the requirements for required approvals and approval rules. This is referred to as overriding the requirements for a pull request. You might choose to do this if a required reviewer is unavailable, or if an urgent need arises to merge a specific pull request into a branch that has approval rules that cannot be met quickly. **To merge a pull request** 1. In the pull request where you want to override requirements and merge, choose the drop-down arrow next to the **Merge** button. Choose **Override approval requirements**. 1. In **Override reason**, provide details of why you are merging this pull request without it meeting the approval rules and required reviewer requirements. While this is optional, this is highly recommended. 1. Optionally choose a merge strategy, or accept the default. You can also choose to update the automatically-generated commit message with more details. 1. Select or deselect the option to delete the source branch on merge. We recommend that you retain the source branch when overriding the requirements for merging a pull request until you've had a chance to review the decision with other team members. 1. Choose **Merge**. ## Merging a pull request (Git) Git supports many options for merging and managing branches. The following commands are some of the options that you can use. For more information, see the available documentation on the [Git website](https://git-scm.com/doc). Once you have merged and pushed your changes, manually close the pull request. For more information, see [Closing a pull request](pull-requests-close.md). **Common Git commands for merging branches** | | | | --- |--- | | Merges changes from the source branch in the local repo to the destination branch in the local repo. | `git checkout destination-branch-name` `git merge source-branch-name` | | Merges the source branch into the destination branch, specifying a fast-forward merge. This merges the branches and moves the destination branch pointer to the tip of the source branch. | `git checkout destination-branch-name` `git merge --ff-only source-branch-name` | | Merges the source branch into the destination branch, specifying a squash merge. This combines all commits from the source branch into a single merge commit in the destination branch. | `git checkout destination-branch-name` `git merge --squash source-branch-name` | | Merges the source branch into the destination branch, specifying a three-way merge. This creates a merge commit and adds the individual commits from the source branch to the destination branch. | `git checkout destination-branch-name` `git merge --no-ff source-branch-name` | | Deletes the source branch in the local repo. This is useful to do as a clean-up for your local repo after merging to the destination branch and pushing the changes to the source repository. | `git branch -d source-branch-name` | | Deletes the source branch in the remote repository (the source repository in CodeCatalyst) using the local repo's specified nickname for the remote repository. (Note the use of the colon (`:`).) Alternatively, specify `--delete` as part of the command. | `git push remote-name :source-branch-name` `git push remote-name --delete source-branch-name` | # Closing a pull request You can mark a pull request as **Closed**. This does not merge the pull request, but it can help you determine which pull requests require action and which pull requests are no longer relevant. We recommend closing a pull request if you no longer plan to merge those changes, or if the changes were merged by another pull request. Closing a pull request will automatically send an email to the creator of the pull request as well as any required or optional reviewers. It will not automatically change the status of any issues linked to the pull request. **Note** You cannot re-open a pull request after it has been closed. **To close a pull request** 1. Navigate to the project where you want to close a pull request. 1. On the project page, open pull requests are displayed. Choose the pull request that you want to close. 1. Choose **Close**. 1. Review the information, and then choose **Close pull request**. # Understanding changes in source code with commits in Amazon CodeCatalyst Commits are snapshots of the contents and changes to the contents of your repository. Every time a user commits and pushes a change to a branch, that information is saved. Git commit information includes the commit author, the person who committed the change, the date and time, and the changes made. Similar information is automatically included when you create or edit a file in the Amazon CodeCatalyst console, but the author name is your CodeCatalyst user name. You can also add Git tags to commits to help you identify specific commits. In Amazon CodeCatalyst, you can: + View a list of commits for a branch. + View individual commits, including the changes made in a commit when compared to its parent or parents. You can also view files and folders. For more information, see [Managing source code files in Amazon CodeCatalyst](source-files.md). **Topics** + [ ## Viewing commits to a branch ](#source-commits-view) + [ ## Changing how commits are displayed (CodeCatalyst console) ](#source-commits-settings) ## Viewing commits to a branch You can view the history of changes made to a branch by reviewing the branch's commits in the CodeCatalyst console. This helps you understand who made changes to the branch and when. You can also review the changes made in a specific commit. **Tip** You can also view the history of commits that made changes to a specific file. For more information see [Viewing a fileViewing the history of changes to a file](source-files-view-history.md). You can also view commits by using your Git client. For more information, see your Git documentation. **To view commits (console)** 1. Navigate to the project that contains the source repository where you want to view commits. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to view commits to a branch. 1. The default branch of the repository is displayed, including information about the most recent commit to the branch. Choose **Commits**. Alternatively, choose **More**, and then choose **View commits**. 1. To view commits for a different branch, choose the branch selector, and then choose the name of the branch. 1. To view details about a particular commit, choose its title from **Commit title**. Details of the commit are displayed, including information about its parent commit and the changes made to the code by comparing the parent commit to the specified commit. **Tip** If a commit has more than one parent, you can choose which parent commit to view information and display changes for by choosing the drop-down icon next to the parent commit ID. ## Changing how commits are displayed (CodeCatalyst console) You can change what information is displayed in the **Commits** view. You can choose to hide or display columns such as author and commit ID. **To change how commits are displayed (console)** 1. Navigate to the project that contains the source repository where you want to view commits. 1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, and then choose **Source repositories**. Choose the repository where you want to change how you view commits. 1. The default branch of the repository is displayed, including information about the most recent commit to the branch. Choose **Commits**. 1. Choose the gear icon. 1. In **Preferences**, choose the number of commits to display, and choose whether to display information about commit author, commit date, and the commit ID. **Note** You can't hide the commit title in the display of information. 1. When you have made your changes, choose **Save** to save them, or **Cancel** to discard them. # Quotas for source repositories in CodeCatalyst The following table describes quotas and limits for source repositories in Amazon CodeCatalyst. For more information about quotas in Amazon CodeCatalyst, see [Quotas for CodeCatalyst](quotas.md). | Resource | Information | | --- | --- | | Branch names | Any combination of allowed characters between 1 and 256 characters in length and must be unique within a repository. Branch names cannot: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/source-quotas.html) Branch names are references. Many of the limitations on branch names are based on the Git reference standard. For more information, see [Git Internals](https://git-scm.com/book/en/v2/Git-Internals-Git-References) and [git-check-ref-format](https://git-scm.com/docs/git-check-ref-format). | | Comments on a pull request | Maximum of 1,000 on a pull request. | | Commit message | Maximum of 1024 characters. | | File paths | Any combination of allowed characters between 1 and 4,096 characters in length. File paths must be an unambiguous name that specifies the file and the exact location of the file. File paths cannot exceed 20 directories in depth. In addition, file paths cannot:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/source-quotas.html) File names and paths must be fully qualified. The name and path to a file on your local computer must follow the standards for that operating system. When specifying the path to a file in a repository, use the standards for Amazon Linux. | | File size | Maximum of 6 MB for any individual file when using the CodeCatalyst console. | | File size viewable in the CodeCatalyst console | Maximum of 6 MB for any individual file when using the CodeCatalyst console. | | Git blob size | Maximum of 2 GB. There is no limit on the number or the total size of all files in a single commit, as long as the metadata does not exceed 6 MB and a single blob does not exceed 2 GB. However, as a best practice, consider making multiple smaller commits rather than one large commit. | | Metadata for a commit | Maximum of 6 MB for the combined [metadata for a commit](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) (for example, the combination of author information, date, parent commit list, and commit messages). There is no limit on the number or the total size of all files in a single commit, as long as the data does not exceed 20 MB, an individual file does not exceed 6 MB, and a single blob does not exceed 2 GB. | | Number of CodeCatalyst issues that can be linked to a pull request | 50 | | Number of Jira issues that can be linked to a pull request | 50 | | Number of open pull requests in a space | Maximum of 1,000 for an Amazon CodeCatalyst space. | | Number of total pull requests in a space | Maximum of 10,000 for an Amazon CodeCatalyst space. | | Number of references in a single push | Maximum of 4,000, including create, delete, and update. There is no limit on the overall number of references in the repository. | | Number of repositories in a space | Maximum of 5,000 for an Amazon CodeCatalyst space. | | Repository descriptions | Any combination of characters between 0 and 1,000 characters in length. Repository descriptions are optional. | | Repository names | Repository names must be unique within a project. They can contain any combination of letters, numbers, periods, underscores, and dashes between 1 and 100 characters in length. Names are not case sensitive. Repository names cannot end in .git, cannot contain spaces, and cannot contain any of the following characters: `! ? @ # $ % ^ & * ( ) + = { } [ ] \| \ / > < ~ ` ' " ; : ` | | Repository size | Repository sizes are impacted by the overall storage limits for your space. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing) and [Troubleshooting problems with source repositories](troubleshooting-source.md). | | Reviewers for a pull request | Maximum of 100 reviewers total (optional or required) for a pull request. | | Written summaries for pull requests | The maximum number of written summaries for pull requests depends on the billing tier for your space. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing). |