Pular para o conteúdo principal

Por que integrar o Devin ao Bitbucket?

Integrar o Devin aos seus repositórios no Bitbucket permite que ele crie pull requests, leia e responda aos comentários nos seus PRs e colabore de forma eficaz com sua equipe. Isso faz com que o Devin seja um verdadeiro colaborador no seu time de engenharia.

Pré-requisitos

Antes de configurar a integração com o Bitbucket, recomendamos:
  • Conta de serviço dedicada - Crie uma nova conta do Bitbucket especificamente para o Devin (por exemplo, devin@yourcompany.com), em vez de usar uma conta de usuário existente, para facilitar o gerenciamento de acesso e o rastreamento de auditoria
Usar uma conta de serviço dedicada facilita o acompanhamento da atividade do Devin, o gerenciamento de permissões e a manutenção das melhores práticas de segurança em toda a sua organização.

Configurando a Integração

Bitbucket Cloud

Há dois tipos de conexão com o Bitbucket Cloud. Escolha o que corresponde ao que você precisa que o Devin faça: “As ações do próprio Devin” são os PRs que o Devin abre e os resultados e as atualizações de descrição que o Devin Review publica. As ações que você mesmo realiza no Devin Review (comentários, respostas, recusa de um PR) são publicadas em seu nome, pela sua própria conta do Bitbucket vinculada, em qualquer um dos tipos de conexão; consulte Devin Review.
O próprio Devin instala os webhooks necessários para a Revisão automática do Devin Review, em qualquer um dos tipos de conexão, mas somente quando a conexão tem permissão para administrar o repositório: um token de acesso com Webhooks: Read and write e Repositories: Admin, ou uma conexão OAuth cuja conta do Bitbucket vinculada seja administradora do repositório. Caso contrário, o repositório aparece como Skipped no status de webhook da conexão, com o motivo informado pelo Bitbucket, e as revisões só são executadas quando você mesmo abre um PR no Devin Review.

Conectar com um token de acesso

  1. No Bitbucket, crie um token de acesso do workspace para o workspace em que o Devin vai trabalhar, com estes escopos:
    • Repositories: Admin
    • PRs: Write
    • Webhooks: Read and write
    Com escopos mais restritos, o Devin não consegue ler o estado de merge nem instalar webhooks.
  2. Na sua conta do Devin, acesse Configurações > Conexões > Bitbucket, abra o menu suspenso ao lado do botão Connect e selecione Connect with access token.
  3. Insira o ID do workspace (o my-workspace em bitbucket.org/my-workspace) e o token e, em seguida, clique em Connect.
O Devin usa o token neste workspace e publica em nome do token, não em seu nome. Quando a conexão estiver ativa, o próprio Devin instala os webhooks dele nos repositórios do workspace; o painel de detalhes da conexão mostra o resultado de cada repositório e um botão Refresh para executar a instalação novamente.

Conectar com OAuth

Use OAuth quando seu workspace não estiver no Bitbucket Cloud Premium. Uma conexão OAuth usa a autorização do Bitbucket da própria conta vinculada: as ações de escrita do Devin (os PRs que ele abre, os resultados e as atualizações de descrição que o Devin Review publica) aparecem em nome dessa conta, e os webhooks são instalados apenas nos repositórios que essa conta administra. Por isso, as etapas abaixo começam com uma conta dedicada do Bitbucket: nunca vincule a conta de uma pessoa à organização. Se a conexão foi vinculada antes de o app do Bitbucket do Devin poder gerenciar webhooks, os repositórios dela aparecem como Skipped até que você a substitua.
  1. Crie uma nova conta no Bitbucket especificamente para o Devin (assim como você criaria uma conta pessoal). Você usará essa conta, não a sua conta pessoal, durante o processo de integração.
  2. Na sua conta do Devin, acesse Settings > Conexões > Bitbucket e clique em “Connect”.
Conectar Bitbucket Cloud
  1. Você será redirecionado para o Bitbucket, onde deverá:
    • Entrar com a conta do Bitbucket que você criou para o Devin (não a sua conta pessoal)
    • Conceder as permissões necessárias para o Devin trabalhar com seus repositórios
  2. Quando terminar, você retornará à página de configurações do Devin, onde poderá confirmar que a integração está ativa.

Substituir uma conexão OAuth antiga

Uma conexão OAuth mantém as permissões que tinha quando foi vinculada. Por isso, uma conexão vinculada antes de o app do Bitbucket do Devin poder gerenciar webhooks exibe seus repositórios como Skipped, e o status de webhook dela pede que você a reconecte. Não há como reconectá-la diretamente: conectar novamente adiciona uma segunda conexão com o mesmo nome, e a primeira continua como Skipped. Em vez disso, substitua a conexão antiga:
  1. Abra o painel de detalhes da conexão e anote o que você alterou nela, como as permissões de repositório e Manage access. Nenhuma dessas configurações é transferida para a nova conexão.
  2. Na aba General, clique em Disconnect connection. O Devin fica sem acesso a esses repositórios até que a próxima etapa seja concluída.
  3. Em Configurações > Conexões > Bitbucket, abra o menu suspenso ao lado de Connect with access token, selecione Connect with OAuth (any Bitbucket plan) e faça login com a mesma conta do Bitbucket.
  4. Reaplique o que você anotou na etapa 1. A nova conexão começa com acesso a todos os workspaces visíveis para a conta vinculada. Em uma conta Enterprise, ela começa sem acesso a nenhuma organização; portanto, conceda o acesso às suas organizações novamente.
Em seguida, o Devin instala os webhooks automaticamente, e o painel de detalhes da nova conexão mostra o resultado de cada repositório. Se você já tiver conectado novamente, terá duas conexões com o mesmo nome. Anote as configurações de ambas, desconecte as duas e conecte uma única vez, conforme as etapas 3 e 4.

Bitbucket Data Center

Para organizações que usam Bitbucket Data Center (hospedado localmente/self-hosted), siga estas etapas:
  1. Crie uma conta de serviço dedicada na sua instância do Bitbucket Data Center para o Devin.
  2. Na sua conta do Devin, vá para Settings > Connections > Bitbucket, abra o dropdown ao lado do botão Connect e selecione Connect with Bitbucket Data Center.
Conectar Bitbucket Data Center
  1. Configure a conexão fornecendo:
    • Bitbucket Host: o domínio do seu Bitbucket Data Center (por exemplo, bitbucket.mycompany.com)
    • Bitbucket Username: o nome de usuário da conta de serviço
    • Bitbucket HTTP Access Token: um HTTP access token criado para a conta de serviço. Você pode substituí-lo depois em Rotate access token, no painel de detalhes da conexão.
Configuração do Bitbucket Data Center
  1. Conceda à conta de serviço as permissões apropriadas de projeto e repositório na sua instância do Bitbucket Data Center.
  2. Depois de concluir a configuração, o status da integração será exibido nas suas configurações do Devin.

Configuração de webhook (Bitbucket Data Center)

Configurar um webhook permite que o Devin receba eventos de PR do Bitbucket Data Center em tempo real, de modo que o status e os comentários do PR sejam entregues à sessão do Devin que está trabalhando nele.
  1. Na sua conta do Devin, acesse Settings > Conexões > Bitbucket e clique na conexão do Bitbucket Data Center para abrir o painel de detalhes.
  2. Na aba General, clique em Configure na linha Webhook. A caixa de diálogo exibe a URL do webhook e um token secreto — copie o token agora, pois ele é exibido apenas uma vez (você pode gerá-lo novamente depois na mesma caixa de diálogo).
  3. No Bitbucket Data Center, abra as configurações do repositório ou do projeto e vá até Webhooks.
  4. Crie um webhook e cole a URL do webhook.
  5. Em eventos de PR, selecione Opened, Source branch updated, Merged, Declined e Comment added.
  6. Em Authentication, escolha Basic, informe qualquer nome de usuário e cole o token secreto como senha.
Conexões do Bitbucket Cloud não têm caixa de diálogo de webhook: o próprio Devin instala os webhooks em uma conexão por token de acesso ou em uma conexão OAuth cuja conta do Bitbucket vinculada seja administradora do repositório.
Por padrão, tudo o que o Devin faz no Bitbucket Data Center é atribuído à conta de serviço. Ao vincular sua própria conta, você pode comentar, adicionar ou remover revisores, aprovar e recusar PRs pelo Devin Review em seu próprio nome. Configuração do administrador (uma única vez por host do Bitbucket Data Center):
  1. No Devin, acesse Settings > Connections > Bitbucket e clique em Register app na seção Bitbucket Data Center user OAuth. A caixa de diálogo exibe a URL de redirecionamento e as permissões que devem ser usadas.
  2. No Bitbucket Data Center, acesse Administration > Application links, selecione Create link e escolha External application e Incoming. Cole a URL de redirecionamento e conceda a permissão Repositories: Write.
  3. Cole o client ID e o client secret do aplicativo na caixa de diálogo do Devin e clique em Register.
Cada usuário: vincule sua conta do Bitbucket quando o Devin Review solicitar ou pela seção de contas vinculadas do seu perfil.
Remover o aplicativo registrado no Devin desvincula a conta do Bitbucket Data Center de todos os usuários naquele host.

Como usar o Devin com a integração do Bitbucket

Depois de conectar o Bitbucket, configure seus repositórios em Devin’s Machine.
Como o Devin responde a comentários de PR.
  • Bitbucket Cloud: o Devin não é acionado automaticamente por comentários em seus PRs. Mesmo assim, ele pode tratá-los se você apontá-los diretamente na sessão. Os webhooks que o Devin instala em uma conexão Cloud atendem ao Devin Review, e não às sessões.
  • Bitbucket Data Center: depois que o webhook estiver configurado, um comentário em um PR que uma sessão do Devin esteja acompanhando é entregue a essa sessão e o Devin responde. Um organization admin pode restringir esse comportamento com Require @Devin to respond em Settings > Devin > PRs, para que o Devin responda apenas a comentários que comecem com @Devin ou com Devin como palavra isolada, como Devin fix this (o prefixo devinai também é aceito). Comentários que contenham (aside) ou !aside, ou que comecem com aside, são sempre ignorados. Sem um webhook, o Data Center se comporta como o Bitbucket Cloud.

Melhores práticas

  • Crie uma conta dedicada no Bitbucket para o Devin
  • Ative proteções de branch nos branches main e master
  • Conceda à conta de serviço as permissões adequadas de workspace e repositório
  • No Bitbucket Cloud, ao se conectar via OAuth, vincule uma conta do Bitbucket criada para o Devin (com perfil de administrador do repositório); o Devin publica usando a conta vinculada
  • No Bitbucket Data Center, configure o webhook para que o Devin receba eventos de PR em tempo real