Pular para o conteúdo principal
O GitLab unifica issues, code review, CI e CD em uma única interface. Conectar o AppSignal ao GitLab cobre o mesmo terreno que a integração com o GitHub: O GitLab é uma integração pessoal: cada usuário que quiser usá-la precisa concluir a configuração por conta própria em cada app do AppSignal.
O GitLab oferece várias formas de se conectar a ferramentas de terceiros. O AppSignal se conecta usando um personal access token do GitLab e a URL do seu projeto, o que é suportado no GitLab.com, no GitLab Self-Managed e no GitLab Dedicated. O GitLab também oferece aplicações OAuth, mas o AppSignal ainda não suporta a conexão ao GitLab via OAuth.
Site: https://gitlab.com

Passo 1. Crie um personal access token do GitLab

  1. Faça login no GitLab e vá para suas Settings de usuário.
  2. Na barra lateral esquerda, selecione Access tokens e, em seguida, abra Personal access tokens (https://gitlab.com/-/user_settings/personal_access_tokens no GitLab.com).
  3. Selecione Add new token. O GitLab permite criar um personal access token fine-grained ou legacy. Escolha legacy, porque seus escopos correspondem diretamente ao que o AppSignal precisa.
  4. Preencha:
    • Token name: AppSignal
    • Expiration date: escolha uma data que esteja de acordo com a política da sua organização.
    • Scopes: selecione read_api, read_repository e api. O AppSignal precisa dos três.
  5. Selecione Create personal access token e copie o token imediatamente. O GitLab mostra apenas uma vez.
Criar uma issue é uma ação de escrita, então os escopos somente leitura não são suficientes por si só. No GitLab 15.5 e posteriores, o AppSignal não salva um token sem o escopo api. Ele mostra um erro pedindo um token que tenha esse escopo. Versões anteriores do GitLab não informam os escopos de um token, então o AppSignal não consegue verificá-los.O GitLab não permite alterar os escopos de um token depois que ele é criado. Para ajustá-los, crie um novo token e atualize a integração no AppSignal.
Tokens fine-grained também podem funcionar, mas suas permissões de recursos são bem mais granulares, e não é óbvio qual combinação selecionar. Estamos planejando migrar esta integração para as aplicações OAuth do GitLab, a forma mais recente de conectar ferramentas de terceiros ao GitLab.

Passo 2. Adicione a integração no AppSignal

  1. No AppSignal, abra o app que você deseja conectar.
  2. Vá para App settings → Integrations. Em Personal issue tracker integrations, selecione Configure ao lado de GitLab.
  3. Preencha o formulário:
    • Token: cole o personal access token que você criou no Passo 1. A dica do campo informa o escopo de que o AppSignal precisa.
    • GitLab URL: a URL completa do projeto GitLab, por exemplo https://gitlab.com/your-namespace/your-project. Para GitLab Self-Managed, use o hostname da sua instância, por exemplo https://gitlab.example.com/your-group/your-project.
  4. Selecione Create integration.
Você pode retornar a esta página a qualquer momento para Update integration ou Remove integration. Quando novos recursos do GitLab precisam de mais permissões, o AppSignal mostra um banner pedindo que você atualize seu token do GitLab. Selecione Update GitLab token e salve um token com os escopos do Passo 1.

Passo 3. Repita para cada usuário

Como esta é uma integração pessoal, cada colega de equipe que quiser que os links de fonte, os links de backtrace ou a criação de issues funcionem em sua própria conta AppSignal precisa repetir os Passos 1 e 2 com seu próprio token do GitLab. O código muda o tempo todo, então um backtrace é mais útil quando aponta para a revisão que estava implantada no momento em que o erro aconteceu. Conectar o GitLab preenche a Repo URL do seu app, então você não precisa configurá-la manualmente. Você pode confirmar isso em App settings → General, onde o campo contém a URL do seu projeto GitLab. O AppSignal detecta o provedor a partir dessa URL e monta os links de backtrace e comparação correspondentes. Assim que os marcadores de deploy reportarem a revision implantada, o AppSignal vincula cada linha de backtrace à revisão, ao caminho e à linha correspondentes no seu repositório GitLab, para que você possa ir de um erro até o código que foi implantado. Para a configuração completa, veja a documentação de links de backtrace.

Criar issues do GitLab para incidentes

O AppSignal não cria issues do GitLab automaticamente, para evitar sobrecarga de stories. Para criar uma para um incidente de erro:
  1. Abra a tela de detalhes do incidente de erro.
  2. No painel Actions, selecione Send to GitLab.
O AppSignal cria a issue no projeto GitLab vinculado, e você pode abri-la a partir da página do incidente depois. Criar issues exige um token com o escopo api além dos escopos de leitura, descritos no Passo 1.

Acompanhar issues vinculadas a partir do incidente

Este recurso está em beta, como parte do AppSignal Labs. Peça ao suporte para ativá-lo na sua organização.
O painel Actions mostra um botão para cada issue do GitLab vinculada, com o rótulo View #123 in GitLab. Cada botão mostra o status da issue como um badge:
  • Premium e Ultimate: o status como o GitLab o nomeia, como To do ou um status personalizado como In review.
  • Free: Open ou Closed.
O painel Actions de um incidente no AppSignal com um botão View #2 in GitLab e um badge de status In progress O AppSignal atualiza o badge sempre que a issue muda no GitLab. As mudanças de status também aparecem no logbook do incidente. Por exemplo: Changed the status of #123 on GitLab from To do → In review. A entrada mostra quem fez a mudança no GitLab. Algumas limitações que vale a pena conhecer:
  • Uma nova issue recebe seu badge pouco depois de você enviá-la ao GitLab, assim que o GitLab informa o AppSignal sobre ela.
  • Issues enviadas ao GitLab antes deste recurso não mostram badge até a próxima mudança delas no GitLab.
  • O logbook não mostra o primeiro status de uma issue, porque não há um status anterior para comparar.
  • Os badges funcionam para um projeto GitLab por app. Se você e seus colegas de equipe conectarem projetos diferentes, apenas as issues do projeto salvo por último mostram um badge.

Ativar as atualizações de status

O GitLab envia as mudanças de status ao AppSignal por meio de um webhook no seu projeto GitLab. O AppSignal o adiciona quando você salva a integração:
  1. Vá para App settings → Integrations e selecione Configure ao lado de GitLab.
  2. Selecione Update integration. Se a integração for nova, selecione Create integration.
Você precisa da função Maintainer ou Owner no projeto GitLab. Sem ela, a integração ainda é salva. O AppSignal então mostra: “Two-way sync is off: AppSignal couldn’t add a webhook to this GitLab project.” Peça a um Maintainer para salvar a integração, ou obtenha a função e salve-a novamente. Para vincular uma issue do GitLab que já existe, abra a aba Summary do incidente. Escreva uma nota na caixa Logbook com a URL da issue, como https://gitlab.com/your-namespace/your-project/-/issues/42, e selecione Post note. O logbook registra Linked #42 on GitLab, e a issue aparece no painel Actions. O badge de status dela aparece assim que a issue mudar novamente no GitLab. Um comentário sozinho não conta. O servidor MCP do AppSignal vincula issues da mesma forma quando um agente de IA escreve uma nota em um incidente. O AppSignal vincula uma issue apenas quando todas as condições a seguir são verdadeiras. Caso contrário, ele ignora a URL, e a nota é publicada mesmo assim.
  • Você mesmo adicionou a integração do GitLab ao app. O AppSignal busca a issue com o seu token.
  • A issue está no projeto GitLab que você conectou ao app, e o seu token consegue lê-la.
  • A nota tem a URL completa da issue, com /-/issues/ ou /-/work_items/. Referências como #42 ou your-group/your-project#42 não são vinculadas, nem URLs de merge requests.
  • A issue ainda não está vinculada ao incidente. Editar a nota não cria duplicatas.

Trocar de projeto ou remover a integração

  • Trocar para outro projeto GitLab: salve a integração com a URL do novo projeto. O AppSignal move o webhook para o novo projeto. Você precisa da função Maintainer ou Owner no novo projeto.
  • Remover a integração: o AppSignal mantém o webhook enquanto outra pessoa no app ainda usa a integração. Ele remove o webhook quando a última pessoa a remove.

Marcadores de deploy do GitLab CI/CD

Para reportar deploys ao AppSignal a partir de um pipeline do GitLab CI/CD, veja a documentação de marcadores de deploy para a abordagem recomendada da opção de configuração revision, ou o exemplo da Markers API se sua stack não incluir uma integração do AppSignal.

Solução de problemas

O AppSignal diz que o token não tem o escopo api. O AppSignal precisa de api para criar issues. O GitLab não permite editar os escopos de um token. Crie um novo token legacy com read_api, read_repository e api, e salve-o no AppSignal. O envio de um incidente para o GitLab falha. O token pode não ter o escopo api. O AppSignal não consegue verificar isso para tokens salvos antes de começar a verificar escopos, nem no GitLab anterior à versão 15.5. Crie um novo token com os três escopos e atualize a integração no AppSignal. Issues vinculadas não mostram badge de status. Confirme que o projeto GitLab tem o webhook do AppSignal, em Settings → Webhooks no GitLab. Se ele não existir, um Maintainer salva a integração novamente, como em Ativar as atualizações de status. O AppSignal não conseguiu remover o webhook. Um Maintainer do projeto GitLab pode excluí-lo em Settings → Webhooks no GitLab. O AppSignal reporta a integração com o GitLab como inválida. Verifique quais escopos o token realmente tem. read_registry e read_repository ficam lado a lado na lista de escopos do GitLab, e um token que concede read_registry em vez de read_api não consegue ler seu projeto. Os links de fonte no AppSignal não abrem o arquivo correto. No AppSignal, vá para App settings → Integrations e selecione Configure ao lado de GitLab. Confirme que a GitLab URL aponta para a raiz do projeto (ex. https://gitlab.com/namespace/project), e não para um subpath, branch ou URL .git.

Lista de integrações