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.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.
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
| 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
Assign Project (Optional)
Select a project to restrict repository access, or leave empty for global access.
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
Update Credentials (Optional)
Enter a new access token only if rotating credentials. Leave empty to keep the existing token.
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
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 |
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 contentread_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 |
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.Troubleshooting
Connection status shows Failed
Connection status shows Failed
- 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
Authentication failed
Authentication failed
- 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
Cannot access private repository
Cannot access private repository
- 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
TLS certificate error
TLS certificate error
- 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
Helm chart not found
Helm chart not found
- 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
OCI registry authentication failed
OCI registry authentication failed
- 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
Can I use SSH keys for authentication?
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.
How do I rotate repository credentials?
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.
Can multiple repositories use the same credentials?
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.
What happens if credentials expire?
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.
Can I use deploy keys instead of personal tokens?
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.
Why is my repository URL not editable?
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.
How do I access repositories from multiple Git providers?
How do I access repositories from multiple Git providers?
Create separate repository entries for each provider. Each entry can have different credentials and settings.
Can I use OAuth tokens instead of PATs?
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.
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