GitLab Plugin (TRE-PR)

Plugin no padrão aberto Agent Plugins para integração com a instância interna do GitLab do TRE-PR (gitlab.tre-pr.jus.br). Permite que agentes de IA interajam diretamente com projetos, merge requests, issues, pipelines de CI/CD, wiki, releases, tags, milestones e outros recursos do GitLab através do Model Context Protocol (MCP).

O MCP server utilizado é o @trepr/mcp-gitlab, disponibilizado internamente no Nexus do TRE-PR (nexus.tre-pr.jus.br), com suporte nativo a instâncias self-hosted e autenticação via OAuth2 Authorization Code Flow.

gitlab-plugin/
├── .env.example                    # Modelo para configuração das credenciais OAuth
├── plugin.json                     # Manifesto do plugin (Agent Plugins v1.0.0)
├── mcp.json                        # Configuração do MCP server (@trepr/mcp-gitlab)
├── packages/
│   └── mcp-gitlab/                 # Pacote npm wrapper (@trepr/mcp-gitlab) publicado no Nexus
│       ├── bin/run.mjs             # Script de execução com resolução de credenciais
│       ├── package.json            # Metadados e dependências do pacote npm
│       └── README.md               # Instruções de publicação no Nexus
├── skills/
│   └── gitlab-operator/
│       ├── SKILL.md                # Ponto focal com matriz de decisão
│       └── references/             # Guias detalhados sob demanda
├── icon.svg                        # Ícone do plugin
├── tre-root-v3.crt                 # Certificado raiz da AC interna do TRE-PR
├── README.md                       # Documentação do plugin
└── CHANGELOG.md                    # Histórico de versões

1. Node.js 22+ (necessário para o suporte a --use-system-ca)
2. npx disponível no PATH
3. Configuração do Nexus no ~/.npmrc: O escopo @trepr deve apontar para o repositório npm do Nexus interno do TRE-PR:

   @trepr:registry=https://nexus.tre-pr.jus.br/repository/npm-group/

4. Certificado da CA interna do TRE-PR instalado no Certificate Store (geralmente distribuído via GPO na rede interna)

node --version    # Deve retornar v22.x.x ou superior
npx --version     # Deve estar disponível no PATH

O GitLab do TRE-PR utiliza SSL com CA interna. A flag --use-system-ca (Node.js 22+) instrui o Node.js a confiar nos certificados do Certificate Store do sistema operacional.

Para verificar se o certificado da AC raiz está instalado no Windows:

certutil -store Root "ACRAIZ"

Se o certificado não estiver instalado, utilize o arquivo tre-root-v3.crt incluído na raiz deste plugin:

certutil -addstore Root "tre-root-v3.crt"

Este plugin utiliza o OAuth2 Authorization Code Flow diretamente com o GitLab do TRE-PR como provedor de identidade. Não é necessário gerar ou salvar Personal Access Tokens manualmente.

1. Ao iniciar o MCP server, se não houver token válido, um servidor HTTP local é iniciado na porta 8888.
2. O navegador abre automaticamente na página de autorização do GitLab (https://gitlab.tre-pr.jus.br/oauth/authorize).
3. O usuário realiza o login (caso não esteja logado).
4. O GitLab solicita autorização para a aplicação com escopo api.
5. Ao clicar em Authorize, o GitLab redireciona para http://127.0.0.1:8888/callback com o código de autorização.
6. O MCP server troca o código pelo token de acesso OAuth2 e inicia a comunicação.

O plugin inclui a skill skills/gitlab-operator/SKILL.md que orienta o agente sobre:

• Convenções de referência a projetos (group/subgroup/project ou usuario/projeto).
• Modo somente leitura (GITLAB_READ_ONLY_MODE).
• Workflows de Merge Requests e Code Review estruturado (em 2 etapas).
• Gerenciamento de Issues, Pipelines de CI/CD, páginas de Wiki, Releases e Milestones.
• Tratamento estruturado de erros da API.
• Diretrizes de segurança e confirmação prévia para operações destrutivas.

• "Listar meus projetos no GitLab."
• "Mostrar merge requests abertos do projeto sds/sistemas/meu-projeto."

• "Revise o merge request !42 do projeto sds/sistemas/meu-projeto."

• "Criar uma issue no projeto sds/sistemas/meu-projeto com título 'Bug no login'."
• "Listar issues abertas atribuídas a mim."
• "Fechar a issue #15 do projeto sds/sistemas/meu-projeto."

• "Mostrar o status da última pipeline do projeto sds/sistemas/meu-projeto."
• "Ver o log do job 'build' que falhou na pipeline #123."
• "Executar novamente a pipeline #123 do projeto sds/sistemas/meu-projeto."

• "Listar páginas wiki do projeto sds/sistemas/meu-projeto."
• "Criar uma release v2.0.0 a partir da tag v2.0.0."
• "Criar milestone 'Sprint 42' com data de término 2026-07-01."

• Verifique se o Node.js é versão 22+: node --version.
• Verifique se o certificado ACRAIZ está instalado: certutil -store Root "ACRAIZ".
• Instale o certificado tre-root-v3.crt se necessário: certutil -addstore Root "tre-root-v3.crt".

• O token OAuth pode ter expirado ou sido revogado. Reinicie ou reconecte o MCP server para abrir o navegador e autorizar novamente.

• Certifique-se de utilizar o namespace completo do projeto (ex: grupo/subgrupo/projeto).
• Verifique se seu usuário possui permissão de acesso ao projeto no GitLab.

• Verifique se o Node.js 22+ e o npx estão instalados e disponíveis no PATH.
• Verifique se a porta 8888 não está ocupada por outro processo:

  netstat -ano | findstr :8888

• Causa: O MCP server não encontrou o Client ID nas variáveis de ambiente, no arquivo global ~/.gitlab-plugin.env ou no .env do workspace.
• Atenção sobre atualizações: Se você configurou um arquivo .env dentro da pasta do plugin, ele foi removido durante a atualização do plugin realizada pelo Kiro. Nunca salve o arquivo .env na raiz do plugin.
• Como configurar e resolver:
  1. Arquivo Global do Usuário (Recomendado): Crie o arquivo ~/.gitlab-plugin.env (Linux/macOS) ou %USERPROFILE%\.gitlab-plugin.env (Windows):

     GITLAB_OAUTH_CLIENT_ID=<seu_client_id>
     GITLAB_OAUTH_CLIENT_SECRET=<seu_client_secret> # Apenas se a aplicação for confidencial

  2. Variáveis de Ambiente do Sistema:
     • Linux/macOS:

       export GITLAB_OAUTH_CLIENT_ID="<seu_client_id>"
       export GITLAB_OAUTH_CLIENT_SECRET="<seu_client_secret>" # Se confidencial

     • Windows (PowerShell):

       [System.Environment]::SetEnvironmentVariable('GITLAB_OAUTH_CLIENT_ID', '<seu_client_id>', 'User')
       [System.Environment]::SetEnvironmentVariable('GITLAB_OAUTH_CLIENT_SECRET', '<seu_client_secret>', 'User') # Se confidencial

  3. Arquivo .env na Raiz do Workspace: Crie o .env na raiz do projeto/workspace onde você está trabalhando (e não dentro da pasta do plugin).
  4. Após definir as variáveis, reinicie o Kiro ou reconecte o servidor MCP para que as configurações tenham efeito.

O pacote @trepr/mcp-gitlab é executado via npx e resolve as credenciais OAuth a partir do ambiente do usuário, garantindo que credenciais e IDs sensíveis não fiquem expostos no código versionado.

Configure as variáveis através de qualquer uma das opções abaixo:

1. Arquivo Global do Usuário (Recomendado e Persistente): Crie o arquivo ~/.gitlab-plugin.env no diretório de usuário (Linux/macOS: ~/.gitlab-plugin.env, Windows: %USERPROFILE%\.gitlab-plugin.env):

   GITLAB_OAUTH_CLIENT_ID=<seu_client_id>
   GITLAB_OAUTH_CLIENT_SECRET=<seu_client_secret> # Necessário apenas se a aplicação for confidencial

   Esta opção é a mais indicada, pois permanece intacta durante atualizações do plugin e funciona em qualquer workspace.

2. Variáveis de Ambiente do Sistema:

   • Linux/macOS:

     export GITLAB_OAUTH_CLIENT_ID="<seu_client_id>"
     export GITLAB_OAUTH_CLIENT_SECRET="<seu_client_secret>" # Se confidencial

   • Windows:

     [System.Environment]::SetEnvironmentVariable('GITLAB_OAUTH_CLIENT_ID', '<seu_client_id>', 'User')
     [System.Environment]::SetEnvironmentVariable('GITLAB_OAUTH_CLIENT_SECRET', '<seu_client_secret>', 'User') # Se confidencial

3. Arquivo .env na Raiz do Workspace: Crie um arquivo .env na raiz do seu projeto/workspace em desenvolvimento com base no .env.example.

Distribuído sob uso interno TRE-PR.