> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Repositories

> Connect Git, Helm, and OCI repositories to ArgoCD for application deployments

ArgoCD Repositories store connection credentials for Git repositories, Helm chart repositories, and OCI registries. Applications use these credentials to fetch manifests and deploy to Kubernetes clusters.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Repository" icon="git-alt">
    A source location containing application manifests, Helm charts, or container images.
  </Card>

  <Card title="Repository Type" icon="tags">
    The format of the repository: Git (source code), Helm (charts), or OCI (images).
  </Card>

  <Card title="Credentials" icon="key">
    Username and access token for authenticating with private repositories.
  </Card>

  <Card title="Connection Status" icon="signal">
    Health status indicating whether ArgoCD can connect to the repository.
  </Card>
</CardGroup>

## Required Permissions

| Action              | Permission                       |
| ------------------- | -------------------------------- |
| View repositories   | `iam:project:cicd:argocd:read`   |
| Add repositories    | `iam:project:cicd:argocd:write`  |
| Edit repositories   | `iam:project:cicd:argocd:write`  |
| Delete repositories | `iam:project:cicd:argocd:delete` |

## Repository Types

| Type     | Description                                        | URL Format                          |
| -------- | -------------------------------------------------- | ----------------------------------- |
| **Git**  | Source code repositories with Kubernetes manifests | `https://github.com/org/repo.git`   |
| **Helm** | Helm chart repositories                            | `https://charts.example.com`        |
| **OCI**  | OCI-compliant container registries for Helm charts | `oci://registry.example.com/charts` |

## Connection Status

| Status         | Description                                        |
| -------------- | -------------------------------------------------- |
| **Successful** | Repository is accessible and credentials are valid |
| **Failed**     | Connection or authentication failed                |
| **Unknown**    | Status not yet determined                          |

## How to Add a Repository

<Steps>
  <Step title="Select ArgoCD Instance">
    Choose the ArgoCD instance from the dropdown in the toolbar.
  </Step>

  <Step title="Click Add Repository">
    Click the **Add Repository** button in the header.
  </Step>

  <Step title="Enter Repository Name">
    Provide a friendly display name to identify the repository.
  </Step>

  <Step title="Enter Repository URL">
    Enter the full repository URL.
  </Step>

  <Step title="Select Repository Type">
    Choose **Git**, **Helm**, or **OCI** based on the repository contents.
  </Step>

  <Step title="Enter Credentials (Optional)">
    For private repositories, enter username and access token.
  </Step>

  <Step title="Assign Project (Optional)">
    Select a project to restrict repository access, or leave empty for global access.
  </Step>

  <Step title="Configure TLS (Optional)">
    Enable insecure mode to skip TLS verification if needed.
  </Step>

  <Step title="Add">
    Click **Add Repository** to save.
  </Step>
</Steps>

## Required Fields

| Field              | Required | Description                                 |
| ------------------ | -------- | ------------------------------------------- |
| **Name**           | Yes      | Friendly identifier for the repository      |
| **Repository URL** | Yes      | Full URL to the repository                  |
| **Type**           | Yes      | Repository type (git, helm, oci)            |
| **Username**       | No       | Authentication username (for private repos) |
| **Access Token**   | No       | Personal access token or password           |
| **Project**        | No       | Restrict access to specific project         |
| **Insecure**       | No       | Skip TLS certificate verification           |

## URL Formats

### Git Repositories

| Provider      | HTTPS Format                         | SSH Format                       |
| ------------- | ------------------------------------ | -------------------------------- |
| **GitHub**    | `https://github.com/org/repo.git`    | `git@github.com:org/repo.git`    |
| **GitLab**    | `https://gitlab.com/org/repo.git`    | `git@gitlab.com:org/repo.git`    |
| **Bitbucket** | `https://bitbucket.org/org/repo.git` | `git@bitbucket.org:org/repo.git` |

### Helm Repositories

| Type            | Format                                         |
| --------------- | ---------------------------------------------- |
| **Standard**    | `https://charts.example.com`                   |
| **ChartMuseum** | `https://chartmuseum.example.com`              |
| **Harbor**      | `https://harbor.example.com/chartrepo/library` |

### OCI Repositories

| Registry       | Format                                       |
| -------------- | -------------------------------------------- |
| **Docker Hub** | `oci://registry-1.docker.io/org`             |
| **GitHub**     | `oci://ghcr.io/org`                          |
| **AWS ECR**    | `oci://account.dkr.ecr.region.amazonaws.com` |

## How to Edit a Repository

<Steps>
  <Step title="Find the Repository">
    Locate the repository in the list using search.
  </Step>

  <Step title="Click Edit">
    Click the edit (pencil) icon on the repository row.
  </Step>

  <Step title="Modify Settings">
    Update name, credentials, project assignment, or TLS settings.
  </Step>

  <Step title="Update Credentials (Optional)">
    Enter a new access token only if rotating credentials. Leave empty to keep the existing token.
  </Step>

  <Step title="Save">
    Click **Update Repository** to apply changes.
  </Step>
</Steps>

<Info>
  Repository URL cannot be changed after creation. To use a different URL, delete the repository and create a new one.
</Info>

## How to Delete a Repository

<Steps>
  <Step title="Find the Repository">
    Locate the repository to delete.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon on the repository row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting a repository removes its credentials from ArgoCD. Applications using this repository will fail to sync until credentials are restored.
</Warning>

## Authentication

### Public Repositories

No credentials required. Leave username and access token empty.

### Private Repositories

| Provider      | Username           | Access Token                                       |
| ------------- | ------------------ | -------------------------------------------------- |
| **GitHub**    | GitHub username    | Personal Access Token with `repo` scope            |
| **GitLab**    | GitLab username    | Personal Access Token with `read_repository` scope |
| **Bitbucket** | Bitbucket username | App Password with repository read access           |

<Tip>
  Always use Personal Access Tokens instead of passwords. Most Git providers no longer support password authentication for API access.
</Tip>

### Token Scopes

#### GitHub

Required scopes for Personal Access Token:

* `repo` - Full control of private repositories

#### GitLab

Required scopes for Personal Access Token:

* `read_repository` - Read repository content
* `read_api` - Read API access (for repository operations)

#### Bitbucket

Required permissions for App Password:

* Repositories: Read

## Project Assignment

Repositories can be assigned to specific ArgoCD projects to restrict access.

| Setting              | Behavior                                          |
| -------------------- | ------------------------------------------------- |
| **None (Global)**    | Repository available to all projects              |
| **Specific Project** | Repository only available to the assigned project |

<Info>
  Use project assignment to implement least-privilege access. Production repositories should typically be restricted to production projects only.
</Info>

## TLS Configuration

### Secure Mode (Default)

TLS certificate verification is enabled by default. ArgoCD validates the repository server's certificate against trusted CAs.

### Insecure Mode

Enable "Allow Insecure Connection" to skip TLS verification.

<Warning>
  Insecure mode should only be used for development or with self-signed certificates. Always use proper TLS in production.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection status shows Failed" icon="circle-question">
    * Verify the repository URL is correct
    * Check if credentials are valid and not expired
    * Ensure the repository exists and is accessible
    * Verify network connectivity from ArgoCD to the repository
    * Check if IP restrictions block ArgoCD's access
  </Accordion>

  <Accordion title="Authentication failed" icon="circle-question">
    * Verify username is correct
    * Check if the access token has required scopes
    * Ensure the token has not expired
    * For GitHub, verify you're using a PAT, not a password
    * Check if the repository requires SSO authentication
  </Accordion>

  <Accordion title="Cannot access private repository" icon="circle-question">
    * Verify credentials are configured for this repository
    * Check if the token has repository access permissions
    * Ensure the user has access to the repository in Git provider
    * For organization repos, verify organization access is granted
  </Accordion>

  <Accordion title="TLS certificate error" icon="circle-question">
    * Verify the repository uses a valid TLS certificate
    * For self-signed certificates, enable insecure mode
    * Check if the certificate has expired
    * Ensure ArgoCD trusts the certificate authority
  </Accordion>

  <Accordion title="Helm chart not found" icon="circle-question">
    * Verify the repository type is set to "helm"
    * Check if the chart exists in the repository
    * Ensure the repository URL points to the chart index
    * Verify chart version exists
  </Accordion>

  <Accordion title="OCI registry authentication failed" icon="circle-question">
    * Verify the registry URL format (`oci://...`)
    * Check if credentials have registry access
    * Ensure the repository type is set to "oci"
    * Verify the registry supports OCI artifacts
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use SSH keys for authentication?">
    SSH key authentication is supported but must be configured through the ArgoCD CLI or API. The UI currently supports username/token authentication only.
  </Accordion>

  <Accordion title="How do I rotate repository credentials?">
    Edit the repository and enter the new access token. Leave the field empty to keep the existing credentials. Old credentials are replaced immediately.
  </Accordion>

  <Accordion title="Can multiple repositories use the same credentials?">
    No. Each repository stores its own credentials. However, you can use the same access token across multiple repository entries.
  </Accordion>

  <Accordion title="What happens if credentials expire?">
    Applications using the repository will fail to sync with authentication errors. Update the repository with new credentials to restore access.
  </Accordion>

  <Accordion title="Can I use deploy keys instead of personal tokens?">
    Deploy keys are supported through SSH authentication, which requires CLI configuration. For UI-based setup, use Personal Access Tokens.
  </Accordion>

  <Accordion title="Why is my repository URL not editable?">
    Repository URLs are immutable after creation because applications reference them. To change the URL, delete the repository and create a new one.
  </Accordion>

  <Accordion title="How do I access repositories from multiple Git providers?">
    Create separate repository entries for each provider. Each entry can have different credentials and settings.
  </Accordion>

  <Accordion title="Can I use OAuth tokens instead of PATs?">
    OAuth tokens work if they have the required scopes. However, PATs are recommended as they're easier to manage and don't expire based on OAuth sessions.
  </Accordion>
</AccordionGroup>

## Best Practices

### Security

* Use Personal Access Tokens with minimum required scopes
* Rotate tokens periodically (every 90 days recommended)
* Use project assignment to restrict repository access
* Avoid using personal accounts for CI/CD repositories
* Create dedicated service accounts or machine users

### Organization

* Use descriptive repository names
* Group related repositories by naming convention
* Document which applications use each repository
* Remove unused repository entries

### Credentials

* Never share credentials between environments
* Store tokens securely before adding to the platform
* Set up monitoring for authentication failures
* Have a runbook for credential rotation

### Repository Types

* Use **Git** for source code with Kubernetes manifests
* Use **Helm** for chart repositories
* Use **OCI** for Helm charts stored in container registries
* Consider OCI for better security and versioning

### TLS

* Always use TLS in production
* Use proper certificates from trusted CAs
* Avoid insecure mode except for development
* Monitor certificate expiration dates