Gestão de equipes com GitHub
Equipes no GitHub são o recurso que organiza pessoas de uma organização em grupos, com permissões e menções compartilhadas. Neste artigo, você vai entender para que elas servem, como criar uma equipe e como usar cada página do time no dia a dia.
Por que usar equipes no GitHub
Quem já administrou repositórios sem equipes conhece a confusão de alterar o acesso de um grupo de pessoas, uma a uma.
Quando existem vários repositórios, e pessoas diferentes têm níveis de acesso distintos em cada um, a situação fica ainda mais confusa.
O recurso de equipes no GitHub existe justamente para resolver esse problema. Em vez de conceder permissões individuais, você concede acesso ao time, e todos os membros herdam esse acesso.
Segundo a documentação oficial sobre equipes, as equipes refletem a estrutura da empresa ou do grupo, com permissões e menções em cascata.
O que as equipes no GitHub oferecem
Ter visibilidade do trabalho de cada equipe e de seus membros é uma das muitas formas de melhorar a produtividade.
Além disso, identificar rapidamente problemas, como queda de desempenho ou entregas pouco frequentes, é crucial para entregar valor.
As equipes no GitHub reúnem vários recursos que ajudam nessa gestão. Por exemplo, você pode conceder permissões de leitura, escrita ou administração para todo o grupo de uma vez.
Também é possível notificar todos os membros apenas citando a equipe com @organizacao/nome-da-equipe em uma issue ou pull request.
Outro ganho importante é a associação da equipe a projetos e repositórios. Assim, você importa as permissões de várias pessoas ao mesmo tempo.
Esses são apenas alguns exemplos das funções do recurso. A seguir, veja como começar a explorá-lo na prática.
Equipes visíveis e secretas
Todas as equipes no GitHub têm um nível de visibilidade, que você define no momento da criação.
Equipes visíveis podem ser vistas e mencionadas por qualquer membro da organização.
Já as equipes secretas ficam visíveis apenas para os próprios membros e para os proprietários da organização. Por isso, elas costumam proteger trabalhos sensíveis, como projetos com parceiros externos.
Vale notar, contudo, que equipes secretas não podem participar de hierarquias de equipes aninhadas.
Equipes aninhadas
A organização pode montar hierarquias com vários níveis de equipes no GitHub. Nesse modelo, uma equipe pai pode ter várias equipes filhas, mas cada filha tem apenas um pai.
As equipes filhas herdam as permissões de acesso da equipe pai. Dessa forma, a gestão de permissões em grupos grandes fica muito mais simples.
Por outro lado, a menção funciona apenas no nível citado. Ou seja, mencionar uma equipe filha não notifica os membros da equipe pai.
Criando equipes no GitHub
Diferente dos projetos, que podem pertencer a organizações, usuários e repositórios, as equipes existem apenas dentro da organização à qual pertencem.
Por padrão, os proprietários da organização podem criar equipes. Eles também decidem se todos os membros terão essa permissão.
Entrando na página da organização, você encontra a aba de equipes no menu, como mostra o exemplo abaixo.
Em seguida, aparece o botão para criar uma nova equipe, logo abaixo do menu.
Depois de clicar no botão, o GitHub exibe um formulário como o mostrado abaixo.
Preenchendo o formulário
Primeiro, informe o nome da equipe, que é o único campo obrigatório.
Se necessário, adicione uma descrição. Logo abaixo, você pode escolher uma equipe pai, caso ela já exista.
Ignore esse campo quando não houver outra equipe para definir como pai, ou quando a hierarquia simplesmente não fizer sentido.
Como último passo, defina a visibilidade da equipe. Marque a opção secreta quando o time for privado, pois assim apenas os membros conseguirão vê-lo.
Escolha a opção visível quando não houver razão para manter a equipe oculta. Nesse caso, toda a organização poderá encontrá-la e mencioná-la.
O formulário também permite ativar ou desativar as notificações da equipe. Essa opção afeta apenas as notificações geradas por menções ao time.
Assim que você criar a equipe, o GitHub abre a página de visualização dela.
Página inicial
Quando o artigo original foi escrito, a visualização inicial mostrava as discussões existentes dentro da equipe.
Esse espaço era muito útil para avisos gerais, processos de idealização e instruções. Além disso, todos os membros podiam visualizar e participar das conversas.
No entanto, o GitHub aposentou o recurso de discussões de equipe. Hoje, a recomendação oficial é usar o GitHub Discussions para esse tipo de comunicação.
Na prática, você pode criar uma categoria de discussões em um repositório da organização e usar a menção da equipe para chamar os membros certos.
A página de cada uma das equipes no GitHub, por sua vez, continua como ponto de partida para membros, equipes filhas e repositórios do time.
Página de membros das equipes no GitHub
Na página de membros, você vê todas as pessoas da equipe e pode agrupar a visualização por nível de permissão.
Caso tenha o nível necessário, você também pode gerenciar os membros diretamente nessa tela.
Observe que o nome de cada membro é um hipertexto. Ao clicar nele, você chega à página da pessoa dentro da organização, assunto do artigo sobre gestão de organizações com GitHub.
Adicionando um membro à equipe
Na figura anterior, repare no botão verde para adicionar um membro.
Ao clicar nele, surge uma caixa de diálogo que pede o nome de usuário, o e-mail ou o nome completo da pessoa.
Basta informar um desses dados para ver, logo abaixo da caixa de texto, uma lista com o resultado da pesquisa.
Então, selecione o usuário desejado e confirme o convite.
Se a pessoa já pertence à organização, ela entra na equipe imediatamente. Caso contrário, ela recebe um convite por e-mail para entrar na organização e na equipe ao mesmo tempo.
Segundo a documentação, proprietários e mantenedores da equipe podem adicionar membros da organização. Porém, apenas proprietários podem convidar quem ainda não faz parte da organização.
Membros e mantenedores
Dentro das equipes no GitHub, cada pessoa ocupa o papel de membro ou de mantenedor.
O mantenedor pode alterar nome e descrição do time, adicionar e remover pessoas e ajustar configurações como a revisão de código.
Dessa forma, o proprietário da organização delega a gestão do dia a dia sem conceder acesso total à organização.
Equipes secundárias
Repare também que o menu da equipe tem um item de equipes. Ali ficam as equipes filhas, ou secundárias, ligadas ao time atual.
Esse item reflete a hierarquia de equipes aninhadas descrita anteriormente. Assim, você navega rapidamente pelos times que herdam as permissões do grupo principal.
Página de repositórios das equipes no GitHub
Na página de repositórios, você vê todos os repositórios aos quais a equipe tem acesso.
Novamente, se você tiver o nível de acesso necessário, poderá vincular um novo repositório ao time.
Para isso, clique no botão de adicionar repositório. Uma caixa de diálogo aparece, e você digita o nome ou parte do caminho do repositório.
Em seguida, selecione a opção desejada na lista de resultados e salve. Veja o exemplo abaixo.
Papéis de acesso ao repositório
Ao vincular um repositório, você escolhe o papel que a equipe terá nele.
O GitHub oferece cinco papéis padrão. Nesse conjunto, o papel Read serve para quem só precisa ver ou discutir o projeto.
O papel Triage atende quem gerencia issues e pull requests sem precisar de acesso de escrita.
Já o papel Write é indicado para quem envia código ao repositório com frequência.
O papel Maintain atende gestores de projeto que administram o repositório sem acesso a ações destrutivas ou sensíveis.
Por fim, o papel Admin concede acesso total, incluindo ações como gerenciar a segurança ou excluir o repositório.
Na prática, conceder esses papéis às equipes no GitHub, e não a pessoas isoladas, reduz bastante o trabalho de manutenção dos acessos.
Página de projetos das equipes no GitHub
Assim como a página de repositórios, essa página exibe todos os projetos aos quais a equipe está vinculada.
Com isso, os membros encontram em um só lugar os quadros de planejamento que acompanham o trabalho do time.
Para entender como montar e organizar esses quadros, leia o artigo sobre gestão de projetos com GitHub.
Configurações das equipes no GitHub
Por fim, temos a página de configurações.
Nela, você encontra opções para excluir a equipe, alterar a visibilidade e mudar a associação com outras equipes, como no momento da criação.
Também é possível configurar lembretes agendados por meio da integração com o Slack. Assim, o time recebe avisos periódicos sobre pull requests que aguardam revisão.
Revisão de código
As configurações também trazem opções de notificação para revisão de código.
Com a atribuição automática ativada, o GitHub troca a equipe por membros específicos sempre que alguém pede uma revisão ao time.
Para escolher esses membros, existem dois algoritmos. O round robin alterna entre as pessoas que receberam pedidos há mais tempo.
O load balance, por sua vez, distribui as revisões de forma equilibrada, considerando os pedidos dos últimos 30 dias.
Além disso, você define quantas pessoas revisam cada pull request e pode excluir membros específicos da distribuição.
Esse recurso evita que todos recebam a mesma notificação e ninguém assuma a revisão. Portanto, ele melhora a fluidez do trabalho das equipes no GitHub.
Menções e responsáveis pelo código
Um dos usos mais práticos das equipes no GitHub aparece no dia a dia das issues e dos pull requests.
Ao escrever @organizacao/nome-da-equipe em um comentário, você notifica todos os membros do time de uma só vez. Dessa forma, ninguém precisa lembrar quem faz parte de cada grupo.
Essa menção respeita a configuração de notificações definida na criação da equipe. Se as notificações estiverem desativadas, a citação não gera alertas para os membros.
Além disso, as equipes podem aparecer no arquivo CODEOWNERS de um repositório. Esse arquivo indica quem é responsável por cada pasta ou tipo de arquivo.
Por exemplo, a linha abaixo torna uma equipe responsável por todos os arquivos dentro da pasta src/api:
/src/api/ @my-org/backend-team
Com isso, o GitHub solicita automaticamente a revisão do time sempre que um pull request alterar esses arquivos.
Para que isso funcione, a equipe precisa ter permissão de escrita no repositório. Portanto, vale combinar o CODEOWNERS com os papéis de acesso que vimos anteriormente.
Somado à atribuição automática de revisores, esse recurso transforma as equipes no GitHub em uma peça central do fluxo de revisão de código.
Boas práticas
Comece com uma estrutura simples, que reflita os times reais da empresa. Afinal, hierarquias muito profundas confundem mais do que ajudam.
Prefira conceder acesso aos repositórios sempre por meio de equipes. Dessa forma, a entrada ou a saída de uma pessoa exige apenas uma alteração.
Use equipes secretas somente quando houver um motivo concreto. Caso contrário, deixe o time visível para facilitar menções e colaboração.
Revise periodicamente os papéis de cada equipe nos repositórios. Com isso, você aplica o princípio do menor privilégio e reduz riscos de segurança.
Agora é com você
O objetivo deste artigo foi apresentar o recurso de equipes e as ferramentas fundamentais de cada página.
Use esses recursos em projetos pessoais e explore a usabilidade. Em seguida, analise os resultados para ganhar experiência antes de aplicá-los no trabalho.
Para continuar estudando, veja como fazer deploy de ASP.NET com GitHub Actions e Microsoft Azure e como usar GitHub Packages e GitHub Actions para distribuir contextos delimitados.
Se quiser aprofundar a base, o curso gratuito Fundamentos do Git e Azure DevOps é um bom próximo passo.
FAQ
Preciso de uma organização para criar equipes no GitHub?
Sim. As equipes existem apenas dentro de organizações, e contas pessoais não oferecem esse recurso.
Quem pode criar uma equipe?
Os proprietários da organização sempre podem criar equipes. Eles também podem liberar essa permissão para todos os membros.
Qual a diferença entre equipe visível e secreta?
A equipe visível aparece para toda a organização. Já a secreta fica visível apenas para seus membros e para os proprietários.
Uma equipe filha herda as permissões da equipe pai?
Sim. As equipes filhas herdam as permissões de acesso da equipe pai, mas menções à filha não notificam a pai.
As discussões de equipe ainda existem?
Não. O GitHub aposentou as discussões de equipe e recomenda o uso do GitHub Discussions.