Criar e gerenciar projetos

O projeto é a aplicação: é ele que tem endereço público, histórico de versões e configuração.

Antes de começar

• Um repositório no GitHub, no GitLab ou no Bitbucket, com um Dockerfile na pasta que será publicada.
• Se você quer publicar sob o domínio da sua empresa, ative a zona antes de criar o projeto: a zona é a base do endereço e escolhê-la depois significaria trocar o endereço.

Criar o projeto

Em Projetos → Criar projeto, o formulário tem três blocos.

Identidade

Campo	O que decide
Nome do projeto	Aparece no endereço público. Letras minúsculas, números e hífen, de 3 a 40 caracteres
Domínio	Sob qual domínio o endereço será composto: o da plataforma ou uma zona própria já ativa
Endereço	O rótulo antes do domínio. Em branco, a plataforma compõe a partir do nome

O formulário confere a disponibilidade do endereço final enquanto você digita, e sugere alternativas livres. Um nome disponível na sua organização pode produzir um endereço já ocupado — é o endereço que decide.

Origem do projeto

Campo	O que decide
Provedor	GitHub, GitLab ou Bitbucket. Quando o endereço diz o host, o provedor é deduzido dele
Endereço do repositório	A URL completa, o endereço SSH ou dono/repo. Ver as formas aceitas
Branch ou tag	De onde a primeira versão será publicada
Pasta dentro do repositório	Opcional. Em branco, a raiz. Num monorepo, a pasta onde está o Dockerfile

Este repositório passa a ser a origem do projeto: todos os serviços do projeto publicam dele. Repositório público não precisa de credencial; repositório privado pede um token de acesso, informado depois em Origem.

A referência é conferida antes da publicação começar: se o repositório ou a branch não resolvem, você descobre no formulário e não minutos depois.

A pasta é a causa de falha mais comum

Sem indicar a pasta, a plataforma procura o Dockerfile na raiz do repositório. Num monorepo, isso faz toda publicação falhar em Construindo, depois de o formulário ter dito sim.

Onde vai rodar

O ambiente Production nasce com o projeto. Não há o que preencher — o bloco existe para explicar por que não existe um campo.

Confirmar

Criar e publicar cria o projeto, o serviço web e já inicia a primeira publicação. O console leva você para a página do projeto, onde a publicação está acontecendo.

Um clique duplo, ou uma reconexão no meio do envio, não cria dois projetos: a operação é protegida contra repetição.

A origem do projeto

O repositório é do projeto: uma origem por projeto. Os serviços escolhem só a pasta dentro dele e a referência — branch ou tag. Para publicar de outro repositório, crie outro projeto.

A origem fica em Origem, no projeto. O campo do repositório aceita três formas:

Forma	Exemplo
URL completa	https://github.com/dono/repo
Endereço SSH	git@github.com:dono/repo.git
dono/repo, com o provedor escolhido	dono/repo

• Provedores: GitHub, GitLab e Bitbucket. O GitLab aceita subgrupos — grupo/subgrupo/projeto.
• O host decide o provedor. Quando o endereço traz o host, o provedor é deduzido dele. Sem host, escolher o provedor é obrigatório.
• O que não bate é recusado, com o motivo. Um host fora da lista é recusado com o nome dele; um provedor escolhido que diverge do host também.

O botão Salvar origem só habilita com um endereço completo, e diz ao lado o que falta — por exemplo, "Falta o nome do repositório depois de “dono”. Use dono/repositório.".

Token de acesso

Repositório público não precisa de token. Para um repositório privado, informe um token de acesso do provedor.

Depois de salvo, o token nunca volta para a tela: aparece Credencial configurada, com a opção de substituí-lo.

Alterar depois

• Nome e descrição — em Configurações; o que aparece nas listas.
• Endereço público — em Domínios. Trocar libera o anterior assim que o novo estiver no ar; a confirmação diz o que isso afeta. Ver Trocar o endereço.
• Origem — em Origem: repositório, branch ou tag e token, usados nas próximas publicações.

Excluir o projeto

Em Configurações, clique em Excluir projeto. A confirmação mostra o impacto e pede que você digite o nome do projeto — é a defesa contra excluir o projeto errado — e um motivo (opcional), que fica registrado na auditoria. A exclusão é acompanhada até o fim; fechar a janela não a interrompe.

Quando ela termina:

• O projeto some da lista e de toda leitura: URL direta, API e CLI respondem "não encontrado".
• O nome do projeto fica livre para um projeto novo.
• Publicações que estavam na fila são canceladas.
• Ambientes e serviços são encerrados: as aplicações saem do ar.
• A origem é revogada, e as credenciais dela, destruídas.
• O endereço público deixa de servir este projeto e permanece reservado à sua organização. Nenhuma outra organização pode usá-lo, e um projeto novo da sua organização pode — basta escolher o mesmo endereço. Links, callbacks de login e webhooks que apontavam para ele deixam de responder, e nunca passam a responder por outra organização.
• O histórico continua registrado: auditoria, operações, deployments e versões.

Pela CLI: zero projects delete <projeto> --reason "..." --yes. Ver CLI.

Se o projeto usa uma zona de domínio próprio, a zona recusa ser removida enquanto o projeto existir. Exclua o projeto primeiro.

Erros comuns

Mensagem	Significado	O que fazer
"Use letras minúsculas, números e hífen"	O nome participa do endereço público	Ajuste o nome
"Este endereço já está em uso"	O endereço final está reservado	Escolha outro ou use uma sugestão
"O Zero publica a partir de GitHub, GitLab ou Bitbucket, e “…” não é um deles."	Outro provedor de código	Espelhe o repositório em um dos três
"O endereço é do GitLab, mas o provedor escolhido é GitHub."	O provedor escolhido diverge do host do endereço	Corrija o provedor, ou o endereço
"Falta o nome do repositório depois de “dono”. Use dono/repositório."	Endereço incompleto	Complete o endereço
"Informe a pasta sem a barra inicial"	Caminho começando com /	Escreva apps/api, não /apps/api

Próximos passos

• Publicar
• Endereço do projeto
• Variáveis de ambiente