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

> Create and manage CI/CD pipeline projects with automated triggers and deployment environments

Pipeline Projects connect your Git repositories to CI/CD pipelines. Configure automated triggers, deployment environments, and run pipelines manually or automatically via webhooks.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Project" icon="folder-git">
    A connection between a Git repository and pipeline configuration with deployment settings.
  </Card>

  <Card title="Environment" icon="globe">
    A deployment target (dev, staging, prod) with ArgoCD clusters and namespaces.
  </Card>

  <Card title="Webhook" icon="webhook">
    Automatic pipeline triggering on Git events (push, tag, merge request).
  </Card>

  <Card title="Pipeline" icon="play">
    A CI/CD execution instance with stages, logs, and deployment artifacts.
  </Card>
</CardGroup>

## Required Permissions

### Project Permissions

| Action             | Permission                          |
| ------------------ | ----------------------------------- |
| View projects      | `iam:project:cicd:pipeline:read`    |
| Create projects    | `iam:project:cicd:pipeline:write`   |
| Edit projects      | `iam:project:cicd:pipeline:write`   |
| Delete projects    | `iam:project:cicd:pipeline:delete`  |
| Run pipelines      | `iam:project:cicd:pipeline:execute` |
| View pipeline logs | `iam:project:cicd:pipeline:logs`    |

### Webhook Permissions

| Action              | Permission                        |
| ------------------- | --------------------------------- |
| View webhook        | `iam:project:cicd:webhook:read`   |
| Create/Edit webhook | `iam:project:cicd:webhook:write`  |
| Delete webhook      | `iam:project:cicd:webhook:delete` |

## How to Create a Project

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

  <Step title="Select Template">
    Choose a pipeline template. Templates define deployment type and required configurations.
  </Step>

  <Step title="Enter Project Name">
    Provide a unique name for the project.
  </Step>

  <Step title="Select Git Provider">
    Choose GitHub, GitLab, or Bitbucket from configured providers.
  </Step>

  <Step title="Configure Repository">
    Choose **Create new repository** or **Use existing repository**.

    * For new repos: Select organization/group and enter repository name
    * For existing repos: Select from available repositories
  </Step>

  <Step title="Set Visibility">
    Choose **Public** or **Private** for repository visibility (new repos only).
  </Step>

  <Step title="Select Namespace (Optional)">
    If the template requires a namespace, select one to inherit shared variables.
  </Step>

  <Step title="Configure Environments">
    If the template requires environments, add deployment targets:

    * Environment name (e.g., dev, staging, production)
    * ArgoCD instance
    * Cluster name
    * Namespace
  </Step>

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

<Info>
  The template determines which fields are required. Some templates don't require namespaces or environments.
</Info>

## How to Run a Pipeline

<Steps>
  <Step title="Open Project">
    Click on a project to open its detail page.
  </Step>

  <Step title="Click Run Pipeline">
    Click the **Run Pipeline** button.
  </Step>

  <Step title="Select Environment">
    Choose the target deployment environment.
  </Step>

  <Step title="Select Strategy">
    Choose an image tag strategy:

    * **Trunk Based**: Branch + commit SHA
    * **Tag Based**: Git tag release
    * **Feature**: Branch name only
    * **Manual**: Custom tag
  </Step>

  <Step title="Select Branch">
    Choose the source branch from the repository.
  </Step>

  <Step title="Select Commit">
    For Trunk Based and Feature strategies, select a specific commit.
  </Step>

  <Step title="Select Tag (Optional)">
    For Tag Based strategy, enter or select a Git tag.
  </Step>

  <Step title="Run">
    Click **Run Pipeline** to start execution.
  </Step>
</Steps>

## Image Tag Strategies

| Strategy        | Image Tag Format   | Use Case                                     |
| --------------- | ------------------ | -------------------------------------------- |
| **Trunk Based** | `branch-commitsha` | Continuous deployment from main branch       |
| **Tag Based**   | `v1.0.0`           | Release deployments with semantic versioning |
| **Feature**     | `feature-name`     | Development/testing feature branches         |
| **Manual**      | Custom value       | Special deployments with custom naming       |

<Tip>
  Use Trunk Based for continuous deployment workflows and Tag Based for release-based deployments.
</Tip>

## How to Monitor Pipelines

### Pipeline Statuses

| Status                    | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| **Running**               | Pipeline is currently executing                       |
| **Pending**               | Pipeline is queued for execution                      |
| **Success**               | All stages completed successfully                     |
| **Success with Warnings** | Completed with non-critical issues                    |
| **Failed**                | One or more stages failed                             |
| **Cancelled**             | Pipeline was manually cancelled                       |
| **Skipped**               | Pipeline was skipped (duplicate or condition not met) |

### Pipeline Actions

| Action            | Description                      | Availability              |
| ----------------- | -------------------------------- | ------------------------- |
| **Cancel**        | Stop a running pipeline          | Running/Pending pipelines |
| **Retry**         | Re-run a failed pipeline         | Failed pipelines          |
| **Re-run**        | Run the same configuration again | Completed pipelines       |
| **Download Logs** | Download pipeline execution logs | Completed pipelines       |

## How to Manage Environments

### Adding an Environment

<Steps>
  <Step title="Open Project Settings">
    Navigate to the **Environments** tab in project detail.
  </Step>

  <Step title="Click Add Environment">
    Click the **Add Environment** button.
  </Step>

  <Step title="Enter Environment Name">
    Provide a name (e.g., development, staging, production).
  </Step>

  <Step title="Add Deployment Target">
    Configure target settings:

    * **ArgoCD Instance**: Select the ArgoCD server
    * **Cluster Name**: Select the Kubernetes cluster
    * **Namespace**: Select the target namespace
    * **Active**: Enable/disable deployments to this target
  </Step>

  <Step title="Add More Targets (Optional)">
    Click **Add Target** to deploy to multiple clusters/namespaces.
  </Step>

  <Step title="Save">
    Click **Add Environment** to save.
  </Step>
</Steps>

### Environment Requirements

| Field            | Required | Description                     |
| ---------------- | -------- | ------------------------------- |
| Environment Name | Yes      | Unique name within the project  |
| ArgoCD Instance  | Yes      | Target ArgoCD server            |
| Cluster Name     | Yes      | Kubernetes cluster              |
| Namespace        | Yes      | Target namespace for deployment |

<Warning>
  At least one active target is required per environment. Environments without active targets cannot be used for deployments.
</Warning>

## How to Configure Webhooks

Webhooks enable automatic pipeline triggering from Git events.

### Creating a Webhook

<Steps>
  <Step title="Open Project Settings">
    Navigate to the **Webhook** tab in project detail.
  </Step>

  <Step title="Click Create Webhook">
    Click **Create Webhook** to generate a new webhook endpoint.
  </Step>

  <Step title="Copy Webhook URL">
    Copy the webhook URL to configure in your Git provider.
  </Step>

  <Step title="Save Webhook Secret">
    Copy and securely store the webhook secret. It is shown only once.
  </Step>

  <Step title="Configure Git Provider">
    Add the webhook URL and secret to your Git repository settings.
  </Step>
</Steps>

<Warning>
  The webhook secret is displayed only once after creation. Store it securely before closing the dialog.
</Warning>

### Webhook Event Types

| Event             | Description         | Trigger                                         |
| ----------------- | ------------------- | ----------------------------------------------- |
| **Push**          | Branch push events  | Pipeline runs on commits to configured branches |
| **Tag**           | Tag creation events | Pipeline runs when tags are pushed              |
| **Merge Request** | PR/MR events        | Pipeline runs on pull request actions           |

### Managing Webhook Settings

| Action                 | Description                             |
| ---------------------- | --------------------------------------- |
| **Enable/Disable**     | Toggle webhook active status            |
| **Regenerate Secret**  | Create new secret (invalidates old one) |
| **Update Event Types** | Change which events trigger pipelines   |
| **Delete**             | Remove webhook configuration            |

<Info>
  Regenerating the secret invalidates the previous secret. Update your Git provider settings after regenerating.
</Info>

## How to Manage Project Variables

<Steps>
  <Step title="Open Variables Tab">
    Navigate to the **Variables** tab in project detail.
  </Step>

  <Step title="Add Variable">
    Click **Add Variable** and enter key-value pairs.
  </Step>

  <Step title="Set Variable Type">
    Toggle **JSON** for structured data, or leave off for plain text.
  </Step>

  <Step title="Save">
    Click **Save Changes** to persist variables.
  </Step>
</Steps>

<Tip>
  Project variables override namespace variables with the same key. Use project variables for project-specific configuration.
</Tip>

## How to Edit a Project

<Steps>
  <Step title="Open Project">
    Navigate to the project detail page.
  </Step>

  <Step title="Go to Settings">
    Click the **Settings** tab.
  </Step>

  <Step title="Click Edit">
    Click **Edit Project** to open the edit form.
  </Step>

  <Step title="Modify Settings">
    Update project name, namespace, or other settings.
  </Step>

  <Step title="Save">
    Click **Save Changes** to apply updates.
  </Step>
</Steps>

## How to Delete a Project

<Steps>
  <Step title="Open Project Settings">
    Navigate to the **Settings** tab in project detail.
  </Step>

  <Step title="Click Delete">
    Click **Delete Project** in the danger zone.
  </Step>

  <Step title="Choose Repository Action">
    Select whether to also delete the Git repository:

    * **Keep repository**: Only delete project configuration
    * **Delete repository**: Also delete the Git repository
  </Step>

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

<Warning>
  Deleting a project removes all pipeline history, environments, and configurations. If you choose to delete the repository, all code will be permanently lost.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Pipeline not triggered by webhook" icon="circle-question">
    * Verify webhook is enabled (active status)
    * Check event type is configured (push, tag, merge\_request)
    * Confirm webhook URL is correctly configured in Git provider
    * Verify webhook secret matches
    * Check branch filters match the pushed branch
    * Review webhook delivery logs in Git provider
  </Accordion>

  <Accordion title="Pipeline fails immediately" icon="circle-question">
    * Verify Git provider credentials are valid
    * Check repository access permissions
    * Ensure pipeline configuration files exist in repository
    * Verify template configuration is complete
  </Accordion>

  <Accordion title="Cannot run pipeline" icon="circle-question">
    * Verify you have execute permission
    * Check that at least one environment is configured
    * Ensure Git provider connection is active
    * Verify branch and commit selection
  </Accordion>

  <Accordion title="Environment deployment fails" icon="circle-question">
    * Verify ArgoCD instance is accessible
    * Check cluster and namespace exist
    * Ensure ArgoCD has permissions to deploy
    * Review ArgoCD application logs
  </Accordion>

  <Accordion title="Cannot create project" icon="circle-question">
    * Verify you have write permission
    * Check Git provider is configured and active
    * Ensure repository name is valid and unique
    * Verify required template fields are filled
  </Accordion>

  <Accordion title="Webhook secret lost" icon="circle-question">
    * Click **Regenerate** to create a new secret
    * Update the secret in your Git provider settings
    * Old webhook deliveries will fail signature verification
  </Accordion>

  <Accordion title="Variables not available in pipeline" icon="circle-question">
    * Verify variables are saved
    * Check variable key spelling (case-sensitive)
    * Namespace variables require project to be in that namespace
    * Project variables override namespace variables
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use multiple Git providers for one project?">
    No. Each project connects to one Git provider and one repository. Create separate projects for different repositories.
  </Accordion>

  <Accordion title="How do I migrate a project to a different repository?">
    Projects cannot be migrated to different repositories. Create a new project with the new repository and optionally delete the old project.
  </Accordion>

  <Accordion title="Can I have multiple environments with the same name?">
    No. Environment names must be unique within a project. Use descriptive names like "production-us", "production-eu" for regional deployments.
  </Accordion>

  <Accordion title="What happens when I cancel a running pipeline?">
    The pipeline execution stops at the current step. Partially deployed resources may remain. Review deployment state after cancellation.
  </Accordion>

  <Accordion title="How do I roll back a deployment?">
    Run a new pipeline with the previous commit or tag. Alternatively, use ArgoCD directly to sync to a previous revision.
  </Accordion>

  <Accordion title="Can webhooks trigger specific environments?">
    Webhook trigger configuration in the template determines which branches trigger which environments. Configure branch-to-environment mapping in the template trigger configuration.
  </Accordion>

  <Accordion title="Are pipeline logs retained permanently?">
    Pipeline logs are retained according to your organization's retention policy. Download logs for long-term storage if needed.
  </Accordion>

  <Accordion title="Can I run the same pipeline configuration multiple times?">
    Yes. Use the **Re-run** action on any completed pipeline to run the same configuration again.
  </Accordion>

  <Accordion title="What's the difference between Retry and Re-run?">
    **Retry** attempts to continue from the failed stage. **Re-run** starts a fresh pipeline execution from the beginning.
  </Accordion>

  <Accordion title="How do I deploy to multiple clusters simultaneously?">
    Add multiple targets to an environment. Each target can specify a different ArgoCD instance, cluster, or namespace.
  </Accordion>
</AccordionGroup>

## Best Practices

### Project Organization

* Use consistent naming conventions (team-service-env)
* Group related projects in the same namespace
* Keep one project per microservice/application
* Document project purpose in description

### Pipeline Execution

* Use Tag Based strategy for production releases
* Use Trunk Based for continuous deployment
* Always verify environment selection before running
* Monitor pipeline progress for failures

### Environment Configuration

* Create separate environments for dev/staging/production
* Use multiple targets for multi-cluster deployments
* Disable targets during maintenance
* Keep production targets with restricted access

### Webhook Configuration

* Always configure webhook secrets for security
* Enable only required event types
* Monitor webhook delivery statistics
* Update secrets periodically

### Security

* Use private repositories for sensitive code
* Limit execute permission to authorized users
* Store secrets in variables, not in code
* Review pipeline logs for sensitive data exposure
* Rotate webhook secrets regularly

### Variables

* Use UPPER\_SNAKE\_CASE for environment variables
* Document variable purposes
* Use namespace variables for shared configuration
* Override with project variables for specific needs