Guia dos espaços Git

Um repositório Git do Flow é um repositório verdadeiro (clonas e fazes push com o git que já usas) que vive dentro do Flow em vez de num serviço externo. Código, tasks e pull requests estão onde estão também os teus ficheiros: o mesmo login, os mesmos membros e permissões, a mesma cópia de segurança, a mesma instância, europeia ou na tua empresa.

Foi pensado para quem não quer (ou não pode) deixar o código sair: o repositório é um espaço como os outros, com os seus membros e dois papéis (editor faz push, leitor clona e lê), mais os administradores, que podem tudo. Os repositórios aparecem na secção Repositórios da barra lateral, e ocupam espaço na quota do plano como tudo o resto.

No navegador encontras cinco separadores: Código, Commits, Tasks, Pull requests e Acesso. Os dois primeiros servem para consultar, os outros para trabalhar: o trabalho de equipa (quem faz o quê, o que entra no ramo principal) acontece aí.

O clone e o push passam por HTTPS, com credenciais criadas para o efeito:

• utilizador = o teu email;
• palavra-passe = uma palavra-passe Git, que crias tu mesmo no separador Acesso do repositório («Como ligar», com o comando de clone já pronto a copiar).

A palavra-passe só se vê no momento da criação: copia-a para o gestor de credenciais do git (no Mac osxkeychain, no Windows Git Credential Manager) e não volta a ser pedida. Se a perderes não se recupera: crias outra e revogas a antiga. As tuas palavras-passe Git vês e revogas em Conta → Git; uma palavra-passe vale para todos os repositórios a que tens acesso, e para mais nada: não abre a app e não vale para a API.

Quem pode fazer o quê é decidido pelo papel no espaço: editor faz push de ramos e tags como em qualquer remoto, leitor só clone e fetch. Quem não é membro nem sequer vê o repositório.

O separador Código mostra a árvore de ficheiros no ramo escolhido, e a página inicial do repositório abre o README da raiz, como seria de esperar. Os ficheiros de texto leem-se aí; para um binário ou um ficheiro muito grande o navegador é claro: diz-te para clonares.

O separador Commits é o histórico do ramo: cada commit abre-se no seu diff. No texto de tasks e comentários, um sha leva diretamente ao diff desse commit.

O navegador foi pensado para ler e decidir: escreve-se localmente, com o próprio editor, e faz-se push. A única escrita que passa pela web é a que tem de passar por lá: fundir uma pull request.

Os tasks são onde a equipa comunica: bugs a corrigir, alterações a pedir, coisas a fazer, discussões. Quatro tipos (Bug, Pedido de alteração, To-do, Discussão) e de resto a mesma forma: título, texto em Markdown, comentários, estado aberto/fechado.

Cada task tem um número: escrever #12 num task, num comentário ou numa pull request cria a ligação; um sha de commit torna-se a ligação para o seu diff. Um task pode ter um responsável (entre os membros), etiquetas e uma prioridade; os filtros no topo da lista («Abertos», «Os meus tasks», a pesquisa) ajudam a orientar-te quando os tasks passam a ser muitos.

O que ainda não leste vê-se: o task com novidades aparece a negrito, e o separador mostra o contador «por ler». Os emails seguem a tua preferência em Conta → Notificações por email → Tasks: quem participa num task (autor, responsável, quem comentou) recebe atribuições, comentários e fechos.

A um task anexam-se ficheiros: vão para uma pasta «Task #n» do espaço, e no texto fica a referência. Útil para capturas de ecrã, logs, documentos de partida: ficam no repositório de quem trabalha nele, não num chat externo.

Uma pull request propõe fundir um ramo noutro. Abre-la escolhendo os dois ramos (uma PR aberta por ramo de cada vez), e o separador diz-te de imediato e em tempo real em que estado está: «funde-se sem conflitos: n commits», ou a lista dos ficheiros em conflito, que resolves localmente, e no push seguinte o separador atualiza-se.

Por baixo estão os commits que vão entrar e o diff completo. Comenta-se no fim ou na linha concreta do diff: cada linha abre um fio com Responder e Resolver, e os fios nas linhas que um novo push alterou não se perdem: passam para o fim, com o seu caminho e número de linha.

As reviews dão o veredicto: Aprovar ou Pedir alterações (nunca na própria PR). Conta o último veredicto de cada um, e uma aprovação vale para a versão do ramo em que foi dada: depois de um novo push fica marcada «numa versão anterior do ramo» e deixa de contar.

Fundir a partir da web, escolhendo como entram os commits:

• commit de merge: o histórico fica como está, com um commit de fusão assinado por quem carrega no botão;
• squash: todos os commits comprimidos num só, assinado por quem abriu a PR;
• rebase: os commits reaplicados em fila por cima do destino, sem commit de merge.

Há a opção «apagar o ramo depois do merge», e se, em vez disso, fundires a partir do terminal com git, a PR deteta-o sozinha e fica marcada «Fundida com git».

Num ramo protegido ninguém faz push direto, nem os editores: quem tenta recebe a recusa do servidor, com a indicação do motivo. No ramo só se entra de uma forma: fundindo uma pull request a partir da web.

Protege-se um ramo no separador Acesso (é necessário um administrador), e para cada ramo pode exigir-se um número de aprovações: a PR só se funde quando as reviews aprovadas forem suficientes, e uma review «pedir alterações» bloqueia até mudar. O administrador pode fundir na mesma: a regra disciplina a equipa, não lhe tira as chaves.

É a forma de dizer «ao main só se chega com uma PR revista», e de fazer com que seja o servidor a garanti-lo em vez de um acordo verbal.

Cada push é posto em segurança de imediato, no mesmo arquivo protegido dos teus ficheiros: cópias redundantes, verificações contínuas, reposição automática. Não há nada a configurar nem nada de que te tenhas de lembrar.

A página do repositório diz-te quando foi feita a última cópia («Cópia de segurança atualizada…») e, se uma cópia não tiver corrido bem, indica-o.

Na quota do plano o repositório pesa o que pesa realmente, com a deduplicação que vale para tudo o resto: um repositório normal ocupa pouco.

A palavra-passe Git abre também uma porta adicional: as rotas da API dos tasks e das pull requests (/api/repos/…/tasks e /api/repos/…/pulls). Com um curl autenticado (utilizador o teu email, palavra-passe a palavra-passe Git) é possível listar os tasks, ler uma PR, comentar, anexar um ficheiro a um task ou a uma PR. Só essas rotas: para o resto da API é necessário um token API verdadeiro (é explicado na página Programadores).

Serve a quem automatiza o próprio fluxo de trabalho (scripts, ferramentas de desenvolvimento, agentes) sem distribuir credenciais mais amplas do que o necessário: a palavra-passe Git pode ser revogada num clique em Conta → Git, e o seu âmbito é o trabalho no repositório.