Environments

An environment is a deployment target within a project. Environments let you run different versions of your code side by side — for example, a production environment serving live traffic and a staging environment for testing.

What an Environment Contains

Each environment has:

• A current deployment — The deployment that currently receives live traffic for this environment. When a new deployment succeeds, it can be set as the current deployment.
• Deployment history — A record of all deployments created for this environment.
• Environment variables — Key-value pairs that are injected into your application at build time. Values are stored encrypted and are not exposed in API responses. See Manage Environment Variables.
• Custom domains — One or more subdomains on .phemeral.app that route traffic to the environment's current deployment. See Configure Custom Domains.
• GitHub branch mapping — An optional link between a GitHub branch and this environment. Pushes to the mapped branch trigger automatic deployments. See Set Up GitHub Continuous Deployment.
• Scheduled webhooks — Optional scheduled HTTP requests that target the environment's current deployment through its active domain. See Configure Scheduled Webhooks.

Creating an Environment

When you create a project, Phemeral automatically creates three environments for you: Production, Staging, and Development. You can create additional environments from the project's Environments page.

When creating an environment, you provide:

• An environment name.
• Optionally, initial environment variables.

When you create a project from the dashboard, any initial environment variables you provide are added to the Development environment.

How Traffic Reaches an Environment

Each environment can be assigned one or more custom domains in the format {subdomain}.phemeral.app. When a request arrives at a custom domain, it is routed to the environment's current deployment.

Individual deployments also have their own auto-generated domains in the format {deployment-id}.phemeral.app. These are useful for previewing a specific deployment regardless of which deployment is currently active on the environment.

Environments and Branches

An environment can have a GitHub branch mapped to it. When code is pushed to that branch, Phemeral automatically:

1. Downloads the code from the repository.
2. Creates a new deployment in the mapped environment.
3. Sets the new deployment as the environment's current deployment.

Multiple environments can map to different branches of the same repository. For example:

Unmapping a branch stops automatic deployments for that environment. Existing deployments are not affected.

Scheduled Webhooks

Scheduled webhooks are environment-bound HTTP requests that Phemeral runs on a UTC cron schedule.

Although you configure them from the project's Settings tab, each scheduled webhook targets one environment. Phemeral sends the request to that environment's oldest active domain, which means the request always reaches the environment's current deployment.

This makes scheduled webhooks useful for tasks that should follow an environment over time, such as:

• warming caches after traffic goes idle
• calling internal maintenance endpoints
• triggering application-level jobs on a schedule

If an environment has no active domains, scheduled webhooks for that environment cannot run until a domain becomes active again.