Credenciais

O cluster Credenciais reúne, em um único lugar da barra lateral, 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. Cada tipo fica em uma aba própria, e todos os valores sensíveis são armazenados criptografados no banco do painel.

Esta página cobre as quatro abas: Provedores Git, Provedores de Servidor, Pacotes e SSH Keys.

#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 Credenciais > Provedores Git.
2. Clique em Conectar Provedor e selecione GitHub.
3. Siga o fluxo OAuth ou informe um Personal Access Token (PAT). O campo do token leva direto para a página de criação de token do GitHub e lista os escopos necessários. Para PATs clássicos, use repo (acesso aos repositórios) e admin:repo_hook (para o webhook de deploy automático).
4. O PrimeForge verifica a conexão e passa a listar os seus repositórios disponíveis na criação de sites.

#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 via nuvem" no assistente de criação de servidor.

#Provedores suportados

#Cadastrando um provedor

1. Acesse Credenciais > Provedores de Servidor e clique em Criar.
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 assistente 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. Um botão leva você ao painel da CloudPrime para concluir o desligamento lá — a cobrança só para quando você finaliza a VPS no provedor. Vale notar que a ação Excluir Servidor só remove os registros do lado do painel em qualquer provedor; ela não chama o endpoint de destruição da nuvem.

#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 Credenciais > Pacotes.
2. Clique em Criar 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) dentro do container, contendo somente as credenciais pertinentes. Isso permite que o Build instale pacotes privados sem expor tokens no repositório nem no .env.

#SSH Keys

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 Credenciais > SSH Keys e clique em Criar SSH Key.
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 ou apagar 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 aba SSH Keys própria nas suas configurações, útil para dar a um sistema de CI/CD acesso a apenas um servidor específico.

#Próximos passos

• Configuração do Painel — equipe, integrações e configurações gerais da organização.
• Gerenciando Servidores — criar e provisionar servidores usando os provedores de nuvem cadastrados aqui.
• Segurança — como o PrimeForge protege credenciais, tráfego e acesso.