Dev Wiki | Johnny Salazar Reidel

Guia completo: configurando um ambiente de desenvolvimento colaborativo com deploy automatizado

Detalhes
Escrito por Johnny Salazar Reidel
Categoria: CI / DI, Code Review e automações com IA

Este documento é um tutorial passo a passo que demonstra como configurar um fluxo de trabalho de desenvolvimento completo e profissional para um projeto web. Utilizaremos como exemplo um projeto fictício chamado "[NOME_DO_PROJETO]", um sistema web genérico (ex: um blog, um portal de notícias ou um LMS).

O objetivo é criar uma estrutura robusta no GitHub que permita a colaboração de múltiplos desenvolvedores (divididos em equipes), mantendo o controle de versão e automatizando completamente o processo de publicação (deploy) para um servidor de produção, neste caso, um servidor (como uma hospedagem compartilhada) que ofereça acesso SSH.

O que vamos configurar:

  • Uma Organização no GitHub para centralizar o projeto.

  • Um Repositório Git com uma estrutura de branches (main, dev, grupo1, grupo2) para organizar o desenvolvimento.

  • Permissões de acesso granulares usando Times (Teams) para garantir que cada equipe só possa alterar sua respectiva branch.

  • Um pipeline de Integração Contínua e Entrega Contínua (CI/CD) usando GitHub Actions que, ao detectar uma atualização na branch main, envia automaticamente os arquivos para o servidor de produção via SSH e rsync.

Passo 1: Criação da Organização e do Repositório no GitHub

A base de um bom projeto colaborativo é uma estrutura organizacional clara. Para evitar que o repositório fique atrelado ao perfil pessoal de um único desenvolvedor e para gerenciar melhor as permissões, a prática ideal é criar uma "Organização" no GitHub para ser a "dona" do projeto.

  1. Criar uma Organização no GitHub (Novo Dono):

    • Acesse sua conta no GitHub.

    • Clique na sua foto de perfil no canto superior direito e selecione "Your organizations".

    • Clique no botão "New organization".

    • Escolha o plano "Free".

    • Defina um nome para a organização (ex: [NOME_DO_PROJETO]-Org ou algo relacionado ao projeto). Este nome será o "dono" do repositório.

    • Preencha as informações solicitadas. Você pode pular o passo de adicionar membros por enquanto.

  2. Criar o Repositório dentro da Organização:

    • Após criar a organização, você será direcionado para o painel dela. Clique em "New" para criar um novo repositório.

    • Nome do repositório: [nome-do-projeto]

    • Descrição: (Opcional) Ex: "Código-fonte do [NOME_DO_PROJETO]."

    • Selecione "Private" se o código não for aberto.

    • Marque a opção "Add a README file" para já iniciar o repositório com um arquivo.

    • Clique em "Create repository".

  3. Clonar o Repositório:

    • Copie a URL SSH do seu novo repositório (a URL agora incluirá o nome da organização, ex: Este endereço de email está sendo protegido de spambots. Você precisa do JavaScript ativado para vê-lo.:NomeDaOrganizacao/[nome-do-projeto].git).

    • No seu terminal, navegue até a pasta onde guarda seus projetos e execute:

      git clone <URL_DO_SEU_REPOSITORIO>
cd [nome-do-projeto]

  4. Criar as Branches de Trabalho:

    • O repositório foi criado com a branch main. Vamos criar as outras:

      • Acesse o repositório na página da sua organização no GitHub.

      • Clique no botão de branches, que mostra "main".

      • No campo "Find or create a branch...", digite dev e clique em "Create branch: dev from 'main'".

      • Repita o processo para grupo1 e grupo2.

Passo 2: Sincronizando e Populando o Repositório

Agora que o repositório está estruturado, vamos adicionar os arquivos do projeto e garantir que todas as branches de desenvolvimento comecem com a mesma base de código.

  1. Buscar as Novas Branches:

    • Dentro da pasta [nome-do-projeto] no seu terminal, execute o comando abaixo para buscar todas as branches que você criou no GitHub:

      git pull --all

  2. Adicionar os Arquivos do Projeto:

    • Copie todos os arquivos e pastas do seu projeto diretamente para a raiz da pasta [nome-do-projeto] que você clonou no seu computador.

  3. Commitar e Enviar os Arquivos Iniciais:

    • Vamos commitar os arquivos na sua branch de desenvolvimento principal, a dev.

      # Mude para a branch dev
git checkout dev

# Adicione todos os novos arquivos para o commit
git add .

# Crie o commit
git commit -m "Commit inicial dos arquivos do projeto"

# Envie o commit para o repositório no GitHub
git push origin dev

  4. Atualizar as Branches dos Grupos:

    • Para que os grupos comecem a trabalhar com a base de código mais recente, vamos fazer o merge das alterações da dev para as branches grupo1 e grupo2.

      # Mude para a branch grupo1 e atualize
git checkout grupo1
git merge dev
git push origin grupo1

# Mude para a branch grupo2 e atualize
git checkout grupo2
git merge dev
git push origin grupo2

# Volte para a sua branch principal de desenvolvimento
git checkout dev

Passo 3: Preparando o Acesso ao Servidor (Chave SSH)

Para que o GitHub Actions possa se conectar ao seu servidor de produção e enviar os arquivos, ele precisa de uma forma segura de autenticação. Usaremos um par de chaves SSH (pública e privada) exclusivamente para este propósito.

  1. Gerar um Novo Par de Chaves SSH:

    • No terminal do seu computador (Mac/Linux), execute o comando abaixo.

      ssh-keygen -t rsa -b 4096 -C "actions@github" -f ~/.ssh/github_actions_key

    • Explicação do comando:

      • -t rsa -b 4096: Cria uma chave RSA de 4096 bits (muito segura).

      • -C "actions@github": Adiciona um comentário à chave para identificá-la.

      • -f ~/.ssh/github_actions_key: Salva a chave com o nome github_actions_key para não sobrescrever sua chave pessoal (id_rsa).

    • O terminal pedirá uma "passphrase" (senha). Pressione Enter duas vezes para deixar em branco. Isso é crucial, pois o script de deploy automatizado não terá como digitar uma senha.

  2. Autorizar a Chave no Servidor de Produção:

    • Agora, precisamos dizer ao servidor que ele deve confiar nesta nova chave.

    • Primeiro, copie o conteúdo da sua chave pública (o arquivo com final .pub):

      cat ~/.ssh/github_actions_key.pub

    • Selecione e copie toda a linha de saída, que começa com ssh-rsa ....

    • Conecte-se ao seu servidor de produção via SSH.

    • Uma vez conectado, edite (ou crie) o arquivo authorized_keys:

      nano ~/.ssh/authorized_keys

    • Cole a chave pública que você copiou em uma nova linha no final deste arquivo.

    • Salve o arquivo (pressione Ctrl + X, depois Y e Enter).

    • Importante: Garanta que as permissões dos arquivos estão corretas no servidor. Execute:

      chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

Passo 4: Configuração do CI/CD com GitHub Actions

Agora, vamos criar o pipeline que automatiza o deploy.

  1. Adicionar Segredos (Secrets) no GitHub:

    • Atenção: Este passo deve ser feito dentro das configurações do repositório, e não da Organização.

    • Navegue até seu repositório, clique em "Settings" > "Secrets and variables" > "Actions". Na seção "Repository secrets", clique em "New repository secret" e adicione:

      • PROD_SERVER_HOST: O endereço do seu servidor de produção (ex: seudominio.com ou o IP).

      • PROD_SERVER_USERNAME: Seu nome de usuário de acesso SSH.

      • PROD_SERVER_PRIVATE_KEY: A chave SSH privada que você gerou no passo anterior.

        • Como obter a chave: No seu terminal, execute o comando cat ~/.ssh/github_actions_key. Copie todo o conteúdo, desde -----BEGIN ... até -----END ..., e cole neste campo.

      • PROD_SERVER_PORT: A porta SSH do seu servidor (geralmente 22 ou 2222).

      • PROD_SERVER_DESTINATION_PATH: O caminho completo no servidor onde os arquivos devem ser enviados (ex: public_html/[nome-do-projeto]).

  2. Criar o Arquivo de Workflow:

    • Na raiz do seu projeto local, crie a seguinte estrutura de pastas: .github/workflows/.

    • Dentro de workflows, crie um arquivo chamado deploy.yml.

    • Cole o seguinte código no arquivo:

      # .github/workflows/deploy.yml
name: Deploy to Production Server

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout do código do repositório
        uses: actions/checkout@v4

      - name: Configura o ambiente SSH
        run: |
          mkdir -p ~/.ssh/
          echo "${{ secrets.PROD_SERVER_PRIVATE_KEY }}" > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key
          cat << EOF > ~/.ssh/config
          Host production_server
            HostName ${{ secrets.PROD_SERVER_HOST }}
            User ${{ secrets.PROD_SERVER_USERNAME }}
            Port ${{ secrets.PROD_SERVER_PORT }}
            IdentityFile ~/.ssh/deploy_key
            IdentitiesOnly yes
            StrictHostKeyChecking no
            PreferredAuthentications publickey
          EOF

      - name: Deploy com rsync
        run: |
          # Nota: A lista --exclude abaixo é um exemplo para projetos baseados
          # em CMS. Ajuste conforme as necessidades do seu projeto.
          rsync -avz --delete \
            --exclude='/.git/' \
            --exclude='/.github/' \
            --exclude='/_dumps/' \
            --exclude='/node_modules/' \
            --exclude='/cache/' \
            --exclude='/administrator/cache/' \
            --exclude='/administrator/logs/' \
            --exclude='/tmp/' \
            --exclude='/.vscode/' \
            --exclude='/configuration.php' \
            --exclude='/configuration.php - example' \
            --exclude='/.htaccess' \
            --exclude='/.htaccess.admintools' \
            --exclude='/.htaccess - example' \
            --exclude='/composer.json' \
            --exclude='/composer.lock' \
            --exclude='/package-lock.json' \
            --exclude='/package.json' \
            --exclude='/.gitignore' \
            --exclude='.DS_Store' \
            ./ production_server:${{ secrets.PROD_SERVER_DESTINATION_PATH }}

Passo 5: Gerenciamento de Acesso com Times e Regras de Proteção

 

Esta é a forma mais eficiente de gerenciar as permissões dos grupos.

  1. Criar os Times:

    • Na página principal da sua Organização no GitHub, clique na aba "Teams".

    • Clique em "New team".

    • Nome do Time: Grupo 1. Crie e, na tela seguinte, associe o repositório [nome-do-projeto] com permissão de Write.

    • Repita o processo para criar o time Grupo 2.

  2. Configurar Regras de Proteção de Branch:

    • Vá para as configurações do seu repositório ("Settings" > "Branches").

    • Para a branch main (Produção):

      • Clique em "Add branch protection rule".

      • Em "Ruleset Name", digite Regras Main.

      • Em "Target branches", clique em "Add target" > "Include by pattern" e digite main.

      • Marque "Require a pull request before merging" e defina "Required approvals" como 1.

    • Para a branch grupo1:

      • Clique em "Add branch protection rule".

      • Em "Ruleset Name", digite Regras Grupo 1.

      • Na seção "Bypass list" (no início), adicione você (administrador) e o time @NomeDaSuaOrganizacao/grupo-1.

      • Em "Target branches", clique em "Add target" > "Include by pattern" e digite grupo1.

      • Marque a opção "Restrict updates".

    • Para a branch grupo2:

      • Crie uma regra similar à do grupo1, mas para a branch grupo2 e adicionando o time grupo-2 na "Bypass list".

  3. Convidar e Gerenciar Pessoas:

    • Convide os membros para a Organização ("People" > "Invite member").

    • Assim que aceitarem, vá para a aba "Teams", clique no time correspondente, vá para "Members" e adicione a pessoa.

 

Passo 6: Resumo do Fluxo de Trabalho para os Grupos

 

  1. Desenvolvimento:

    • Cada grupo trabalha em sua respectiva branch (grupo1 ou grupo2).

    • Eles fazem commits e push para suas branches.

  2. Integração e Revisão:

    • Quando uma funcionalidade está pronta, o grupo abre um Pull Request (PR) da sua branch para a main.

    • O líder do projeto revisa, aprova e faz o merge.

  3. Deploy Automático:

    • Ao fazer o merge para a main, o GitHub Actions é acionado e envia os arquivos para o servidor de produção.

    • O site em produção é atualizado automaticamente.

Categorias