- Documentação
- Serviços
- Links de Deploy
Links de Deploy
Um link para https://app.guaracloud.com/services/new pode levar parâmetros de query que pré-preenchem o assistente de novo serviço. Use esses links em botões Deploy na Guara Cloud em READMEs, templates e documentação, ou deixe a CLI, o MCP ou um agente montarem o link para você.
Exemplos
Um serviço com build por Dockerfile a partir de um repositório GitHub:
https://app.guaracloud.com/services/new?name=Minha%20API&source=dockerfile&repo=https://github.com/org/app&branch=main&dockerfile=Dockerfile&port=3000&service_type=web&env.LOG_LEVEL=info
Um serviço a partir de uma imagem pública:
https://app.guaracloud.com/services/new?name=Minha%20API&source=image&image=ghcr.io/org/app:latest&port=8080&is_public=true
Um botão em um README:
[Deploy na Guara Cloud](https://app.guaracloud.com/services/new?name=Minha%20API&source=buildpack&repo=org/app)
Codifique os valores para URL: espaço vira %20, e & ou # dentro de um valor precisam ser codificados (%26, %23).
Parâmetros
Cada parâmetro tem um nome completo igual ao campo do assistente, e alguns têm um alias mais curto. Os dois funcionam.
| Parâmetro | Alias | Passo | Valor |
|---|---|---|---|
project | Topo | ID do projeto. Se a pessoa não puder criar serviços nele, o projeto padrão é usado. | |
name | Fonte | Nome do serviço, de 3 a 40 caracteres. O slug é gerado a partir dele. | |
source | build_method | Build | dockerfile, buildpack (padrão) ou image. |
service_type | Build | web (padrão) ou worker. | |
github_repo_url | repo | Build | https://github.com/dono/repo ou dono/repo. Só Dockerfile e Buildpack. |
github_branch | branch | Build | Branch de deploy. Exige repo. |
github_root_directory | root | Build | Diretório onde o build roda, como /apps/api. Exige repo. |
dockerfile_path | dockerfile | Build | Caminho relativo ao diretório raiz, sem ... Só com source=dockerfile. |
build_command | Build | Só com source=buildpack. Sem ; & $ \ ( ) { } < >, pipes ou crases. | |
start_command | Build | Só com source=buildpack. Mesmas regras do build_command. | |
image_reference | image | Build | Referência da imagem, como ghcr.io/org/app:1.2. Só com source=image. |
env.<CHAVE> | Ambiente | Uma variável de ambiente por parâmetro, como env.LOG_LEVEL=info. | |
port | Recursos | De 1 a 65535 (padrão 3000). Só serviços web. | |
is_public | Recursos | true ou false (1 ou 0). Só serviços web. | |
storage_enabled | Recursos | true ou false. Adiciona um volume persistente. | |
storage_size_mi | Recursos | Tamanho em MiB, no mínimo 128. Exige storage_enabled=true. Os limites do plano são checados ao criar. | |
volume_mount_path | Recursos | Caminho absoluto, como /data (padrão). Exige storage_enabled=true. |
Os parâmetros só valem onde o assistente mostra aquele campo. Por exemplo, image é ignorado sem source=image, e port é ignorado para um worker. Sem source, o assistente abre em Buildpack.
Não use project em botões públicos: IDs de projeto são de uma conta só. Ele serve para links montados para uma pessoa específica, como pela CLI ou por um agente.
O repositório GitHub
O assistente seleciona o repositório só quando a instalação do GitHub App da pessoa tem acesso a ele. Se não tiver, o assistente avisa, e a pessoa pode dar acesso ao app a esse repositório ou escolher outro. O branch só é selecionado se existir; caso contrário, o branch padrão do repositório continua selecionado.
Em um template público, quem faz o deploy usa a própria cópia: aponte para o template e peça um fork, ou use em repo um repositório que a pessoa já tenha.
Variáveis de ambiente
Use um parâmetro env.<CHAVE>=<valor> por variável. As chaves seguem as mesmas regras do assistente: letras, dígitos e underscore, começando com letra ou underscore. Nomes reservados como PORT, NODE_ENV, PATH ou qualquer um que comece com GUARA_ são ignorados. Valor vazio é permitido (env.FEATURE_FLAG=).
Restrições de segurança
Links passam por navegadores, chats e logs, então nunca levam segredos:
- Credenciais de registry (
registry_url,registry_username,registry_password) nunca são aplicadas. Preencha na seção de registry privado do assistente. - Variáveis de ambiente com nome de segredo são descartadas: nomes que contêm
SECRET,TOKEN,PASSWORD,PASS,PWD,PRIVATE_KEY,CREDENTIALS,API_KEYouACCESS_KEY. - Variáveis de ambiente com valor de credencial são descartadas, qualquer que seja o nome: URLs com senha (
postgres://usuario:senha@host), chaves privadas e tokens do GitHub, Stripe, Slack, AWS ou JWT.
Preencha esses valores você mesmo no passo Ambiente, ou depois de criar o serviço.
Tudo o que o assistente não aplica (desconhecido, inválido, repetido, segredo ou que não vale para as opções escolhidas) aparece pelo nome no aviso no topo do assistente, nunca com o valor. O resto continua preenchido. Quando um parâmetro aparece duas vezes, vale o primeiro valor.
Quem não está logado
Quem abre o link sem sessão passa primeiro pela tela de login e depois volta para o assistente com os mesmos parâmetros. Isso vale também para contas novas. Mantenha os links com menos de 2.000 caracteres para que funcionem também no login por link de email.