# Git repositories
<a name="working-with-repositories"></a>

Repositories provide version control for project artifacts, including branching, commit history, and collaboration workflows. When a repository is added to a project, members can track artifacts, create branches, and commit and push changes to a remote repository on GitHub, GitLab, or Bitbucket. A project can use any number of repositories and branches simultaneously, with each repository operating independently. Repositories are appropriate for production workloads requiring change attribution, CI/CD integration, or safe branching for iteration.

## How S3 shared storage and repositories coexist
<a name="repos-coexist"></a>

When you create work in a project, you decide whether to version-control it. If you do nothing, your work is saved normally. If you want version history, branching, and the ability to push to a remote repository, you add the artifact to a repository. This is a per-artifact choice.

Artifacts exist in one of two states:
+ **Untracked** — Stored through the tool's default mechanism and visible to project members according to the tool's save behavior.
+ **Tracked in a repository** — Changes you make are saved to your project as usual and tracked in your selected repository and branch, ready to be committed and pushed to the remote.

You choose per-artifact whether to track it by using the Add to repository action. Files that come from a cloned repository are tracked automatically when you open them in a tool. Only new artifacts that you create in the project require manual tracking.

## Supported tools
<a name="repos-supported-tools"></a>

Repository tracking is available in Query Editor, Visual ETL, Workflows, and Notebooks. JupyterLab and Code Editor support full Git operations through their built-in terminals and Git extensions.

## Supported providers
<a name="repos-supported-providers"></a>

The following Git providers are supported:
+ GitHub Cloud
+ GitHub Enterprise Server
+ GitLab Cloud
+ GitLab Self-Managed
+ Bitbucket Cloud

All connections are managed through AWS CodeConnections. AWS CodeCommit is not supported for new projects. Repository tracking is available in both IAM and IAM Identity Center (IDC) domains.

## Prerequisites
<a name="repos-prerequisites"></a>

Before you can work with repositories, you must meet the following requirements:

1. A domain administrator has created and enabled at least one Git connection.

1. You have project owner or member permissions to add repositories.

## Adding a repository
<a name="repos-adding"></a>

There is no fixed limit on the number of repositories per project, and you can use any number of repositories and branches simultaneously. The recommended size limit per repository is 1 GB with up to 20,000 files.

**To add a repository**

1. Open the **Repositories** page from the left navigation.

1. Choose **Add Repository**.

1. Select a connection, then select an existing repository or create a new one.

1. Select a default branch.

1. Choose **Add**.

### What happens when you add a repository
<a name="repos-cloning-behavior"></a>

When you add a repository, Amazon SageMaker Unified Studio creates a local clone that is shared across all project members. The clone behaves as follows:
+ The default branch you select is cloned into the project. Other branches from the remote repository are listed and available but are cloned on first access.
+ The local clone automatically tracks changes made to any of its files. When you open a file from the repository in a tool, it is tracked automatically.
+ Cloning time depends on the size of the repository. The clone is stored in the project's S3 bucket.
+ After cloning completes, files are visible on the repository details page. However, these files do not appear in any tool's artifact list until you navigate to the repository details page and explicitly open a file in its respective tool.

**Important**  
When you connect a project to a third-party Git repository, all users who can sign in to any domain in the account have read and write access to all repositories on that connection. This access is not limited to the project or domain where the connection was created. To enforce isolation between repositories, use separate AWS accounts.

## Removing a repository
<a name="repos-removing"></a>

You can remove a repository from your project at any time. Removing a repository disconnects the project from the remote repository but does not delete the remote repository itself.

When you remove a repository:
+ The local clone is deleted from the project.
+ Any artifacts that were tracked in that repository become untracked. Your artifacts remain in the project and you can continue working with them.
+ The remote repository is not affected. You can re-add it later if needed.

To remove a repository, open the **Repositories** page, choose the actions menu for the repository you want to remove, and choose **Remove**.

## Branch management
<a name="repos-branches"></a>

Branches are independent lines of development within a repository. Each branch maintains its own copy of tracked artifacts, so changes on one branch do not affect another until explicitly merged in your Git provider. Project members can open artifacts from any branch in any tool simultaneously.

### Viewing and switching branches
<a name="repos-viewing-branches"></a>

Open the details page of your repository and use the branch selector next to the repository name. Switching branches changes which files are displayed on the repository details page, but does not affect tools — you can open artifacts from any branch simultaneously without switching.

### Creating a branch
<a name="repos-creating-branch"></a>

**To create a branch**

1. Open the **Repositories** page from the left navigation.

1. Open the branch selector.

1. Choose **Create branch**.

1. Select the source branch to create from.

1. Enter a name.

1. Choose **Create**.

When you create a branch, it is created on the remote first and then cloned into your project. If you switch to a branch that has not been cloned previously, the system clones it and you might see a brief loading state. After the initial clone, subsequent switches are immediate.

**Note**  
As a best practice, each project member should use a separate branch to avoid accidentally overriding or pushing another member's work.

## Tracking artifacts in a repository
<a name="repos-tracking"></a>

### Adding an artifact to a repository
<a name="repos-add-artifact"></a>

By default, new artifacts are not version-controlled. When you decide an artifact needs version control, you explicitly add it. Files from a cloned repository are already tracked automatically when you open them in a tool.

**To track a new artifact**

1. Open the artifact in its tool (Query Editor, Visual ETL, Workflows, or Notebooks).

1. Choose the **Add to repository** icon.

1. Select the target repository and branch.

From that point, changes are tracked. Changes are automatically staged locally and ready to be committed and pushed. You cannot select a specific folder path within the repository during this step.

### Artifact statuses
<a name="repos-artifact-statuses"></a>

The following table describes the statuses that tracked artifacts can have.


**Artifact statuses**  

| Status | Meaning | 
| --- | --- | 
| Added | Newly tracked and not yet pushed to the remote | 
| Modified | Changed since the last push | 
| Deleted | Removed locally, pending push to delete from the remote | 

### Removing tracking
<a name="repos-removing-tracking"></a>

The **Remove from repository** action stops tracking an artifact. The artifact itself remains saved to your project — your work is not lost.
+ If the artifact had never been pushed, it disappears from the repository details page immediately.
+ If it had been previously pushed, it appears with a status of "Deleted" until the next push, at which point the file is removed from the remote.

## Committing and pushing
<a name="repos-commit-push"></a>

Changes accumulate locally but are not pushed until you explicitly choose to do so. Commit and push is a single combined action under the **Push** button — you cannot commit without pushing.

**To commit and push changes**

1. Open the **Repositories** page.

1. Choose **Push** on the repository with uncommitted changes.

1. Review the list of changed artifacts and select or clear items to include.

1. Enter a commit message describing your changes.

1. Choose **Push**.

You can also access this action from the branch dropdown on any tracked artifact.

**Tip**  
Push is not available when there are unpulled changes from the remote, so you must pull before you can push.

## Pulling changes
<a name="repos-pulling"></a>

When teammates push changes, those changes do not appear until you pull. The **Repositories** page shows a "pull available" indicator when remote changes exist.

**To pull changes**

1. Open the **Repositories** page.

1. Choose **Pull** on the repository with available updates.

Pull performs a rebase, meaning your local changes are replayed on top of remote changes. You cannot pull while you have uncommitted local changes that conflict with the remote. If this happens, you must commit and push first, or use the terminal in JupyterLab or Code Editor.

## Resolving conflicts
<a name="repos-conflicts"></a>

If you have uncommitted local changes when you attempt to pull, an error is displayed. To proceed, you must either undo local changes or use JupyterLab/Code Editor to commit or handle them.

If you use an IDE to resolve local changes and then pull, and remote changes conflict with your committed work, the merge conflict resolution panel is shown. Amazon SageMaker Unified Studio displays a JSON diff and lets you choose local or remote on a per-artifact basis.

For complex conflicts, use the Git provider's interface or the terminal.

## How repositories work with each tool
<a name="repos-per-tool"></a>

Each tool stores artifacts differently. The following table describes how repository tracking works in each tool.


| Tool | Behavior | Save model | 
| --- | --- | --- | 
| Query Editor | Files stored as .sqlnb | Explicit save | 
| Notebooks | Autosaves internally. Current state materialized to repository at commit time. File format: notebook\_name (notebook\_ID).ipynb. Renaming in the studio does not rename the repo file. Only one user can edit at a time due to locking. | Autosave | 
| Visual ETL | Creates two files per job: a .py script and a .vetl graph definition. Both tracked as a set and must not be deleted individually. | Explicit save | 
| Workflows | Stored as .yaml files. Only serverless workflows supported for repository tracking. | Explicit save | 
| JupyterLab and Code Editor | Full Git CLI through the terminal. Changes in the terminal are reflected on the Repositories page after refresh, and vice versa. | Git CLI | 

Changes pushed from outside your project (for example, directly in GitHub by a teammate) are synced to your tool state after you pull.

## When a remote repository is deleted
<a name="repos-remote-deleted"></a>

If someone deletes the remote repository from your Git provider (for example, deletes the repository in GitHub), the local clone in your project becomes disconnected. The following behavior applies:
+ Push and pull operations fail because the remote no longer exists.
+ Artifacts that were tracked remain in the project but can no longer sync with the remote.
+ The repository continues to appear on the Repositories page until you remove it.

To resolve this, remove the disconnected repository from your project and add a new one if needed.

## Known limitations
<a name="repos-limitations"></a>

The following limitations apply to repositories in Amazon SageMaker Unified Studio:
+ No pull requests or code reviews within the product — use your Git provider.
+ No commit history browsing — use your Git provider.
+ No revert action in the UI — use the terminal or your Git provider.
+ No automatic artifact tracking.
+ No programmatic API for repository operations.
+ Managed and provisioned workflows are not supported for repository tracking.
+ Jobs does not support repository tracking.
+ Git worktrees are not supported.
+ Repository management is available through the console only.