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

repo

string

required

Repository URL

# Git repositories
repo: https://github.com/myorg/myrepo
repo: [email protected]:myorg/myrepo.git

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

# OCI registries
repo: oci://ghcr.io/myorg/charts

type

string

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

name

string

Repository name (required for Helm repos)

project

string

Project that owns this repository

Authentication Fields

username

string

Username for HTTPS authentication

password

string

Password or personal access token

sshPrivateKey

string

SSH private key (PEM format) for Git repos

bearerToken

string

Bearer token for Git authentication (BitBucket Data Center)

tlsClientCertData

string

TLS client certificate (PEM format)

tlsClientCertKey

string

TLS client certificate key (PEM format)

GitHub App Authentication

githubAppPrivateKey

string

GitHub App private key (PEM format)

githubAppID

int64

GitHub App ID

githubAppInstallationID

int64

GitHub App installation ID

githubAppEnterpriseBaseUrl

string

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

Cloud Provider Authentication

gcpServiceAccountKey

string

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

useAzureWorkloadIdentity

boolean

Use Azure Workload Identity for authentication

Additional Options

insecure

boolean

Skip TLS certificate or SSH host key validation

enableLfs

boolean

Enable Git LFS support (Git repos only)

enableOCI

boolean

Enable OCI support for Helm repos

proxy

string

HTTP/HTTPS proxy URL

forceHttpBasicAuth

boolean

Force HTTP basic authentication

insecureOCIForceHttp

boolean

Use HTTP instead of HTTPS for OCI repos

depth

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

repo

string

Filter by repository URL

forceRefresh

boolean

Force refresh connection state

appProject

string

Filter by project

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

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}

repo

string

required

Repository URL (URL-encoded)

forceRefresh

boolean

Force refresh connection state

appProject

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"

Create Repository

POST /api/v1/repositories

repo

Repository

required

Complete Repository configuration

upsert

boolean

Update if already exists (default: false)

credsOnly

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

Update Repository

Update repository configuration.

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

repo.repo

string

required

Repository URL (URL-encoded)

repo

Repository

required

Updated repository configuration

Delete Repository

Remove a repository.

DELETE /api/v1/repositories/{repo}

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"

Repository Operations

Validate Access

Test repository connectivity and credentials.

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

repo

string

required

Repository URL (URL-encoded)

All repository fields

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

repo

string

required

Repository URL (URL-encoded)

revision

string

Git revision (default: HEAD)

appName

string

Application name context

appProject

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

source

ApplicationSource

required

Application source configuration

appName

string

Application name

appProject

string

Project name

List Helm Charts

List available Helm charts in a Helm repository.

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

repo

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

repo

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": "[email protected]: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

Resources

gRPC Services

​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

Build docs developers (and LLMs) love

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