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

# Namespaces

> Organize pipeline projects and variables with namespaces

Namespaces provide logical grouping for pipeline projects and shared variables. Use namespaces to organize projects by team, environment, or application, and to share configuration across multiple pipelines.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Namespace" icon="folder-open">
    A logical container for organizing related projects and sharing variables across pipelines.
  </Card>

  <Card title="Variables" icon="variable">
    Key-value pairs defined at the namespace level. Available to all pipelines within the namespace.
  </Card>

  <Card title="Cloning" icon="copy">
    Create a copy of a namespace including all its variables for quick setup.
  </Card>

  <Card title="Scope" icon="sitemap">
    Variables can be scoped to namespace (group) level, accessible by all projects in that namespace.
  </Card>
</CardGroup>

## Required Permissions

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

## Namespace Naming Rules

| Rule                   | Requirement                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| **Length**             | 1-100 characters                                                 |
| **Characters**         | Letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (\_) |
| **Spaces**             | Not allowed                                                      |
| **Special Characters** | Not allowed (except hyphen and underscore)                       |

## How to Create a Namespace

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

  <Step title="Enter Name">
    Provide a unique name following the naming rules (e.g., `production`, `team-backend`, `app-payments`).
  </Step>

  <Step title="Add Description (Optional)">
    Enter a description to help identify the namespace purpose (max 500 characters).
  </Step>

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

<Tip>
  Use consistent naming conventions like `{environment}`, `{team}-{app}`, or `{project}-{env}` for easier organization.
</Tip>

## How to Edit a Namespace

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

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

  <Step title="Modify Settings">
    Update the name or description as needed.
  </Step>

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

## How to Clone a Namespace

Cloning creates a copy of a namespace including all its variables.

<Steps>
  <Step title="Find the Namespace">
    Locate the namespace you want to clone.
  </Step>

  <Step title="Click Clone">
    Click the clone (copy) icon on the namespace row.
  </Step>

  <Step title="Review">
    The new namespace is created with the name "{original} (Clone)".
  </Step>

  <Step title="Rename (Recommended)">
    Edit the cloned namespace to give it a meaningful name.
  </Step>
</Steps>

<Info>
  Cloning copies all namespace variables. This is useful for setting up new environments with similar configuration.
</Info>

## How to Delete a Namespace

<Steps>
  <Step title="Find the Namespace">
    Locate the namespace you want to delete.
  </Step>

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

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

<Warning>
  Deleting a namespace removes all associated variables. Projects using this namespace's variables may fail.
</Warning>

## How to Manage Namespace Variables

Click on a namespace row to navigate to its variables page.

### Adding Variables

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

  <Step title="Enter Key">
    Provide a unique variable key (e.g., `DATABASE_URL`, `API_KEY`).
  </Step>

  <Step title="Enter Value">
    Enter the variable value. Toggle **JSON** switch for structured data.
  </Step>

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

### Editing Variables

<Steps>
  <Step title="Locate Variable">
    Find the variable in the list or use search.
  </Step>

  <Step title="Show Value">
    Click the eye icon to reveal hidden values.
  </Step>

  <Step title="Modify">
    Update the key or value directly in the input fields.
  </Step>

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

### JSON Editing Mode

For bulk editing or importing variables:

<Steps>
  <Step title="Toggle JSON Mode">
    Click the braces icon to switch to JSON editing mode.
  </Step>

  <Step title="Edit JSON">
    Modify variables as a JSON object in the Monaco editor.
  </Step>

  <Step title="Save">
    Click **Save JSON** to apply all changes.
  </Step>
</Steps>

<Tip>
  Use JSON mode to paste variables from another namespace or external source.
</Tip>

### Deleting Variables

<Steps>
  <Step title="Find Variable">
    Locate the variable to delete.
  </Step>

  <Step title="Click Delete">
    Click the trash icon on the variable row.
  </Step>

  <Step title="Confirm">
    The variable is immediately removed.
  </Step>
</Steps>

## Variable Types

| Type     | Description                     | Use Case                               |
| -------- | ------------------------------- | -------------------------------------- |
| **Text** | Simple string value             | API keys, URLs, simple configuration   |
| **JSON** | Structured JSON object or array | Complex configuration, nested settings |

<Info>
  Toggle the JSON switch on a variable to enable JSON validation and syntax highlighting in the editor.
</Info>

## Common Use Cases

### Environment-Based Namespaces

```
development
staging
production
```

Each environment has its own namespace with environment-specific variables.

### Team-Based Namespaces

```
team-backend
team-frontend
team-platform
```

Variables shared across all projects owned by a team.

### Application-Based Namespaces

```
payments-service
user-service
notification-service
```

Variables specific to each microservice or application.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot create namespace" icon="circle-question">
    * You need write permission
    * Name may already exist
    * Name contains invalid characters
    * Name exceeds 100 characters
  </Accordion>

  <Accordion title="Variables not appearing in pipeline" icon="circle-question">
    * Verify the project is assigned to the correct namespace
    * Check that variables were saved
    * Ensure variable keys don't have typos
    * Variables are case-sensitive
  </Accordion>

  <Accordion title="JSON validation error" icon="circle-question">
    * Check for missing commas between properties
    * Ensure all strings are wrapped in double quotes
    * Verify brackets and braces match
    * Use the JSON mode editor for syntax highlighting
  </Accordion>

  <Accordion title="Cannot delete namespace" icon="circle-question">
    * You need delete permission
    * Check if projects are still using this namespace
    * Try refreshing the page
  </Accordion>

  <Accordion title="Clone failed" icon="circle-question">
    * You need write permission
    * The source namespace may have been deleted
    * Try refreshing and cloning again
  </Accordion>

  <Accordion title="Variables not saving" icon="circle-question">
    * Click Save Changes after editing
    * Check for validation errors in JSON mode
    * Ensure you have write permission
    * Try refreshing and editing again
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can a project belong to multiple namespaces?">
    No. Each project belongs to one namespace. Use project-level variables for project-specific configuration and namespace variables for shared configuration.
  </Accordion>

  <Accordion title="Are namespace variables available in all stages?">
    Yes. Namespace variables are available in all pipeline stages (build, test, deploy) for projects within that namespace.
  </Accordion>

  <Accordion title="How do I override a namespace variable in a project?">
    Define a variable with the same key at the project level. Project-level variables take precedence over namespace-level variables.
  </Accordion>

  <Accordion title="Can I use namespace variables in other namespaces?">
    No. Namespace variables are scoped to that namespace only. Use clone to copy variables to another namespace, then modify as needed.
  </Accordion>

  <Accordion title="Are variables encrypted at rest?">
    Yes. All variables are encrypted in the database. Values are masked in the UI by default for security.
  </Accordion>

  <Accordion title="What happens to variables when I clone a namespace?">
    All variables are copied to the new namespace with identical keys and values. Changes to one namespace don't affect the other.
  </Accordion>

  <Accordion title="Can I import/export namespace variables?">
    Use JSON mode to copy variables as JSON. Paste the JSON into another namespace's JSON editor to import.
  </Accordion>

  <Accordion title="What's the variable key naming convention?">
    Use UPPER\_SNAKE\_CASE for environment variables (e.g., `DATABASE_URL`, `API_KEY`). For JSON configuration, use camelCase or whatever your application expects.
  </Accordion>
</AccordionGroup>

## Best Practices

### Organization

* Use consistent naming conventions across namespaces
* Group related projects in the same namespace
* Create separate namespaces for different environments
* Document namespace purpose in the description field

### Variables

* Use descriptive variable keys
* Don't store secrets that should be in a secrets manager
* Keep sensitive values hidden by default
* Use JSON type for complex configuration
* Review variables before cloning namespaces

### Security

* Limit namespace write access to authorized users
* Regularly audit namespace variables
* Use environment-specific values (never share production secrets with development)
* Mask sensitive values when sharing screens

### Maintenance

* Remove unused namespaces to reduce clutter
* Update descriptions when namespace purpose changes
* Clone instead of recreating to save time
* Use search to quickly find namespaces