Como resolver avisos de acesso, branch e deploy em Ambientes

Na aba GitHub de Ambientes, o Benflow confere cada repositório e, quando algo não fecha, explica o motivo e mostra um guia Como resolver. Há três tipos de aviso: o repositório não abre (falta acesso), a branch de um ambiente não existe e a branch existe, mas nada sobe com push nela. O guia de acesso é só para o admin da organização, que também cria a branch e muda o workflow.

Como ler o esquema da conexão

Logo abaixo dos dados da conexão, um esquema liga o Benflow (só leitura) à conta do GitHub (@sua-conta, conectada ou sem conexão) e aos repositórios. Verde quer dizer que está tudo certo e vermelho, que há um problema. Em cada repositório, a frase embaixo do nome diz o que falta, como acesso, branches e deploy ok ou falta a branch develop.

Cada repositório tem a Leitura do repositório (leitura liberada ou sem acesso) e, para cada ambiente, duas checagens com o selo ok ou falta: Branch (a branch existe) e Deploy por push (há um workflow que roda com push nela). O selo do repositório vira Tudo certo ou Com problema.

Sem acesso ao repositório

Quando o GitHub recusa o acesso, o Testar conexão mostra uma faixa vermelha com Motivo encontrado em o repositório e o link Ver o passo a passo. O guia Como resolver fica embaixo do repositório e traz:

• O motivo que o GitHub deu, em português. Os mais comuns: o token foi criado com a conta pessoal como dono, o repositório não está marcado no token, falta permissão de leitura, a validade é maior que a permitida, falta autorizar o token no login único (SSO), o token espera a aprovação da organização, a organização não aceita aquele tipo de token, o token clássico está sem o escopo repo ou a conta não tem acesso ao repositório.
• Dois quadros lado a lado, O token enxerga hoje (a conta e os repositórios que ela vê) e Como precisa ficar.
• O passo a passo, com miniaturas do formulário do GitHub que marcam o que escolher.

O caminho principal é o token clássico. O guia abre o formulário no GitHub pelo botão Criar token clássico no GitHub, com o escopo repo já marcado e a validade de até 1 ano. Se a organização usa SSO, o passo seguinte é autorizar o token em Configure SSO. Por fim, o botão Colar o token agora leva ao formulário do Benflow e você clica em Testar conexão.

Quando o problema é a conta (A conta @... não tem acesso a o repositório), nenhum token resolve: um dono da organização precisa dar acesso à conta, e o token clássico passa a enxergar o repositório sozinho. Prefere o token mais restrito? O bloco Prefere o token fine-grained (só leitura, por repositório)? traz os passos para ele.

Criar a branch que falta

Se o repositório não tem a branch de um ambiente, como a develop, o repositório mostra o cartão Crie a branch develop para ter homologação. Ele explica para que serve (a homologação é onde a equipe, ou o Claude, publica para você conferir antes de ir para o ar) e desenha o caminho do código: a branch do chamado, a develop (falta criar) e a main.

1. 1
   Passo 1: Clique em Criar a branch develop. O botão aparece para o admin quando há token conectado.
2. 2
   Passo 2: Na janela Criar a branch develop, confira o aviso: o Benflow cria a branch igual à de produção de agora, e nenhuma outra branch muda.
3. 3
   Passo 3: Clique em Criar develop. A mensagem confirma a branch criada, e você clica em Testar conexão para conferir.

Se o GitHub recusar, a janela mostra o que ajustar. Com token fine-grained, a permissão Contents precisa estar em Read and write. Sem token (ou sem ser admin), o link Criar no GitHub leva à tela de branches do repositório, e Ver as branches no GitHub mostra o que já existe.

Falta o deploy por push em uma branch

Se a branch existe, mas um push nela não publica em lugar nenhum (por exemplo, o deploy.yml roda só com a main), o cartão Falta o deploy da develop (homologação) mostra Como resolver. Cada branch precisa de um workflow que rode com push nela, e há dois jeitos:

• Um arquivo por branch (recomendado): o arquivo de produção fica como está, e a develop ganha o seu, como deploy-homolog.yml, criado na própria branch. O Benflow acha o arquivo sozinho pelo nome (deploy, homolog ou staging).
• Um arquivo só: o gatilho leva as duas branches e cada etapa escolhe o destino pela branch. Funciona, mas um erro nessa escolha publica a branch no lugar errado.

O cartão traz o Prompt para a IA. Clique em Copiar prompt (ou Ver o prompt) e cole no Claude Code, aberto na pasta do repositório. Ele cria o workflow, diz quais secrets cadastrar no GitHub (em Settings, Secrets and variables, Actions) e faz o push. Depois, clique em Testar conexão. Se a produção é publicada à mão de propósito, pode deixar assim: o Benflow só não acompanha o deploy a cada push.

Já o projeto que não tem servidor de homologação não precisa de nada disso: use Este projeto não tem homologação, no mesmo cartão. Veja Projeto sem homologação.