- Vincular o AppSignal ao seu repositório no GitLab, para que o AppSignal saiba onde seu código está.
- Vincular backtraces a revisões e linhas, para que cada linha de backtrace abra o código que foi implantado.
- Criar issues do GitLab para incidentes, direto da tela de detalhes de um incidente.
- Acompanhar issues vinculadas a partir do incidente, para ver o status delas no GitLab sem sair do AppSignal. Este recurso está em beta.
- Vincular uma issue existente do GitLab a partir de uma nota no incidente. Este recurso está em beta.
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.
Vincular o AppSignal ao seu repositório no GitLab
Passo 1. Crie um personal access token do GitLab
- Faça login no GitLab e vá para suas Settings de usuário.
- Na barra lateral esquerda, selecione Access tokens e, em seguida, abra Personal access tokens (
https://gitlab.com/-/user_settings/personal_access_tokensno GitLab.com). - 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.
- 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_repositoryeapi. O AppSignal precisa dos três.
- Token name:
- Selecione Create personal access token e copie o token imediatamente. O GitLab mostra apenas uma vez.
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
- No AppSignal, abra o app que você deseja conectar.
- Vá para App settings → Integrations. Em Personal issue tracker integrations, selecione Configure ao lado de GitLab.
- 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 exemplohttps://gitlab.example.com/your-group/your-project.
- Selecione Create integration.
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.Vincular backtraces a revisões e linhas
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 arevision 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:- Abra a tela de detalhes do incidente de erro.
- No painel Actions, selecione Send to GitLab.
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.
- Premium e Ultimate: o status como o GitLab o nomeia, como To do ou um status personalizado como In review.
- Free: Open ou Closed.

- 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:- Vá para App settings → Integrations e selecione Configure ao lado de GitLab.
- Selecione Update integration. Se a integração for nova, selecione Create integration.
Vincular uma issue existente do GitLab
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, comohttps://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#42ouyour-group/your-project#42nã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çãorevision, 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 deapi 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.