> ## 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.

# Projects

> Manage ArgoCD projects for organizing applications and access control

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

<CardGroup cols={2}>
  <Card title="Project" icon="folder-git">
    A logical grouping that defines allowed sources, destinations, and resource permissions.
  </Card>

  <Card title="Source Repository" icon="git-alt">
    Git repositories from which applications in this project can deploy manifests.
  </Card>

  <Card title="Destination" icon="server">
    Kubernetes clusters and namespaces where applications can be deployed.
  </Card>

  <Card title="Resource Rules" icon="shield">
    Allow and deny lists controlling which Kubernetes resources can be created.
  </Card>
</CardGroup>

## 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)                         |

**Valid examples**: `my-project`, `app1`, `team-frontend-prod`

**Invalid examples**: `My-Project`, `my_project`, `-project`, `project-`

## How to Create a Project

<Steps>
  <Step title="Select ArgoCD Instance">
    Choose the ArgoCD instance from the dropdown in the toolbar.
  </Step>

  <Step title="Click Create Project">
    Click the **Create Project** button in the header.
  </Step>

  <Step title="Enter Project Name">
    Provide a unique name following the naming rules.
  </Step>

  <Step title="Set Namespace">
    Enter the Kubernetes namespace (default: `argocd`).
  </Step>

  <Step title="Add Description (Optional)">
    Provide a description to identify the project purpose.
  </Step>

  <Step title="Configure Source Repositories">
    Add allowed Git repositories. Use `*` to allow all repositories.
  </Step>

  <Step title="Configure Source Namespaces">
    Add allowed source namespaces. Use `*` to allow all namespaces.
  </Step>

  <Step title="Configure Destinations">
    Add allowed deployment destinations (server, namespace, name).
  </Step>

  <Step title="Configure Resource Rules">
    Set allow and deny lists for cluster and namespace resources.
  </Step>

  <Step title="Create">
    Click **Create Project** to save.
  </Step>
</Steps>

<Info>
  Project name cannot be changed after creation. Choose a meaningful name that reflects the project purpose.
</Info>

## How to Edit a Project

<Steps>
  <Step title="Find the Project">
    Locate the project in the list using search.
  </Step>

  <Step title="Click Edit">
    Click the edit (pencil) icon on the project row.
  </Step>

  <Step title="Modify Settings">
    Update description, sources, destinations, or resource rules.
  </Step>

  <Step title="Save">
    Click **Update Project** to apply changes.
  </Step>
</Steps>

<Warning>
  Project name cannot be modified. To rename a project, delete it and create a new one with the desired name.
</Warning>

## How to Delete a Project

<Steps>
  <Step title="Find the Project">
    Locate the project to delete.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon on the project row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting a project does not delete its applications. Reassign or delete applications before deleting the project.
</Warning>

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

<Steps>
  <Step title="Click Add">
    Click the **Add** button in the Source Repositories section.
  </Step>

  <Step title="Enter Repository URL">
    Enter the full Git repository URL or `*` for all.
  </Step>

  <Step title="Repeat">
    Add more repositories as needed.
  </Step>
</Steps>

<Tip>
  Use `*` during development and restrict to specific repositories in production for security.
</Tip>

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

<Steps>
  <Step title="Click Add">
    Click the **Add** button in the Destinations section.
  </Step>

  <Step title="Enter Server">
    Enter cluster URL (e.g., `https://kubernetes.default.svc`) or `*` for all.
  </Step>

  <Step title="Enter Namespace">
    Enter target namespace or `*` for all namespaces.
  </Step>

  <Step title="Enter Name (Optional)">
    Optionally provide a cluster name for identification.
  </Step>
</Steps>

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

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

<Info>
  Deny list takes precedence over allow list. If a resource matches both lists, it is denied.
</Info>

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

<Warning>
  Default settings allow all access. Restrict sources, destinations, and resources for production projects.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot create project" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Application sync fails with project error" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot edit project name" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot delete project" icon="circle-question">
    * Verify you have delete permission
    * Check if applications are still assigned to this project
    * Applications may need to be deleted or reassigned first
  </Accordion>

  <Accordion title="Resource creation denied" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Project not appearing in list" icon="circle-question">
    * Verify correct ArgoCD instance is selected
    * Check you have read permission
    * Try refreshing the page
    * Ensure project was created successfully
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can multiple projects share the same destination?">
    Yes. Multiple projects can have overlapping destinations. Applications are isolated by their assigned project regardless of destination overlap.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

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