Skip to main content
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

Repository

A source location containing application manifests, Helm charts, or container images.

Repository Type

The format of the repository: Git (source code), Helm (charts), or OCI (images).

Credentials

Username and access token for authenticating with private repositories.

Connection Status

Health status indicating whether ArgoCD can connect to the repository.

​
Required Permissions

​
Repository Types

​
Connection Status

​
How to Add a Repository

1

Select ArgoCD Instance

Choose the ArgoCD instance from the dropdown in the toolbar.
2

Click Add Repository

Click the Add Repository button in the header.
3

Enter Repository Name

Provide a friendly display name to identify the repository.
4

Enter Repository URL

Enter the full repository URL.
5

Select Repository Type

Choose Git, Helm, or OCI based on the repository contents.
6

Enter Credentials (Optional)

For private repositories, enter username and access token.
7

Assign Project (Optional)

Select a project to restrict repository access, or leave empty for global access.
8

Configure TLS (Optional)

Enable insecure mode to skip TLS verification if needed.
9

Add

Click Add Repository to save.

​
Required Fields

​
URL Formats

​
Git Repositories

​
Helm Repositories

​
OCI Repositories

​
How to Edit a Repository

1

Find the Repository

Locate the repository in the list using search.
2

Click Edit

Click the edit (pencil) icon on the repository row.
3

Modify Settings

Update name, credentials, project assignment, or TLS settings.
4

Update Credentials (Optional)

Enter a new access token only if rotating credentials. Leave empty to keep the existing token.
5

Save

Click Update Repository to apply changes.
Repository URL cannot be changed after creation. To use a different URL, delete the repository and create a new one.

​
How to Delete a Repository

1

Find the Repository

Locate the repository to delete.
2

Click Delete

Click the delete (trash) icon on the repository row.
3

Confirm

Confirm the deletion. This action cannot be undone.
Deleting a repository removes its credentials from ArgoCD. Applications using this repository will fail to sync until credentials are restored.

​
Authentication

​
Public Repositories

No credentials required. Leave username and access token empty.

​
Private Repositories

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

​
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.
Use project assignment to implement least-privilege access. Production repositories should typically be restricted to production projects only.

​
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.
Insecure mode should only be used for development or with self-signed certificates. Always use proper TLS in production.

​
Troubleshooting

  • 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
  • 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
  • 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
  • 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
  • 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
  • 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

​
FAQ

SSH key authentication is supported but must be configured through the ArgoCD CLI or API. The UI currently supports username/token authentication only.
Edit the repository and enter the new access token. Leave the field empty to keep the existing credentials. Old credentials are replaced immediately.
No. Each repository stores its own credentials. However, you can use the same access token across multiple repository entries.
Applications using the repository will fail to sync with authentication errors. Update the repository with new credentials to restore access.
Deploy keys are supported through SSH authentication, which requires CLI configuration. For UI-based setup, use Personal Access Tokens.
Repository URLs are immutable after creation because applications reference them. To change the URL, delete the repository and create a new one.
Create separate repository entries for each provider. Each entry can have different credentials and settings.
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.

​
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