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).
# 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**.