> ## Documentation Index
> Fetch the complete documentation index at: https://docs.5x.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Project management

> Learn how to create, edit, and manage Cube projects with Git-based version control and branch management

**Focus:** Master project management in Metrics Store, including creating projects, managing repositories, working with branches, and configuring project settings.

Project management in Metrics Store enables you to organize your Cube definitions into separate projects, each with its own Git repository, branches, and deployment configuration. This allows you to manage different environments, features, and teams independently.

## Creating projects

### **Project creation workflow**

1. **Navigate to Metrics Store**
   * Go to `/metrics-store` page
   * Or click **"Metrics Store"** from navigation

2. **Access project creation**
   * If no projects exist: Click **"Create project"** button
   * If projects exist: Click project name in header → **"New project"**

3. **Fill project details**
   * Project name (required, unique, max 50 characters)
   * Repository type (Platform Managed or Imported)
   * Environment selection
   * Deployment options
   * Protected branches (optional)

4. **Add project**
   * Click **"Add Project"** button
   * Wait for repository cloning (if imported)
   * Project will be created and initialized

### **Repository types**

<Tabs>
  <Tab title="Platform Managed">
    Choose **Platform Managed** when you want 5X to handle repository management:

    **When to use:**

    * Creating new projects from scratch
    * Quick setup without Git configuration
    * Projects that don't require complex Git workflows
    * Learning and experimentation

    **What you get:**

    * 5X-managed Git repository
    * Automatic repository initialization
    * Ready-to-use development environment
    * No GitHub configuration required

    **Configuration:**

    * Project name (used to generate repository name)
    * Environment selection
    * Deployment options
  </Tab>

  <Tab title="Imported">
    Choose **Imported** when you have an existing GitHub repository:

    **When to use:**

    * Importing existing Cube.js projects
    * Maintaining version control with your team
    * Complex projects with custom dependencies
    * Projects shared across multiple environments

    **Requirements:**

    * Public or accessible private GitHub repository
    * Repository must contain valid Cube.js schema files
    * Deployment key must be added to GitHub repository

    **Configuration:**

    * GitHub repository URL
    * Subdirectory (optional, if Cube files are in a subfolder)
    * Deployment key (generated and displayed after creation)
    * Environment selection
    * Deployment options
  </Tab>
</Tabs>

### **Project settings**

**Project name**

* Unique identifier for your project
* Maximum 50 characters
* Used for display and repository naming
* Can be edited after creation

**Environment**

* Select the environment where your data warehouse is configured
* Different environments can have different data sources
* Environment selection affects deployment and API access

**Deployment options**

* **Always on** - Service runs continuously
* **On demand** - Service starts when needed
* **Scheduled** - Time-based or CRON-based scheduling

See [Deployment Options](/core-features/metric-store/deployment-options) for detailed configuration.

**Protected branches**

* Specify branches that should be protected from direct changes
* Protected branches typically require pull requests for changes
* Common choices: `main`, `master`, `production`

## Editing projects

### **Edit project details**

1. **Access project settings**
   * Click **"Settings"** button in header (gear icon)
   * Or click project name → **"Edit project"**

2. **Modify settings**
   * Edit project name
   * Change environment
   * Update deployment options
   * Modify protected branches

3. **Save changes**
   * Click **"Save"** to apply changes
   * Changes take effect immediately

### **Editable fields**

* **Project name** - Update display name
* **Environment** - Change deployment environment
* **Deployment options** - Modify how service runs
* **Protected branches** - Add or remove protected branches

### **Read-only fields**

* **GitHub URL** (for imported repos) - Cannot be changed after creation
* **Subdirectory** (if set) - Cannot be modified
* **Deploy key** (for imported repos) - Displayed for reference

## Deleting projects

### **Delete workflow**

1. **Access project settings**
   * Go to project settings
   * Scroll to **"Danger Zone"** section

2. **Delete confirmation**
   * Click **"Delete Project"** button
   * Confirm deletion in modal

3. **Post-deletion**
   * Project and all associated data are permanently removed
   * Cannot be undone
   * Repository data is deleted

<Warning>
  **Permanent deletion**

  Deleting a project permanently removes:

  * All cube definitions
  * All branches and history
  * All API credentials
  * All BI connections
  * All project settings

  This action cannot be undone. Make sure you have backups of important cube schemas before deleting.
</Warning>

## Branch management

### **Understanding branches**

Branches allow you to work on different versions of your cube definitions:

* **Main/master branch** - Production-ready cube definitions
* **Feature branches** - Development work for new features
* **Environment branches** - Different configurations for dev/staging/prod

### **Branch operations**

**Switch branches:**

1. Click branch name in header
2. Select branch from dropdown
3. System automatically:
   * Loads files for selected branch
   * Updates Cube Playground
   * Refreshes API credentials

**Delete branch:**

* Available in project settings
* Only non-protected branches can be deleted
* Cannot delete currently selected branch

### **Protected branches**

**Purpose:**

* Prevent accidental changes to critical branches
* Enforce code review workflows
* Maintain production stability

**Configuration:**

* Set in project settings
* Specify branch names (e.g., `main`, `master`, `production`)
* Protected branches cannot be deleted or directly modified

## Repository synchronization

### **Sync now**

Manually pull latest changes from Git repository:

1. **Click "Sync now" button** in header
2. **Wait for sync to complete**
3. **Changes reflected automatically:**
   * Files are refreshed
   * Cube Playground reloads
   * API credentials update if needed

**When to sync:**

* After pushing changes from external Git client
* When collaborators make changes
* After merging pull requests
* To ensure you have latest schema definitions

### **Automatic sync**

The system automatically:

* Syncs when switching projects
* Refreshes when switching branches
* Updates when project is first loaded

## Project selection

### **Selecting active project**

1. **Click project name** in header
2. **Select project** from dropdown menu
3. **System automatically:**
   * Switches to selected project
   * Starts heartbeat polling
   * Loads files and branches
   * Initializes Cube Playground

### **Project list**

The dropdown shows:

* All available projects
* Project names
* Current project indicator
* **"New project"** option (if you have permissions)

## Best practices

### **Project organization**

<CardGroup cols={2}>
  <Card title="One project per environment" icon="layer-group">
    **Separate environments**

    Use separate projects for dev, staging, and production to isolate changes and prevent accidents.
  </Card>

  <Card title="Logical naming" icon="tag">
    **Clear project names**

    Use descriptive names that indicate purpose: "Sales Analytics", "Marketing Metrics", "Finance KPIs".
  </Card>

  <Card title="Protected branches" icon="shield">
    **Protect production**

    Always protect main/master branches in production projects to prevent accidental changes.
  </Card>

  <Card title="Regular syncing" icon="sync">
    **Stay updated**

    Sync regularly to ensure you're working with the latest cube definitions and changes.
  </Card>
</CardGroup>

### **Branch management**

* **Use descriptive branch names** - `feature/new-metrics`, `fix/revenue-calculation`
* **Protect critical branches** - Always protect main/master branches
* **Sync before switching** - Ensure you have latest changes before switching branches
* **Clean up unused branches** - Delete branches that are no longer needed
* **Review before merging** - Use pull requests for protected branches

### **Repository selection**

* **Platform Managed** - Best for new projects and quick setup
* **Imported** - Best for existing projects and team collaboration
* **Consider team workflows** - Choose based on your team's Git practices

## Troubleshooting

### **Common issues**

<AccordionGroup>
  <Accordion icon="folder" title="Project creation fails">
    **Possible causes:**

    * Project name already exists
    * Environment not selected
    * Invalid GitHub URL (for imported repos)
    * Deployment key not added to GitHub

    **Solutions:**

    * Use a unique project name
    * Verify environment is configured
    * Check GitHub repository accessibility
    * Ensure deployment key is added to repository settings
  </Accordion>

  <Accordion icon="code-branch" title="Branch not showing">
    **Possible causes:**

    * Branch hasn't been synced from repository
    * Protected branch restrictions
    * Repository not fully cloned

    **Solutions:**

    * Click "Sync now" to refresh branches
    * Check project settings for branch restrictions
    * Wait for repository cloning to complete
  </Accordion>

  <Accordion icon="sync" title="Sync not working">
    **Possible causes:**

    * Git repository access issues
    * Network connectivity problems
    * Repository structure issues

    **Solutions:**

    * Verify repository access permissions
    * Check network connection
    * Review repository structure and files
    * Try refreshing the page and syncing again
  </Accordion>
</AccordionGroup>

***

<CardGroup cols={2}>
  <Card title="Cube Playground" icon="code" href="/core-features/metric-store/cube-playground">
    **Build cubes**

    Learn how to use Cube Playground to define and test your cubes.
  </Card>

  <Card title="Deployment Options" icon="settings" href="/core-features/metric-store/deployment-options">
    **Configure deployment**

    Understand deployment modes and scheduling options.
  </Card>
</CardGroup>