Nesta página

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âmetroAliasPassoValor
projectTopoID do projeto. Se a pessoa não puder criar serviços nele, o projeto padrão é usado.
nameFonteNome do serviço, de 3 a 40 caracteres. O slug é gerado a partir dele.
sourcebuild_methodBuilddockerfile, buildpack (padrão) ou image.
service_typeBuildweb (padrão) ou worker.
github_repo_urlrepoBuildhttps://github.com/dono/repo ou dono/repo. Só Dockerfile e Buildpack.
github_branchbranchBuildBranch de deploy. Exige repo.
github_root_directoryrootBuildDiretório onde o build roda, como /apps/api. Exige repo.
dockerfile_pathdockerfileBuildCaminho relativo ao diretório raiz, sem ... Só com source=dockerfile.
build_commandBuildSó com source=buildpack. Sem ; & $ \ ( ) { } < >, pipes ou crases.
start_commandBuildSó com source=buildpack. Mesmas regras do build_command.
image_referenceimageBuildReferência da imagem, como ghcr.io/org/app:1.2. Só com source=image.
env.<CHAVE>AmbienteUma variável de ambiente por parâmetro, como env.LOG_LEVEL=info.
portRecursosDe 1 a 65535 (padrão 3000). Só serviços web.
is_publicRecursostrue ou false (1 ou 0). Só serviços web.
storage_enabledRecursostrue ou false. Adiciona um volume persistente.
storage_size_miRecursosTamanho em MiB, no mínimo 128. Exige storage_enabled=true. Os limites do plano são checados ao criar.
volume_mount_pathRecursosCaminho 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_KEY ou ACCESS_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.