ArgoCD Projects provide logical grouping of applications and define access control policies. Projects control which Git repositories can be deployed, which clusters and namespaces can be targeted, and which Kubernetes resources can be created.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
Project
A logical grouping that defines allowed sources, destinations, and resource permissions.
Source Repository
Git repositories from which applications in this project can deploy manifests.
Destination
Kubernetes clusters and namespaces where applications can be deployed.
Resource Rules
Allow and deny lists controlling which Kubernetes resources can be created.
Required Permissions
| Action | Permission |
|---|---|
| View projects | iam:project:cicd:argocd:read |
| Create projects | iam:project:cicd:argocd:write |
| Edit projects | iam:project:cicd:argocd:write |
| Delete projects | iam:project:cicd:argocd:delete |
Project Name Rules
| Rule | Requirement |
|---|---|
| Characters | Lowercase letters (a-z), numbers (0-9), hyphens (-) |
| Start/End | Must start and end with alphanumeric character |
| Uppercase | Not allowed |
| Spaces | Not allowed |
| Special Characters | Not allowed (except hyphen) |
my-project, app1, team-frontend-prod
Invalid examples: My-Project, my_project, -project, project-
How to Create a Project
Project name cannot be changed after creation. Choose a meaningful name that reflects the project purpose.
How to Edit a Project
How to Delete a Project
Source Repositories
Source repositories define which Git repositories can be used by applications in this project.| Value | Meaning |
|---|---|
* | Allow all repositories |
https://github.com/org/* | Allow all repos in organization |
https://github.com/org/repo | Allow specific repository |
Adding Source Repositories
Source Namespaces
Source namespaces restrict which Kubernetes namespaces can contain application manifests.| Value | Meaning |
|---|---|
* | Allow all namespaces |
namespace-name | Allow specific namespace |
Destinations
Destinations define where applications can deploy resources.| Field | Description | Wildcard |
|---|---|---|
| Server | Kubernetes cluster URL or name | * for all clusters |
| Namespace | Target namespace | * for all namespaces |
| Name | Optional cluster name | Optional |
Adding Destinations
Resource Rules
Resource rules control which Kubernetes resource types can be created by applications in this project.Cluster Resource Rules
Cluster resources are cluster-scoped (not namespaced), such as:ClusterRoleClusterRoleBindingNamespacePersistentVolumeCustomResourceDefinition
Namespace Resource Rules
Namespace resources are namespace-scoped, such as:DeploymentServiceConfigMapSecretPod
Rule Configuration
| Field | Description |
|---|---|
| Kind | Kubernetes resource kind (e.g., Deployment, Service) or * for all |
| Group | API group (e.g., apps, networking.k8s.io) or * for all |
Allow vs Deny Lists
| List Type | Purpose |
|---|---|
| Allow List | Resources explicitly permitted (whitelist) |
| Deny List | Resources explicitly forbidden (blacklist) |
Deny list takes precedence over allow list. If a resource matches both lists, it is denied.
Default Configuration
New projects are created with permissive defaults:| Setting | Default Value |
|---|---|
| Namespace | argocd |
| Source Repos | * (all) |
| Source Namespaces | * (all) |
| Destinations | Server: *, Namespace: *, Name: * |
| Cluster Resource Allow | Kind: *, Group: * |
| Cluster Resource Deny | Empty |
| Namespace Resource Allow | Kind: *, Group: * |
| Namespace Resource Deny | Empty |
Troubleshooting
Cannot create project
Cannot create project
- Verify you have write permission
- Check project name follows naming rules (lowercase, alphanumeric, hyphens)
- Ensure project name doesn’t already exist
- Verify ArgoCD instance is selected and accessible
Application sync fails with project error
Application sync fails with project error
- Verify source repository is in project’s allowed sources
- Check destination cluster and namespace are allowed
- Ensure resource types are in allow list and not in deny list
- Verify application is assigned to correct project
Cannot edit project name
Cannot edit project name
- Project names cannot be changed after creation
- Create a new project with the desired name
- Reassign applications to the new project
- Delete the old project
Cannot delete project
Cannot delete project
- Verify you have delete permission
- Check if applications are still assigned to this project
- Applications may need to be deleted or reassigned first
Resource creation denied
Resource creation denied
- Check if resource kind is in the deny list
- Verify resource kind and group are in the allow list
- Review both cluster and namespace resource rules
- Deny list takes precedence over allow list
Project not appearing in list
Project not appearing in list
- Verify correct ArgoCD instance is selected
- Check you have read permission
- Try refreshing the page
- Ensure project was created successfully
FAQ
What is the 'default' project?
What is the 'default' project?
ArgoCD includes a built-in
default project with no restrictions. It’s recommended for testing only. Create dedicated projects with appropriate restrictions for production use.Can I move an application to a different project?
Can I move an application to a different project?
Yes. Edit the application and change its project assignment. The application must comply with the new project’s source, destination, and resource rules.
How do I restrict deployments to specific namespaces?
How do I restrict deployments to specific namespaces?
Edit the project’s destinations. Remove
* and add specific server/namespace combinations. Applications can only deploy to listed destinations.What happens if I delete a project with applications?
What happens if I delete a project with applications?
Applications become orphaned and may fail to sync. Delete or reassign applications before deleting the project.
Can I use regex patterns for source repos?
Can I use regex patterns for source repos?
Yes. ArgoCD supports glob patterns. Use
https://github.com/org/* to allow all repositories in an organization.How do resource allow/deny lists interact?
How do resource allow/deny lists interact?
Deny list always wins. If a resource matches both allow and deny lists, it is denied. Design deny lists carefully to avoid blocking legitimate resources.
Can multiple projects share the same destination?
Can multiple projects share the same destination?
What's the difference between cluster and namespace resources?
What's the difference between cluster and namespace resources?
Cluster resources are cluster-scoped (e.g., ClusterRole, Namespace). Namespace resources are scoped to a namespace (e.g., Deployment, Service). Different rules apply to each type.
Best Practices
Project Design
- Create separate projects for different teams or environments
- Use descriptive names (e.g.,
team-frontend-prod,platform-staging) - Document project purpose in the description field
- Start restrictive and add permissions as needed
Source Control
- Avoid
*for source repos in production - Use organization-level patterns when possible
- Restrict to specific repositories for sensitive environments
- Audit source repository access regularly
Destination Control
- Define specific cluster/namespace pairs for production
- Use
*sparingly and only in development - Separate staging and production destinations
- Consider namespace isolation per team
Resource Rules
- Default to deny unknown resources in production
- Allow only required resource types
- Use deny lists to block dangerous resources (e.g.,
ClusterRolemodifications) - Review resource rules when onboarding new applications
Security
- Restrict cluster resource creation for non-admin projects
- Deny
NamespaceandClusterRolecreation where not needed - Audit project configurations periodically
- Use separate projects for different security boundaries