Credenciais

A seção Credenciais reúne, dentro do submenu de Configurações, todas as credenciais que o PrimeForge usa para trabalhar em seu nome: a conta do GitHub de onde ele busca o seu código, os tokens de nuvem que provisionam servidores, as credenciais de registries privados de pacotes e as chaves SSH que dão acesso aos servidores gerenciados. Todos os valores sensíveis são armazenados criptografados no banco do painel.

Esta página cobre as quatro entradas da seção: Provedores Git, Provedores de Servidor, Pacotes e Chaves SSH. Elas já foram um grupo próprio do menu principal; links antigos para /admin/credentials/… continuam funcionando e redirecionam para cá.

#Provedores Git

O PrimeForge faz deploy de código a partir de repositórios Git. Para criar sites a partir de repositórios privados — e para habilitar o deploy automático por push — você precisa conectar a sua conta do GitHub.

#Conectando o GitHub

1. Acesse Configurações → Credenciais → Provedores Git (pelo menu do avatar).
2. Clique em Criar Provedor Git, dê um nome (ex.: "Minha conta GitHub") e selecione GitHub.
3. Cole um Personal access token (PAT). A ajuda do campo leva direto para a página de criação de token do GitHub. Para PATs clássicos, use os escopos repo (acesso aos repositórios) e admin:repo_hook (para o webhook de deploy automático). Se o token expira, informe a expiração do token.
4. Salve. A partir daí o provedor aparece no assistente de criação de sites, e os repositórios privados que o token alcança passam a ser aceitos.

#Testar token

Use a ação Testar token — disponível no formulário de criação, na página de edição e em cada linha da lista de provedores — para validar um token na hora. Ela autentica contra o GitHub, mostra a qual conta o token pertence e avisa quando um PAT clássico está sem o escopo repo ou admin:repo_hook (a causa mais comum de o webhook de deploy automático falhar mais tarde). Sempre que criar ou trocar um token, rode esse teste antes de depender dele.

#Deploy automático por push

Com um provedor GitHub conectado, sites novos já vêm com o deploy automático habilitado. Para repositórios hospedados no GitHub, o PrimeForge registra automaticamente um webhook de push no seu repositório, guardando o id do webhook no site para poder removê-lo de forma limpa quando você desabilitar o deploy automático ou apagar o site. Cada push na branch configurada dispara um deploy; pushes em sequência são deduplicados, de modo que apenas o mais recente é executado.

#Provedores de Servidor

O PrimeForge pode criar VPS em seu nome, eliminando o trabalho manual de subir uma máquina no provedor, copiar o IP e colar no painel. Para isso, você registra as credenciais de API dos provedores de nuvem suportados. Uma vez salvas, elas ficam disponíveis como opção Provisionar automaticamente via cloud no formulário Criar Servidor.

#Provedores suportados

#Cadastrando um provedor

1. Acesse Configurações → Credenciais → Provedores de Servidor e clique em Criar Provedor de Servidor.
2. Selecione o provedor, dê um nome à credencial e cole o token.
3. Clique em Criar — o PrimeForge valida o token contra a API do provedor e o salva criptografado.

Depois de salvo, o formulário Criar Servidor passa a oferecer o provedor como opção de provisionamento automático. O PrimeForge envia uma chave SSH da organização ao provedor (idempotente pela fingerprint), cria a VPS, aguarda ela ficar ativa e inicia o provisionamento de ponta a ponta. No caso da CloudPrime, a chave pública SSH é passada em cada chamada de provisionamento, sem uma etapa separada de upload de chave.

#Escopos do token (DigitalOcean)

A DigitalOcean emite tokens com escopos granulares, e o PrimeForge usa duas capacidades distintas:

Um token sem o escopo Domains faz o PrimeForge cair para o desafio HTTP-01 na emissão de certificados. Por isso, a página de edição do provedor oferece dois botões de teste separados: Testar token (Droplets), que confirma se o token consegue provisionar VPS, e Testar token (Domains), que confirma se o token consegue gravar registros de DNS. Se o teste de Domains retornar ausente, gere um novo token com Domains: Read + Write habilitado e cole no provedor.

#CloudPrime — soft-detach ao excluir

A API da CloudPrime não expõe um endpoint de exclusão de VPS. Quando você clica em Excluir servidor para uma máquina CloudPrime, o painel mostra um aviso de soft-detach: o registro é removido do PrimeForge, mas a VPS continua rodando na CloudPrime. O botão Abrir painel de VPS da Cloud Prime leva você até lá para concluir o desligamento — a cobrança só para quando você finaliza a VPS no provedor.

Com a DigitalOcean é diferente: excluir no PrimeForge um servidor que o próprio painel criou também destrói o droplet no provedor. Se a destruição falhar (um token revogado, por exemplo), o servidor sai do painel mesmo assim e uma notificação crítica avisa que a VM continua cobrando, para você removê-la no console da DigitalOcean. Servidores conectados por SSH nunca são apagados no provedor.

#Pacotes

Se a sua aplicação instala dependências de registries privados Composer ou NPM, você pode registrar as credenciais centralmente e o PrimeForge as injeta durante o estágio de Build do deploy — sem que nada seja gravado em disco fora da janela de build.

#Cadastrando uma credencial de pacote

1. Acesse Configurações → Credenciais → Pacotes.
2. Clique em Criar Credencial de Pacote e escolha Composer ou NPM.
3. Preencha os dados de autenticação — HTTP-basic (usuário/senha), bearer, tokens de OAuth ou de acesso para Composer; registry, escopo e token para NPM.
4. Defina o escopo, que controla onde a credencial se aplica:

Durante cada deploy, o PrimeForge resolve as credenciais aplicáveis a cada site e gera um auth.json (Composer) ou um .npmrc (NPM) no diretório de build da release do site, sob o usuário Linux dedicado do site, contendo somente as credenciais pertinentes. Isso permite que o Build instale pacotes privados sem expor tokens no repositório nem no .env.

#Chaves SSH

As chaves SSH da organização dão acesso administrativo aos servidores gerenciados. O PrimeForge gerencia essas chaves centralmente pelo painel e as distribui aos usuários root e primeforge de cada servidor, o que permite rastreamento no log de auditoria e revogação centralizada.

#Adicionando uma chave

1. Acesse Configurações → Credenciais → Chaves SSH e clique em Criar Chave SSH.
2. Dê um nome e cole a sua chave pública (o conteúdo de ~/.ssh/id_ed25519.pub ou similar).
3. Escolha o escopo — todos os servidores (global) ou servidores específicos.
4. O PrimeForge distribui a chave imediatamente aos servidores selecionados, importando-a para os usuários root e primeforge.

#Revogação

Revogar (reversível, com Reativar) ou Excluir uma chave a remove de todos os servidores conectados em poucos segundos: o painel chama o Agent de cada servidor em paralelo e reescreve o authorized_keys. Uma chave revogada não consegue mais fazer login, mesmo que uma cópia antiga da chave pública esteja em cache em alguma estação de trabalho. Rotacione ou revogue proativamente sempre que alguém com acesso deixar a equipe.

Nunca adicione chaves SSH diretamente nos servidores. Gerencie-as sempre pelo painel — assim toda alteração fica registrada no log de auditoria e você mantém a capacidade de revogar de forma central. Chaves adicionadas manualmente na máquina escapam desse controle.

Além das chaves globais e por servidor gerenciadas aqui, cada servidor também tem uma página Chaves SSH própria (grupo Rede e segurança da sua sub-navegação), útil para dar a um sistema de CI/CD acesso a apenas um servidor específico.

#Próximos passos

• Equipe e Conta — o restante de Configurações: organização, membros e chaves de API.
• Gerenciando Servidores — criar e provisionar servidores usando os provedores de nuvem cadastrados aqui.
• Segurança — como o PrimeForge protege credenciais, tráfego e acesso.