Repository API - 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

string

required

Repository URL

# 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

string

Repository type: “git” (default), “helm”, or “oci”

string

Repository name (required for Helm repos)

string

Project that owns this repository

Authentication Fields

string

Username for HTTPS authentication

string

Password or personal access token

string

SSH private key (PEM format) for Git repos

string

Bearer token for Git authentication (BitBucket Data Center)

string

TLS client certificate (PEM format)

string

TLS client certificate key (PEM format)

GitHub App Authentication

string

GitHub App private key (PEM format)

int64

GitHub App ID

int64

GitHub App installation ID

string

GitHub Enterprise API URL (default: https://api.github.com)

Cloud Provider Authentication

string

GCP service account key (JSON format) for Google Cloud Source repos

boolean

Use Azure Workload Identity for authentication

Additional Options

boolean

Skip TLS certificate or SSH host key validation

boolean

Enable Git LFS support (Git repos only)

boolean

Enable OCI support for Helm repos

string

HTTP/HTTPS proxy URL

boolean

Force HTTP basic authentication

boolean

Use HTTP instead of HTTPS for OCI repos

int64

Git shallow clone depth (0 = full clone)

Example Repository

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.

GET /api/v1/repositories

string

Filter by repository URL

boolean

Force refresh connection state

string

Filter by project

curl https://argocd-server/api/v1/repositories \
  -H "Authorization: Bearer $TOKEN"

import repositorypkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/repository"

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

import requests

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

Response:

{
  "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.

GET /api/v1/repositories/{repo}

string

required

Repository URL (URL-encoded)

boolean

Force refresh connection state

string

Project context

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

repo, err := repoClient.Get(ctx, &repositorypkg.RepoQuery{
    Repo: "https://github.com/myorg/myrepo",
})

Create Repository

POST /api/v1/repositories

Repository

required

Complete Repository configuration

boolean

Update if already exists (default: false)

boolean

Create as credential template instead of repository

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"
  }'

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"
  }'

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

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
  }'

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,
})

# Using argocd CLI
argocd repo add https://github.com/myorg/private-repo \
  --username myuser \
  --password ghp_mytoken123 \
  --project production

Update Repository

Update repository configuration.

PUT /api/v1/repositories/{repo.repo}

string

required

Repository URL (URL-encoded)

Repository

required

Updated repository configuration

Delete Repository

Remove a repository.

DELETE /api/v1/repositories/{repo}

string

required

Repository URL (URL-encoded)

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"

_, err := repoClient.DeleteRepository(ctx, &repositorypkg.RepoQuery{
    Repo: "https://github.com/myorg/myrepo",
})

Repository Operations

Validate Access

Test repository connectivity and credentials.

POST /api/v1/repositories/{repo}/validate

string

required

Repository URL (URL-encoded)

object

Provide all authentication fields for validation

Example:

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:

{
  "status": "Successful",
  "message": "repository is accessible"
}

List Repository Apps

Discover applications in a repository.

GET /api/v1/repositories/{repo}/apps

string

required

Repository URL (URL-encoded)

string

Git revision (default: HEAD)

string

Application name context

string

Project context

Response:

{
  "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.

POST /api/v1/repositories/{source.repoURL}/appdetails

ApplicationSource

required

Application source configuration

string

Application name

string

Project name

List Helm Charts

List available Helm charts in a Helm repository.

GET /api/v1/repositories/{repo}/helmcharts

string

required

Repository URL (URL-encoded)

Response:

{
  "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.

GET /api/v1/repositories/{repo}/refs

string

required

Repository URL (URL-encoded)

Response:

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

List OCI Tags

List available tags in an OCI repository.

GET /api/v1/repositories/{repo}/oci-tags

Write Repositories

Separate read and write repositories for source hydration workflows.

List Write Repositories

GET /api/v1/write-repositories

Get Write Repository

GET /api/v1/write-repositories/{repo}

Create Write Repository

POST /api/v1/write-repositories

Update Write Repository

PUT /api/v1/write-repositories/{repo.repo}

Delete Write Repository

DELETE /api/v1/write-repositories/{repo}

Authentication Examples

GitHub Personal Access Token

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

GitHub App

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

GitLab Token

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

SSH Key

{
  "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

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

Google Cloud Source Repositories

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

Connection State

Repositories report their connection status:

{
  "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

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

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

Enable TLS Verification

Always verify TLS certificates in production:

{"insecure": false}

Use SSH for Private Repos

SSH keys are generally more secure than HTTPS tokens for Git.

Rotate Credentials

Regularly rotate repository credentials and tokens.

Use Credential Templates

Share credentials across repositories to reduce duplication.

Next Steps

Application API

Create applications from repositories

Project API

Configure allowed repositories

​Overview

​Repository Resource

​Repository Spec

​Authentication Fields

​GitHub App Authentication

​Cloud Provider Authentication

​Additional Options

​Example Repository

​API Operations

​List Repositories

​Get Repository

​Create Repository

​Update Repository

​Delete Repository

​Repository Operations

​Validate Access

​List Repository Apps

​Get App Details

​List Helm Charts

​List Refs

​List OCI Tags

​Write Repositories

​List Write Repositories

​Get Write Repository

​Create Write Repository

​Update Write Repository

​Delete Write Repository

​Authentication Examples

​GitHub Personal Access Token

​GitHub App

​GitLab Token

​SSH Key

​Helm with Basic Auth

​Google Cloud Source Repositories

​Connection State

​Repository Credentials

​Create Credential Template

​Security Best Practices

​Next Steps

Application API

Project API

Overview

Repository Resource

Repository Spec

Authentication Fields

GitHub App Authentication

Cloud Provider Authentication

Additional Options

Example Repository

API Operations

List Repositories

Get Repository

Create Repository

Update Repository

Delete Repository

Repository Operations

Validate Access

List Repository Apps

Get App Details

List Helm Charts

List Refs

List OCI Tags

Write Repositories

List Write Repositories

Get Write Repository

Create Write Repository

Update Write Repository

Delete Write Repository

Authentication Examples

GitHub Personal Access Token

GitHub App

GitLab Token

SSH Key

Helm with Basic Auth

Google Cloud Source Repositories

Connection State

Repository Credentials

Create Credential Template

Security Best Practices

Next Steps