> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository API

> Git and Helm repository configuration and management in Argo CD

## Overview

The Repository Service API manages repository configurations for Git and Helm repositories. Repositories are the source of application manifests and must be registered with Argo CD.

**Base Path:** `/api/v1/repositories`

**gRPC Service:** `repository.RepositoryService`

## Repository Resource

A Repository represents a Git or Helm repository containing application manifests.

### Repository Spec

<ParamField path="repo" type="string" required>
  Repository URL

  ```yaml theme={null}
  # Git repositories
  repo: https://github.com/myorg/myrepo
  repo: git@github.com:myorg/myrepo.git

  # Helm repositories
  repo: https://charts.helm.sh/stable

  # OCI registries
  repo: oci://ghcr.io/myorg/charts
  ```
</ParamField>

<ParamField path="type" type="string">
  Repository type: "git" (default), "helm", or "oci"
</ParamField>

<ParamField path="name" type="string">
  Repository name (required for Helm repos)
</ParamField>

<ParamField path="project" type="string">
  Project that owns this repository
</ParamField>

### Authentication Fields

<ParamField path="username" type="string">
  Username for HTTPS authentication
</ParamField>

<ParamField path="password" type="string">
  Password or personal access token
</ParamField>

<ParamField path="sshPrivateKey" type="string">
  SSH private key (PEM format) for Git repos
</ParamField>

<ParamField path="bearerToken" type="string">
  Bearer token for Git authentication (BitBucket Data Center)
</ParamField>

<ParamField path="tlsClientCertData" type="string">
  TLS client certificate (PEM format)
</ParamField>

<ParamField path="tlsClientCertKey" type="string">
  TLS client certificate key (PEM format)
</ParamField>

### GitHub App Authentication

<ParamField path="githubAppPrivateKey" type="string">
  GitHub App private key (PEM format)
</ParamField>

<ParamField path="githubAppID" type="int64">
  GitHub App ID
</ParamField>

<ParamField path="githubAppInstallationID" type="int64">
  GitHub App installation ID
</ParamField>

<ParamField path="githubAppEnterpriseBaseUrl" type="string">
  GitHub Enterprise API URL (default: [https://api.github.com](https://api.github.com))
</ParamField>

### Cloud Provider Authentication

<ParamField path="gcpServiceAccountKey" type="string">
  GCP service account key (JSON format) for Google Cloud Source repos
</ParamField>

<ParamField path="useAzureWorkloadIdentity" type="boolean">
  Use Azure Workload Identity for authentication
</ParamField>

### Additional Options

<ParamField path="insecure" type="boolean">
  Skip TLS certificate or SSH host key validation
</ParamField>

<ParamField path="enableLfs" type="boolean">
  Enable Git LFS support (Git repos only)
</ParamField>

<ParamField path="enableOCI" type="boolean">
  Enable OCI support for Helm repos
</ParamField>

<ParamField path="proxy" type="string">
  HTTP/HTTPS proxy URL
</ParamField>

<ParamField path="forceHttpBasicAuth" type="boolean">
  Force HTTP basic authentication
</ParamField>

<ParamField path="insecureOCIForceHttp" type="boolean">
  Use HTTP instead of HTTPS for OCI repos
</ParamField>

<ParamField path="depth" type="int64">
  Git shallow clone depth (0 = full clone)
</ParamField>

### Example Repository

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  type: git
  url: https://github.com/myorg/private-repo
  username: myuser
  password: ghp_mytoken123
  project: production
```

## API Operations

### List Repositories

Retrieve list of configured repositories.

```bash theme={null}
GET /api/v1/repositories
```

<ParamField query="repo" type="string">
  Filter by repository URL
</ParamField>

<ParamField query="forceRefresh" type="boolean">
  Force refresh connection state
</ParamField>

<ParamField query="appProject" type="string">
  Filter by project
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://argocd-server/api/v1/repositories \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  import repositorypkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/repository"

  repoClient := repositorypkg.NewRepositoryServiceClient(conn)
  repos, err := repoClient.ListRepositories(ctx, &repositorypkg.RepoQuery{})
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://argocd-server/api/v1/repositories",
      headers={"Authorization": f"Bearer {token}"}
  )
  repos = response.json()
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "items": [
    {
      "repo": "https://github.com/argoproj/argocd-example-apps",
      "type": "git",
      "connectionState": {
        "status": "Successful",
        "message": "repository is accessible"
      },
      "project": "default"
    }
  ]
}
```

### Get Repository

Retrieve a specific repository.

```bash theme={null}
GET /api/v1/repositories/{repo}
```

<ParamField path="repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

<ParamField query="forceRefresh" type="boolean">
  Force refresh connection state
</ParamField>

<ParamField query="appProject" type="string">
  Project context
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  REPO=$(echo -n "https://github.com/myorg/myrepo" | jq -sRr @uri)
  curl "https://argocd-server/api/v1/repositories/${REPO}" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  repo, err := repoClient.Get(ctx, &repositorypkg.RepoQuery{
      Repo: "https://github.com/myorg/myrepo",
  })
  ```
</CodeGroup>

### Create Repository

Register a new repository.

```bash theme={null}
POST /api/v1/repositories
```

<ParamField body="repo" type="Repository" required>
  Complete Repository configuration
</ParamField>

<ParamField body="upsert" type="boolean">
  Update if already exists (default: false)
</ParamField>

<ParamField body="credsOnly" type="boolean">
  Create as credential template instead of repository
</ParamField>

<CodeGroup>
  ```bash Git with HTTPS theme={null}
  curl -X POST https://argocd-server/api/v1/repositories \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "repo": "https://github.com/myorg/private-repo",
      "username": "myuser",
      "password": "ghp_mytoken123",
      "type": "git",
      "project": "production"
    }'
  ```

  ```bash Git with SSH theme={null}
  curl -X POST https://argocd-server/api/v1/repositories \
    -H "Authorization: Bearer $TOKEN" \
    -d '{
      "repo": "git@github.com:myorg/private-repo.git",
      "sshPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...",
      "type": "git"
    }'
  ```

  ```bash Helm Repository theme={null}
  curl -X POST https://argocd-server/api/v1/repositories \
    -H "Authorization: Bearer $TOKEN" \
    -d '{
      "repo": "https://charts.helm.sh/stable",
      "name": "stable",
      "type": "helm"
    }'
  ```

  ```bash OCI Registry theme={null}
  curl -X POST https://argocd-server/api/v1/repositories \
    -H "Authorization: Bearer $TOKEN" \
    -d '{
      "repo": "oci://ghcr.io/myorg/charts",
      "username": "myuser",
      "password": "ghp_token",
      "type": "helm",
      "enableOCI": true
    }'
  ```

  ```go Go theme={null}
  repo, err := repoClient.CreateRepository(ctx, &repositorypkg.RepoCreateRequest{
      Repo: &v1alpha1.Repository{
          Repo:     "https://github.com/myorg/private-repo",
          Username: "myuser",
          Password: "ghp_mytoken123",
          Type:     "git",
          Project:  "production",
      },
      Upsert: false,
  })
  ```

  ```bash CLI theme={null}
  # Using argocd CLI
  argocd repo add https://github.com/myorg/private-repo \
    --username myuser \
    --password ghp_mytoken123 \
    --project production
  ```
</CodeGroup>

### Update Repository

Update repository configuration.

```bash theme={null}
PUT /api/v1/repositories/{repo.repo}
```

<ParamField path="repo.repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

<ParamField body="repo" type="Repository" required>
  Updated repository configuration
</ParamField>

### Delete Repository

Remove a repository.

```bash theme={null}
DELETE /api/v1/repositories/{repo}
```

<ParamField path="repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  REPO=$(echo -n "https://github.com/myorg/myrepo" | jq -sRr @uri)
  curl -X DELETE "https://argocd-server/api/v1/repositories/${REPO}" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```go Go theme={null}
  _, err := repoClient.DeleteRepository(ctx, &repositorypkg.RepoQuery{
      Repo: "https://github.com/myorg/myrepo",
  })
  ```
</CodeGroup>

## Repository Operations

### Validate Access

Test repository connectivity and credentials.

```bash theme={null}
POST /api/v1/repositories/{repo}/validate
```

<ParamField path="repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

<ParamField body="All repository fields" type="object">
  Provide all authentication fields for validation
</ParamField>

**Example:**

```bash theme={null}
curl -X POST "https://argocd-server/api/v1/repositories/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "repo": "https://github.com/myorg/private-repo",
    "username": "myuser",
    "password": "ghp_newtoken",
    "type": "git"
  }'
```

**Response:**

```json theme={null}
{
  "status": "Successful",
  "message": "repository is accessible"
}
```

### List Repository Apps

Discover applications in a repository.

```bash theme={null}
GET /api/v1/repositories/{repo}/apps
```

<ParamField path="repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

<ParamField query="revision" type="string">
  Git revision (default: HEAD)
</ParamField>

<ParamField query="appName" type="string">
  Application name context
</ParamField>

<ParamField query="appProject" type="string">
  Project context
</ParamField>

**Response:**

```json theme={null}
{
  "items": [
    {
      "type": "Kustomize",
      "path": "kustomize-guestbook"
    },
    {
      "type": "Helm",
      "path": "helm-guestbook"
    },
    {
      "type": "Directory",
      "path": "guestbook"
    }
  ]
}
```

### Get App Details

Get detailed information about an application in the repository.

```bash theme={null}
POST /api/v1/repositories/{source.repoURL}/appdetails
```

<ParamField body="source" type="ApplicationSource" required>
  Application source configuration
</ParamField>

<ParamField body="appName" type="string">
  Application name
</ParamField>

<ParamField body="appProject" type="string">
  Project name
</ParamField>

### List Helm Charts

List available Helm charts in a Helm repository.

```bash theme={null}
GET /api/v1/repositories/{repo}/helmcharts
```

<ParamField path="repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

**Response:**

```json theme={null}
{
  "items": [
    {
      "name": "nginx",
      "versions": ["1.0.0", "0.9.0"]
    },
    {
      "name": "redis",
      "versions": ["2.1.0", "2.0.0"]
    }
  ]
}
```

### List Refs

List Git branches and tags.

```bash theme={null}
GET /api/v1/repositories/{repo}/refs
```

<ParamField path="repo" type="string" required>
  Repository URL (URL-encoded)
</ParamField>

**Response:**

```json theme={null}
{
  "branches": ["main", "develop", "feature/new-app"],
  "tags": ["v1.0.0", "v0.9.0"]
}
```

### List OCI Tags

List available tags in an OCI repository.

```bash theme={null}
GET /api/v1/repositories/{repo}/oci-tags
```

## Write Repositories

Separate read and write repositories for source hydration workflows.

### List Write Repositories

```bash theme={null}
GET /api/v1/write-repositories
```

### Get Write Repository

```bash theme={null}
GET /api/v1/write-repositories/{repo}
```

### Create Write Repository

```bash theme={null}
POST /api/v1/write-repositories
```

### Update Write Repository

```bash theme={null}
PUT /api/v1/write-repositories/{repo.repo}
```

### Delete Write Repository

```bash theme={null}
DELETE /api/v1/write-repositories/{repo}
```

## Authentication Examples

### GitHub Personal Access Token

```json theme={null}
{
  "repo": "https://github.com/myorg/private-repo",
  "username": "myuser",
  "password": "ghp_xxxxxxxxxxxxxxxxxxxx",
  "type": "git"
}
```

### GitHub App

```json theme={null}
{
  "repo": "https://github.com/myorg/private-repo",
  "type": "git",
  "githubAppPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...",
  "githubAppID": 123456,
  "githubAppInstallationID": 789012
}
```

### GitLab Token

```json theme={null}
{
  "repo": "https://gitlab.com/myorg/private-repo",
  "username": "oauth2",
  "password": "glpat-xxxxxxxxxxxxxxxxxxxx",
  "type": "git"
}
```

### SSH Key

```json theme={null}
{
  "repo": "git@github.com:myorg/private-repo.git",
  "type": "git",
  "sshPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"
}
```

### Helm with Basic Auth

```json theme={null}
{
  "repo": "https://charts.example.com",
  "name": "myrepo",
  "type": "helm",
  "username": "user",
  "password": "pass"
}
```

### Google Cloud Source Repositories

```json theme={null}
{
  "repo": "https://source.developers.google.com/p/myproject/r/myrepo",
  "type": "git",
  "gcpServiceAccountKey": "{\"type\":\"service_account\",...}"
}
```

## Connection State

Repositories report their connection status:

```json theme={null}
{
  "connectionState": {
    "status": "Successful",
    "message": "repository is accessible",
    "attemptedAt": "2024-03-04T12:00:00Z"
  }
}
```

**Status Values:**

* `Successful`: Repository is accessible
* `Failed`: Connection or authentication failed
* `Unknown`: Status not yet determined

## Repository Credentials

Credential templates can be shared across multiple repositories.

### Create Credential Template

```bash theme={null}
curl -X POST https://argocd-server/api/v1/repositories \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "repo": "https://github.com/myorg",
    "username": "myuser",
    "password": "token",
    "type": "git",
    "credsOnly": true
  }'
```

Repositories matching the URL prefix will inherit these credentials.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Fine-Grained Tokens">
    Use repository-scoped tokens with minimal permissions:

    * GitHub: Use fine-grained PATs with read-only repo access
    * GitLab: Use project access tokens
    * Bitbucket: Use repository access tokens
  </Accordion>

  <Accordion title="Enable TLS Verification">
    Always verify TLS certificates in production:

    ```json theme={null}
    {"insecure": false}
    ```
  </Accordion>

  <Accordion title="Use SSH for Private Repos">
    SSH keys are generally more secure than HTTPS tokens for Git.
  </Accordion>

  <Accordion title="Rotate Credentials">
    Regularly rotate repository credentials and tokens.
  </Accordion>

  <Accordion title="Use Credential Templates">
    Share credentials across repositories to reduce duplication.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Application API" icon="rocket" href="/api/application">
    Create applications from repositories
  </Card>

  <Card title="Project API" icon="folder" href="/api/appproject">
    Configure allowed repositories
  </Card>
</CardGroup>