# GitLab: o que é e como trabalhar com ele pelo Git (clone, push, merge request, CI/CD)

URL: https://skillaria.top/pt/guides/git/o-que-e-gitlab

O GitLab é uma plataforma web para guardar repositórios Git e trabalhar em equipe: código, merge requests, tarefas e integração contínua (CI/CD) em um só lugar. Você pode usá-lo na nuvem, em gitlab.com, ou em um servidor próprio da empresa, e o código é enviado e baixado com os comandos habituais do Git: clone, push e pull.

## O que é o GitLab

O GitLab é uma plataforma onde ficam guardados os repositórios Git e se organiza o trabalho em equipe: revisão de código, merge requests (pedidos de mesclagem), tarefas, wiki, registro de contêineres e integração contínua (CI/CD). Em resumo, o GitLab é «um GitHub com pipeline de build próprio e a possibilidade de ser instalado no seu servidor». Muitas empresas, sobretudo na Rússia, guardam o código no GitLab instalado na rede interna.

O projeto começou em 2011 como uma aplicação aberta para hospedar código; em torno dele se formou a empresa GitLab Inc. A plataforma existe em duas versões: a Community Edition, aberta e gratuita para instalar no seu servidor, e a Enterprise Edition, com recursos pagos. No gitlab.com os planos se chamam Free, Premium e Ultimate.

É importante não confundir os conceitos. O Git é o sistema de controle de versões, um programa no seu computador. O GitLab é um serviço que mantém uma cópia remota do repositório e acrescenta uma interface e ferramentas para a equipe. Sem o Git não se trabalha com o GitLab, mas o Git funciona muito bem sem o GitLab.

## Git e GitLab: qual é a diferença

As buscas «git e gitlab o que é» costumam surgir quando, em uma vaga de emprego ou no primeiro dia de trabalho, aparecem as duas palavras. A diferença é a mesma que existe entre um documento e um armazenamento em nuvem: o Git registra as alterações dos arquivos, o histórico de commits e as branches no seu computador. O GitLab recebe esse histórico pela rede e o exibe no navegador.

|  | Git | GitLab |
| --- | --- | --- |

| O que é | Programa de controle de versões | Plataforma web para repositórios e trabalho em equipe |

| Onde funciona | No computador do desenvolvedor | No gitlab.com ou no servidor da empresa |

| Precisa de internet | Não, exceto para push, pull, fetch e clone | Sim, é um serviço de rede |

| Principais recursos | Commits, branches, merges, histórico | Merge request, revisão, tarefas, CI/CD, controle de acesso |

| Como é usado | Linha de comando, IDE, clientes gráficos | Navegador mais os comandos habituais do Git |

Todas as ações com o código — commit, branch, merge — continuam sendo feitas no Git. O GitLab apenas recebe o resultado com `git push` e permite discuti-lo com os colegas.

## GitLab e GitHub: em que se diferenciam

Ambos armazenam repositórios Git e permitem revisão de código, então as habilidades básicas são transferidas sem mudanças. As diferenças estão nas ênfases e no modelo de implantação.

| Critério | GitLab | GitHub |
| --- | --- | --- |

| Pedido de mesclagem | Merge request (MR) | Pull request (PR) |

| CI/CD | GitLab CI/CD integrado, arquivo `.gitlab-ci.yml` | GitHub Actions, arquivos em `.github/workflows/` |

| Instalação própria | Community Edition gratuita no seu servidor | GitHub Enterprise Server, pago |

| Código-fonte da plataforma | Aberto (Community Edition) | Fechado |

| Agrupamento de projetos | Grupos e subgrupos aninhados | Organizações |

| Onde é mais popular | Desenvolvimento corporativo, servidores internos | Open source, projetos públicos, portfólio |

Na prática, muitos desenvolvedores usam os dois: projetos pessoais e portfólio ficam no GitHub, e o código de trabalho, no GitLab corporativo. Os comandos do Git são os mesmos; muda apenas o endereço do repositório remoto.

## gitlab.com ou servidor próprio (self-hosted)

O gitlab.com na nuvem é adequado para projetos pessoais e equipes pequenas: você se cadastra e cria repositórios na hora. Atualizações, cópias de segurança e disponibilidade ficam a cargo do GitLab. Os limites do plano gratuito (número de participantes, minutos de CI, espaço de armazenamento) mudam de tempos em tempos, então consulte as condições atuais na página de preços.

O GitLab self-hosted é instalado pela empresa no próprio servidor: a partir do pacote para Linux, em Docker ou em Kubernetes. O código não sai da rede interna, é possível conectar o login corporativo via LDAP e configurar runners próprios para as builds. Em contrapartida, os administradores cuidam das atualizações e dos backups. Para o desenvolvedor a diferença quase não se nota: o endereço não será `gitlab.com`, e sim algo como `gitlab.empresa.com.br`.

## Configurar o Git para trabalhar com o GitLab

Antes do primeiro commit, informe seu nome e seu e-mail: eles aparecerão no histórico, e o GitLab associará os commits ao seu perfil pelo e-mail:

```
git config --global user.name "Ivan Petrov"
git config --global user.email "ivan@example.com"
```

No Windows é cômodo trabalhar no Git Bash: ele é instalado junto com o Git para Windows e inclui o `ssh-keygen`, então todos os comandos deste artigo funcionam nele sem alterações. Depois é preciso escolher a forma de acesso: HTTPS com token ou chave SSH.

### Acesso por HTTPS: personal access token

Para as operações do Git por HTTPS não se deve usar a senha da conta, e, se a autenticação em dois fatores estiver ativa, ela nem funciona. Em vez disso, crie um personal access token nas configurações do perfil no GitLab (seção Access tokens). Para trabalhar com código, bastam as permissões `read_repository` e `write_repository`; defina uma validade e salve o token imediatamente, porque ele não é exibido novamente.

No primeiro push ou clone, o Git pede usuário e senha: digite seu nome de usuário do GitLab e, no lugar da senha, o token. O gerenciador de credenciais (no Git para Windows ele já vem integrado) vai lembrá-lo, e você não precisará digitá-lo de novo.

### Acesso por chave SSH

O SSH é mais cômodo no dia a dia: você adiciona a chave uma vez e não digita mais nada.

```
ssh-keygen -t ed25519 -C "ivan@example.com"
cat ~/.ssh/id_ed25519.pub
```

O conteúdo do arquivo `.pub` (a chave pública) é colado nas configurações do perfil no GitLab, na seção SSH Keys. Para testar a conexão:

```
ssh -T git@gitlab.com
Welcome to GitLab, @ivan.petrov!
```

## Git clone do GitLab: como clonar um repositório

Na página do projeto há um botão Code com dois endereços, para SSH e para HTTPS. Copie o que precisar e execute `git clone`:

```
# por HTTPS
git clone https://gitlab.com/meu-grupo/meu-projeto.git

# por SSH
git clone git@gitlab.com:meu-grupo/meu-projeto.git
```

No GitLab, o caminho do projeto pode incluir subgrupos, por exemplo `gitlab.com/empresa/backend/api.git`. Isso é normal: copie o endereço completo.

### Git clone do GitLab com token

Em scripts e servidores onde ninguém pode digitar uma senha, o token é passado diretamente no endereço. O usuário pode ser o seu nome de usuário ou o nome de serviço `oauth2`:

```
git clone https://oauth2:SEU_TOKEN@gitlab.com/meu-grupo/meu-projeto.git
```

Atenção: esse endereço fica salvo em `.git/config` e pode acabar no histórico de comandos do shell. Para automação é melhor usar um deploy token ou um project access token com permissões mínimas e validade limitada, e, no CI, a variável integrada `CI_JOB_TOKEN`.

## Git push para o GitLab: enviar o código

Se o projeto já existe localmente, crie um projeto vazio no GitLab (sem README, para não gerar um commit extra) e vincule o repositório remoto:

```
git remote add origin git@gitlab.com:meu-grupo/meu-projeto.git
git branch -M main
git push -u origin main
```

A opção `-u` vincula a branch local à remota; depois disso basta escrever `git push` e `git pull`. O ciclo de trabalho normal não difere de qualquer outro serviço:

```
git switch -c feature/login
git add .
git commit -m "Adiciona formulário de login"
git push -u origin feature/login
git pull
```

As tags são enviadas separadamente: `git push origin v1.2.0`, ou todas de uma vez com `git push --tags`. No GitLab as tags aparecem na seção Tags e muitas vezes disparam um pipeline de publicação de versão.

### Erros comuns no git push para o GitLab

- **HTTP Basic: Access denied**: usuário incorreto ou senha digitada no lugar do token. Crie um token com a permissão `write_repository` e apague a entrada antiga do gerenciador de credenciais.
- **Permission denied (publickey)**: o GitLab não reconhece a chave SSH. Verifique se a chave pública está no perfil e execute `ssh -T git@gitlab.com`.
- **You are not allowed to push code to protected branches**: a branch (normalmente `main`) está protegida. Envie as alterações para a sua branch e abra um merge request.
- **rejected ... (fetch first)**: há commits no servidor que você não tem. Execute `git pull --rebase` e repita o push.
- **remote: Project not found**: erro de digitação no endereço ou falta de acesso ao projeto; peça ao proprietário para confirmar o seu papel.

## Merge request no GitLab

O merge request é o equivalente ao pull request do GitHub: o pedido para mesclar a sua branch na principal. É no MR que os colegas deixam comentários nas linhas de código, são executadas as verificações do CI e se decide a mesclagem. Depois do push de uma branch nova, o GitLab mostra no terminal um link para criar o MR, e na interface web aparece a sugestão de criá-lo.

O MR também pode ser criado pela linha de comando com as opções de push:

```
git push -o merge_request.create -o merge_request.target=main origin feature/login
```

O processo típico é: branch para a tarefa → commits → push → MR → revisão e pipeline verde → merge. Ao mesclar, o GitLab pode combinar os commits em um só (squash) e apagar a branch de origem. Se o MR tiver conflitos, o mais simples é atualizar a branch localmente com `git pull --rebase origin main` ou `git merge main`, resolver os conflitos e fazer push novamente.

Marque o trabalho não concluído como Draft: um MR assim não pode ser mesclado por engano, mas os colegas já veem as alterações e podem comentá-las.

## CI/CD no GitLab: .gitlab-ci.yml

A principal característica do GitLab é o CI/CD integrado. Basta colocar na raiz do repositório um arquivo `.gitlab-ci.yml` para que, a cada push, o GitLab execute um pipeline formado por estágios (stages) e tarefas (jobs). As tarefas são executadas pelos runners: no gitlab.com há runners compartilhados; em um servidor próprio, eles são instalados separadamente.

```
stages:
  - test
  - deploy

test:
  stage: test
  image: python:3.12
  script:
    - pip install -r requirements.txt
    - pytest

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  rules:
    - if: $CI_COMMIT_TAG
```

Aqui os testes rodam a cada push, e a tarefa `deploy` só roda quando uma tag é enviada: `git tag v1.0.0` e `git push origin v1.0.0`. Os resultados do pipeline aparecem diretamente no merge request, e é possível bloquear a mesclagem enquanto as verificações não passarem.

## Como excluir um repositório no GitLab

Os comandos do Git não conseguem excluir um projeto do servidor: o `git push` apenas altera branches e tags. O projeto é removido pela interface web: configurações do projeto, seção General, bloco Advanced, botão de excluir com confirmação do nome. É preciso ser Owner. A cópia local permanece: é apenas uma pasta com `.git`.

Se você quiser desvincular o repositório local do GitLab sem apagar nada no servidor, basta `git remote remove origin`.

## Quando escolher o GitLab

- O código não pode ir para uma nuvem externa: é preciso um servidor próprio.
- É necessário CI/CD pronto para uso, sem serviços de terceiros.
- Você trabalha em uma organização grande com hierarquia de equipes: os subgrupos e os papéis flexíveis são úteis.
- Você vai para uma empresa que já usa GitLab: nesse caso não há escolha, mas as habilidades com o Git se transferem por completo.

Para portfólio e open source, costuma-se escolher o GitHub, pela comunidade maior e pela visibilidade dos projetos. Nada impede manter um projeto nos dois serviços ao mesmo tempo: um repositório pode ter vários remotes.

## Resumo

O GitLab é uma plataforma para repositórios Git com revisão por merge requests, tarefas e CI/CD integrado, disponível tanto na nuvem quanto em servidor próprio. Trabalhar com ele se resume a comandos conhecidos: configure o acesso com token ou chave SSH e depois clone, commit, push e merge request. Repositórios remotos e fluxos de trabalho em equipe são explicados com prática no curso de Git.

## FAQ

**O GitLab é gratuito?**

A Community Edition para instalar no seu servidor é gratuita; no gitlab.com existe o plano Free, com limitações. Os recursos avançados ficam nos planos pagos Premium e Ultimate.

**Dá para migrar um projeto do GitHub para o GitLab?**

Sim: o GitLab permite importar projetos do GitHub, e o histórico também pode ser transferido manualmente com git clone --mirror do endereço antigo e git push --mirror para o novo.

**É preciso aprender comandos específicos do GitLab?**

Não; o código é gerenciado com os comandos normais do Git. O GitLab acrescenta a interface web, e para automação existem o utilitário de linha de comando glab e a API.

**Em que o GitLab Flow difere do Git Flow?**

O GitLab Flow é mais simples: o trabalho é feito em branches de funcionalidade com merge requests para a main, e, se necessário, são criadas branches próprias para ambientes e versões, sem as branches develop e hotfix do Git Flow.


---
Source: Skillaria.Top (https://skillaria.top)