Projects

A project is a container that groups related environments together. Each project can be connected to a single GitHub repository for continuous deployment.

What a Project Contains

A project holds:

• Environments — One or more deployment targets (e.g. production, staging, preview). See Environments.
• GitHub repository connection — An optional link to a GitHub repository. When connected, pushes to mapped branches trigger automatic deployments.
• Deployment startup configuration — An optional custom start command that overrides Phemeral's autodetected runtime command for new deployments in the project.
• Deployment history — All deployments created across the project's environments.

Creating a Project

When you create a new project, you provide:

• A project name.
• Optionally, initial environment variables for the Development environment.

Every new project starts with three environments: Production, Staging, and Development.

Every organization starts with a default project called Launchpad that includes those same three environments.

You can create additional projects from the dashboard by navigating to Dashboard → New Project.

Connecting a GitHub Repository

A project can be connected to one GitHub repository at a time. This enables continuous deployment — when you push to a branch that is mapped to an environment, Phemeral automatically creates a new deployment.

To connect a repository:

1. Ensure your GitHub account is connected in User Settings.
2. Open your project's Settings tab.
3. Select a repository from the list of repositories that the Phemeral GitHub App can access.

When you disconnect a repository, all branch-to-environment mappings for the project are removed. Existing deployments are not affected.

See Set Up GitHub Continuous Deployment for the full setup guide.

Project-Level Start Command

Projects can optionally define a custom start command from the Settings tab.

When a custom command is saved, new deployments for that project use it instead of Phemeral's autodetected uvicorn or gunicorn command. Clearing the saved value returns the project to autodetection.

This setting is shared across the project. It does not change existing deployments that have already been created.

See Set a Custom Start Command for the workflow and Supported Frameworks for the autodetected defaults.

Projects and Organizations

Each project belongs to a single organization. All members of the organization can access its projects. There is no per-project access control — access is managed at the organization level.