Creating and managing projects

The project is the application: it is what has a public address, version history, and configuration.

Before you start

• A repository on GitHub, GitLab, or Bitbucket, with a Dockerfile in the folder that will be deployed.
• If you want to publish under your company's domain, activate the zone before creating the project: the zone is the base of the address, and choosing it later would mean changing the address.

Creating the project

Under Projects → Create project, the form has three blocks.

Identity

Field	What it decides
Project name	Appears in the public address. Lowercase letters, numbers, and hyphens, 3 to 40 characters
Domain	Which domain the address is composed under: the platform's or an already active zone of your own
Address	The label before the domain. Left blank, the platform composes it from the name

The form checks the final address's availability as you type, and suggests free alternatives. A name available in your organization can still produce an address that is taken — the address decides.

Project source

Field	What it decides
Provider	GitHub, GitLab, or Bitbucket. When the address names the host, the provider is inferred from it
Repository address	The full URL, the SSH address, or owner/repo. See the accepted forms
Branch or tag	Where the first version is deployed from
Folder inside the repository	Optional. Left blank, the root. In a monorepo, the folder holding the Dockerfile

This repository becomes the project source: every service in the project deploys from it. A public repository needs no credentials; a private repository needs an access token, entered afterwards under Source.

The reference is checked before the deployment starts: if the repository or branch does not resolve, you find out in the form rather than minutes later.

The folder is the most common cause of failure

Without naming the folder, the platform looks for the Dockerfile at the repository root. In a monorepo, that makes every deployment fail at Building, after the form said yes.

Where it will run

The Production environment is created with the project. There is nothing to fill in — the block exists to explain why there is no field.

Confirming

Create and deploy creates the project, the web service, and starts the first deployment. The console takes you to the project page, where the deployment is under way.

A double click, or a reconnection in the middle of the request, does not create two projects: the operation is protected against repetition.

The project source

The repository belongs to the project: one source per project. Services only choose the folder inside it and the reference — branch or tag. To deploy from another repository, create another project.

The source lives under Source, in the project. The repository field accepts three forms:

Form	Example
Full URL	https://github.com/owner/repo
SSH address	git@github.com:owner/repo.git
owner/repo, with the chosen provider	owner/repo

• Providers: GitHub, GitLab, and Bitbucket. GitLab accepts subgroups — group/subgroup/project.
• The host decides the provider. When the address carries the host, the provider is inferred from it. With no host, choosing the provider is required.
• Whatever does not match is refused, with the reason. A host outside the list is refused by name; a chosen provider that disagrees with the host is refused too.

The Save source button is only enabled with a complete address, and says next to it what is missing — for example, "The repository name is missing after “owner”. Use owner/repository.".

Access token

A public repository needs no token. For a private repository, enter an access token from the provider.

Once saved, the token never comes back to the screen: it shows Credential configured, with the option to replace it.

Changing it later

• Name and description — under Settings; what appears in lists.
• Public address — under Domains. Changing it releases the previous one as soon as the new one is live; the confirmation says what that affects. See Changing the address.
• Source — under Source: repository, branch or tag, and token, used in later deployments.

Deleting the project

Under Settings, click Delete project. The confirmation shows the impact and asks you to type the project's name — the defense against deleting the wrong project — and a reason (optional), which is recorded in the audit trail. The deletion is followed to the end; closing the window does not interrupt it.

When it finishes:

• The project disappears from the list and from every read: direct URL, API, and CLI answer "not found".
• The project name becomes free for a new project.
• Deployments that were queued are cancelled.
• Environments and services are shut down: the applications go offline.
• The source is revoked, and its credentials destroyed.
• The public address stops serving this project and stays reserved to your organization. No other organization can use it, and a new project in your organization can — just choose the same address. Links, sign-in callbacks, and webhooks that pointed to it stop responding, and never start responding for another organization.
• The history stays recorded: audit, operations, deployments, and versions.

From the CLI: zero projects delete <project> --reason "..." --yes. See CLI.

If the project uses a custom domain zone, the zone refuses to be deleted while the project exists. Delete the project first.

Common errors

Message	Meaning	What to do
"Use lowercase letters, numbers, and hyphens"	The name is part of the public address	Adjust the name
"This address is already in use"	The final address is reserved	Choose another or take a suggestion
"Zero deploys from GitHub, GitLab, or Bitbucket, and “…” is not one of them."	Another code provider	Mirror the repository to one of the three
"The address is from GitLab, but the chosen provider is GitHub."	The chosen provider disagrees with the address's host	Fix the provider, or the address
"The repository name is missing after “owner”. Use owner/repository."	Incomplete address	Complete the address
"Enter the folder without a leading slash"	A path starting with /	Write apps/api, not /apps/api

Next steps

• Deploy
• Project address
• Environment variables