GitHub - Trabalhando com projetos, equipes e organizações
As organizações no GitHub são o ponto de partida para quem quer gerenciar projetos, controlar o acesso de equipes e acompanhar a participação de cada pessoa em um mesmo lugar. Neste artigo, você vai entender como esses três recursos se conectam e como criar a sua primeira estrutura de trabalho em equipe.
Muito além do versionamento de código
O GitHub oferece diversas ferramentas além do versionamento de código. Por isso, muitos times usam a plataforma também para planejar tarefas, distribuir responsabilidades e controlar quem acessa cada repositório.
Este conteúdo é o primeiro de uma série que apresenta os conceitos fundamentais desses recursos. Portanto, o objetivo principal é mostrar que eles existem e como cada um funciona, sem aprofundar em cenários avançados.
Ao longo do texto, você vai conhecer três pilares: os projetos, as organizações e as equipes. Além disso, vai ver como eles se combinam para formar um ambiente de colaboração organizado.
Se você ainda não configurou o Git na sua máquina, vale começar pelo artigo Git e GitHub: instalação, configuração e primeiros passos. Assim, você chega aqui com o básico de commits e repositórios já resolvido.
Projetos no GitHub
No contexto de projetos, o GitHub historicamente ofereceu dois recursos. O primeiro foi o quadro de projetos clássico, conhecido como Projects (classic).
Esse quadro segue o modelo Kanban, um sistema de gerenciamento de tarefas e fluxo de trabalho. Nele, as colunas definem as etapas, os cartões representam as tarefas e as cores trazem informações adicionais, como prioridade ou complexidade.
O segundo recurso é, na verdade, uma versão evoluída do primeiro. Ele traz diferentes tipos de visualização, paleta de comandos, automação de tarefas de gerenciamento e várias outras ferramentas.
Hoje, esse segundo recurso se chama simplesmente GitHub Projects. De acordo com o anúncio oficial do GitHub, o Projects (classic) foi descontinuado no GitHub.com em 23 de agosto de 2024, e a plataforma migrou automaticamente os quadros clássicos restantes para o novo formato.
Os três tipos de quadros de projeto
Na época em que os dois formatos conviviam, existiam três tipos de quadros de projeto no GitHub. Entender essa divisão ajuda a decidir onde cada quadro deve morar.
- Projetos do usuário, que ficam no seu perfil ou no menu de contexto superior direito, ao clicar na sua foto.
- Quadros da organização, que ficam no perfil da organização.
- Repositórios com quadro próprio, ou seja, projetos do repositório, que ficam dentro do próprio repositório.
A imagem abaixo mostra onde acessar os projetos a partir do perfil do usuário.
Os projetos do usuário podem conter tarefas, ações e problemas de qualquer repositório desse usuário. Dessa forma, você consegue acompanhar trabalhos pessoais espalhados por vários repositórios em um único quadro.
Já os projetos de organizações no GitHub ficam no perfil da própria organização, como mostra a próxima imagem.
Assim como os projetos do usuário, os projetos da organização podem reunir tarefas, ações e problemas de qualquer repositório ou equipe da organização.
Por fim, os projetos de repositório ficavam dentro do próprio repositório.
Os projetos de repositório têm como objetivo conter e organizar apenas as tarefas, ações e problemas do repositório ao qual pertencem. No modelo atual, os projetos pertencem a um usuário ou a uma organização, e você vincula esses projetos aos repositórios que quiser.
O que o GitHub Projects oferece hoje
A documentação do GitHub Projects descreve a ferramenta como um recurso adaptável para planejar e acompanhar o trabalho. Na prática, ele combina issues e pull requests em uma visão única.
Primeiro, você escolhe entre três layouts: tabela, quadro Kanban e roadmap em formato de linha do tempo. Além disso, pode criar várias visualizações com filtros, ordenação e agrupamentos diferentes.
Em seguida, você pode adicionar campos personalizados, até um limite de 50 por projeto. Por exemplo, um campo de data para a entrega, um número para a complexidade, uma seleção única para a prioridade e um campo de iteração para o planejamento semanal.
As automações também fazem parte do pacote. Os fluxos de trabalho nativos atualizam campos quando um item muda, enquanto a API GraphQL e o GitHub Actions permitem automações mais elaboradas.
Por outro lado, o recurso de insights gera gráficos a partir dos dados do projeto. Com isso, todos que têm acesso ao quadro conseguem acompanhar o andamento sem montar planilhas paralelas.
O que são organizações no GitHub
As organizações no GitHub são perfis compartilhados que representam, por exemplo, uma empresa, uma comunidade ou um projeto de código aberto. Cada pessoa continua com a própria conta pessoal, mas várias contas podem participar da mesma organização.
Uma organização pode ter múltiplos administradores, equipes, projetos, repositórios e pacotes. Além disso, o recurso oferece gestão de acesso dos colaboradores aos projetos e repositórios.
Segundo a documentação sobre organizações, elas funcionam como contas compartilhadas com recursos sofisticados de segurança e administração. Ou seja, o foco está em colaboração em escala, e não em trabalho individual.
Planos disponíveis para organizações no GitHub
Você pode criar organizações no GitHub gratuitamente, com o plano GitHub Free. Nesse caso, alguns recursos para repositórios privados ficam limitados.
Por outro lado, os planos GitHub Team e GitHub Enterprise Cloud liberam o conjunto completo de recursos. O Enterprise Cloud, por exemplo, inclui login único com SAML.
Antes de decidir, compare os planos na página de preços. Como os recursos de cada plano mudam com o tempo, a comparação oficial é sempre a referência mais confiável.
Papéis nas organizações no GitHub
Toda organização trabalha com papéis, e cada papel define o que a pessoa pode fazer. A página de papéis em uma organização lista os principais:
- Owners: têm acesso administrativo completo à organização.
- Members: formam o papel padrão, sem poderes administrativos.
- Moderators: bloqueiam colaboradores externos, definem limites de interação e ocultam comentários em repositórios públicos.
- Billing managers: gerenciam as configurações de cobrança.
- Security managers: acompanham alertas e configurações de segurança, com leitura em todos os repositórios.
- Outside collaborators: acessam repositórios específicos sem fazer parte da organização, como prestadores de serviço.
A própria documentação recomenda manter pelo menos dois owners. Assim, a organização não fica travada se uma única pessoa perder o acesso à conta.
Como criar organizações no GitHub
O caminho para criar organizações no GitHub começa no seu perfil. Primeiro, entre na página de organizações, como mostra a imagem abaixo.
Na versão atual da interface, você clica na sua foto no canto superior direito, entra em Settings e escolhe Organizations na seção Access da barra lateral. Em seguida, clique no botão New organization.
Depois disso, aparece uma tela de planos. Nessa etapa, você compara os planos e os recursos de cada um antes de decidir, e neste exemplo usamos o plano gratuito.
Logo em seguida, surge um formulário que pede o nome da organização, um e-mail de contato e a quem a organização pertence. Por exemplo, você indica se ela representa a sua conta pessoal ou uma empresa.
Convites e configuração inicial
Após o formulário, o GitHub abre uma janela para você convidar usuários a entrar na organização. Na tela seguinte, ele pergunta quantas pessoas você espera reunir e qual o objetivo da organização.
Essas duas telas não aparecem nas imagens deste artigo, mas o fluxo é direto. Além disso, você pode pular os convites e enviá-los depois, pela aba People.
Concluído o assistente, a organização já está pronta.
Como a imagem mostra, a página traz opções para gerenciar repositórios, pacotes, pessoas, equipes, projetos e as configurações da própria organização. Então, o próximo passo natural é criar uma equipe.
Primeiras configurações recomendadas
Antes de convidar muita gente, vale revisar as configurações de segurança. Por exemplo, as organizações no GitHub podem exigir autenticação em dois fatores de todos os membros.
Além disso, os owners têm acesso ao log de auditoria, que registra as ações relevantes dentro da organização. Com isso, fica mais fácil investigar uma mudança inesperada de permissão.
Também é possível restringir quais tipos de repositório os membros podem criar. Dessa forma, você evita repositórios públicos criados por engano com código interno.
Equipes nas organizações no GitHub
As equipes existem dentro das organizações no GitHub e servem para agrupar pessoas. Esse gerenciamento envolve criar equipes, adicionar e remover pessoas, definir níveis de acesso por equipe e acompanhar a atividade dos membros.
De acordo com a documentação sobre equipes, apenas membros da organização podem fazer parte de uma equipe. Ou seja, colaboradores externos ficam de fora e recebem acesso direto aos repositórios.
Criando uma equipe
Para criar uma equipe, acesse a aba Teams da organização e clique em New team. Em seguida, você verá o formulário abaixo.
Ao preencher os dados, a equipe passa a existir e o GitHub leva você para uma página onde pode adicionar pessoas ou editar permissões. Depois, ao voltar ao perfil da organização, você tem uma visão rápida das equipes e dos seus membros.
Visibilidade e equipes aninhadas
Uma equipe pode ser visível ou secreta. As visíveis aparecem para todos os membros e podem receber menções, enquanto as secretas ficam restritas aos próprios membros e aos owners.
Além disso, você pode montar equipes aninhadas para refletir a hierarquia da empresa. Nesse caso, a equipe filha herda as permissões da equipe pai.
Por exemplo, uma equipe Engineering pode ter as filhas Backend e Frontend. Assim, quando alguém menciona a equipe pai, os membros das filhas também recebem a notificação.
Equipes secretas, porém, não podem ser aninhadas. Portanto, defina a visibilidade antes de planejar a hierarquia.
Permissões por equipe nas organizações no GitHub
Os owners e os maintainers de cada equipe concedem acesso aos repositórios da organização. Em vez de liberar repositório por repositório para cada pessoa, você libera para a equipe inteira.
Os níveis de acesso a repositórios em organizações no GitHub vão de leitura até administração: read, triage, write, maintain e admin. Dessa forma, um time de QA pode ter triage, enquanto o time de desenvolvimento recebe write.
As equipes também facilitam a revisão de código. Por exemplo, você pode pedir revisão para uma equipe inteira ou apontá-la como dona de uma parte do código no arquivo CODEOWNERS:
# Toda alteração na pasta de API exige revisão da equipe de backend
/src/api/ @my-company/backend
# Arquivos de infraestrutura ficam com a equipe de plataforma
*.tf @my-company/platform
Com essa configuração, o GitHub solicita a revisão da equipe certa sempre que um pull request toca nesses arquivos. Assim, ninguém precisa lembrar quem deve revisar cada parte.
Acompanhando a participação dos membros
Com as equipes montadas, fica mais simples acompanhar o desempenho e a participação de cada pessoa. A aba Insights dos repositórios mostra contribuidores, commits e atividade de pull requests ao longo do tempo.
Por outro lado, os gráficos do GitHub Projects mostram quantos itens cada responsável concluiu em uma iteração. Juntos, esses dois recursos dão uma visão bem completa do andamento do time.
Use esses números com cuidado, porém. Commits e cartões fechados indicam atividade, mas não medem sozinhos a qualidade do trabalho.
Como projetos, equipes e organizações no GitHub se conectam
Os três recursos funcionam melhor quando você os usa juntos. A organização serve de contêiner, as equipes definem quem acessa o quê e os projetos mostram o que precisa ser feito.
Na prática, um fluxo comum segue esta ordem:
- Criar a organização e configurar a segurança básica.
- Convidar os membros e distribuí-los em equipes.
- Conceder às equipes acesso aos repositórios.
- Criar um projeto da organização e vincular os repositórios.
- Definir campos, visualizações e automações do projeto.
Com essa base, as organizações no GitHub viram um ambiente completo de colaboração. Além disso, a estrutura cresce junto com o time, sem exigir uma reorganização a cada nova contratação.
Quando o time evoluir para automações de deploy, os mesmos repositórios da organização podem rodar pipelines. Para ver um exemplo, leia ASP.NET deploy com GitHub Actions e Microsoft Azure.
Boas práticas para organizações no GitHub
Algumas decisões simples evitam dor de cabeça quando a organização cresce. Primeiro, mantenha poucos owners, mas nunca apenas um.
Em seguida, prefira conceder acesso por equipe, e não por pessoa. Dessa forma, quando alguém muda de time, basta trocá-lo de equipe para atualizar todas as permissões.
Também vale seguir o princípio do menor privilégio. Ou seja, comece com leitura e aumente o nível de acesso apenas quando houver necessidade real.
Por fim, documente a estrutura de equipes no README da organização ou em um repositório interno. Assim, quem chega ao time entende rapidamente quem é responsável por cada área.
Próximos passos
Nas próximas partes desta série, vamos explorar melhor as ferramentas e suas propriedades, simulando o uso real em um ambiente de trabalho em equipe. Enquanto isso, você pode aprofundar cada tema nos artigos gestão de organizações com GitHub, gestão de equipes com GitHub e gestão de projetos com GitHub.
Se você trabalha com pacotes compartilhados entre repositórios, o artigo GitHub Packages e GitHub Actions: distribuindo contextos delimitados mostra outra forma de aproveitar a organização. Além disso, o curso gratuito Fundamentos do Git e Azure DevOps ajuda a consolidar a base de controle de versão.
Conclusão
As organizações no GitHub transformam a plataforma em um ambiente de gestão, e não apenas em um lugar para guardar código. Com elas, você centraliza repositórios, pessoas e regras de acesso.
As equipes, por sua vez, simplificam as permissões e as revisões de código. Já o GitHub Projects dá visibilidade ao trabalho, com quadros, tabelas, roadmaps e automações.
Portanto, comece pequeno: crie a organização, monte uma equipe e abra um projeto. Depois, ajuste a estrutura conforme o time cresce.
FAQ
Criar uma organização no GitHub é gratuito?
Sim, o plano GitHub Free permite criar organizações sem custo. Os planos pagos liberam recursos extras, principalmente para repositórios privados e segurança.
O Projects (classic) ainda funciona?
Não no GitHub.com, porque ele foi descontinuado em 23 de agosto de 2024. Os quadros clássicos restantes foram migrados para o novo GitHub Projects.
Um colaborador externo pode participar de uma equipe?
Não, equipes aceitam apenas membros da organização. O colaborador externo recebe acesso direto aos repositórios necessários.
Qual a diferença entre equipe visível e equipe secreta?
A equipe visível aparece para todos os membros e pode receber menções. A secreta fica restrita aos seus membros e aos owners, e não pode ser aninhada.
Quantos owners uma organização deve ter?
Segundo a documentação do GitHub, o ideal é ter pelo menos dois. Assim, a organização continua administrável se um owner perder o acesso.