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

​
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

​
Project Name Rules

Valid examples: my-project, app1, team-frontend-prod Invalid examples: My-Project, my_project, -project, project-

​
How to Create a Project

1

Select ArgoCD Instance

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

Click Create Project

Click the Create Project button in the header.
3

Enter Project Name

Provide a unique name following the naming rules.
4

Set Namespace

Enter the Kubernetes namespace (default: argocd).
5

Add Description (Optional)

Provide a description to identify the project purpose.
6

Configure Source Repositories

Add allowed Git repositories. Use * to allow all repositories.
7

Configure Source Namespaces

Add allowed source namespaces. Use * to allow all namespaces.
8

Configure Destinations

Add allowed deployment destinations (server, namespace, name).
9

Configure Resource Rules

Set allow and deny lists for cluster and namespace resources.
10

Create

Click Create Project to save.
Project name cannot be changed after creation. Choose a meaningful name that reflects the project purpose.

​
How to Edit a Project

1

Find the Project

Locate the project in the list using search.
2

Click Edit

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

Modify Settings

Update description, sources, destinations, or resource rules.
4

Save

Click Update Project to apply changes.
Project name cannot be modified. To rename a project, delete it and create a new one with the desired name.

​
How to Delete a Project

1

Find the Project

Locate the project to delete.
2

Click Delete

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

Confirm

Confirm the deletion. This action cannot be undone.
Deleting a project does not delete its applications. Reassign or delete applications before deleting the project.

​
Source Repositories

Source repositories define which Git repositories can be used by applications in this project.

​
Adding Source Repositories

1

Click Add

Click the Add button in the Source Repositories section.
2

Enter Repository URL

Enter the full Git repository URL or * for all.
3

Repeat

Add more repositories as needed.
Use * during development and restrict to specific repositories in production for security.

​
Source Namespaces

Source namespaces restrict which Kubernetes namespaces can contain application manifests.

​
Destinations

Destinations define where applications can deploy resources.

​
Adding Destinations

1

Click Add

Click the Add button in the Destinations section.
2

Enter Server

Enter cluster URL (e.g., https://kubernetes.default.svc) or * for all.
3

Enter Namespace

Enter target namespace or * for all namespaces.
4

Enter Name (Optional)

Optionally provide a cluster name for identification.

​
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:
  • ClusterRole
  • ClusterRoleBinding
  • Namespace
  • PersistentVolume
  • CustomResourceDefinition

​
Namespace Resource Rules

Namespace resources are namespace-scoped, such as:
  • Deployment
  • Service
  • ConfigMap
  • Secret
  • Pod

​
Rule Configuration

​
Allow vs Deny Lists

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:
Default settings allow all access. Restrict sources, destinations, and resources for production projects.

​
Troubleshooting

  • 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
  • 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
  • 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
  • Verify you have delete permission
  • Check if applications are still assigned to this project
  • Applications may need to be deleted or reassigned first
  • 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
  • Verify correct ArgoCD instance is selected
  • Check you have read permission
  • Try refreshing the page
  • Ensure project was created successfully

​
FAQ

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.
Yes. Edit the application and change its project assignment. The application must comply with the new project’s source, destination, and resource rules.
Edit the project’s destinations. Remove * and add specific server/namespace combinations. Applications can only deploy to listed destinations.
Applications become orphaned and may fail to sync. Delete or reassign applications before deleting the project.
Yes. ArgoCD supports glob patterns. Use https://github.com/org/* to allow all repositories in an organization.
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.
Yes. Multiple projects can have overlapping destinations. Applications are isolated by their assigned project regardless of destination overlap.
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., ClusterRole modifications)
  • Review resource rules when onboarding new applications

​
Security

  • Restrict cluster resource creation for non-admin projects
  • Deny Namespace and ClusterRole creation where not needed
  • Audit project configurations periodically
  • Use separate projects for different security boundaries