NotíciasA busca de código personalizada no Bitbucket Cloud precisa de atenção agora: a Atlassian começará a interromper a API antiga em 3 de novembro de 2026 e a removerá em 15 de novembro. Equipes que usam scripts, painéis internos ou integrações próprias para localizar trechos nos repositórios devem migrar para a nova API de busca por workspace antes do primeiro período de indisponibilidade. A mudança não é só de endereço: o método passa de GET para POST, o corpo da requisição muda e a autenticação precisa identificar o usuário e permitir leitura de repositórios e workspace.
A busca feita normalmente pela interface do Bitbucket não é o foco deste aviso. A Atlassian cita três rotas da API REST, usadas por aplicações e automações. Se sua equipe nunca chamou essas rotas, não há uma migração a fazer; ainda assim, vale procurar por elas em integrações antigas, jobs de CI e ferramentas internas.
Quando a API antiga começa a falhar
O aviso no changelog oficial do Bitbucket Cloud, publicado em 26 de outubro, lista as rotas afetadas:
GET /2.0/users/{user}/search/codeGET /2.0/teams/{team}/search/codeGET /2.0/workspaces/{workspace}/search/code
Os primeiros “brownouts” começam em 3 de novembro, às 00:00 UTC. São janelas temporárias de indisponibilidade, repetidas a cada seis horas e progressivamente mais longas: 15 minutos nos dias 3 e 4; uma hora nos dias 5 e 6; duas horas nos dias 7 e 8; três horas nos dias 9 e 10; quatro horas nos dias 11 e 12; e cinco horas nos dias 13 e 14. Em cada data, as janelas começam às 00:00, 06:00, 12:00 e 18:00 UTC.
Durante essas janelas, as rotas antigas devem responder com HTTP 410. Fora delas, continuarão funcionando até a remoção definitiva, em 15 de novembro, às 00:00 UTC. Como os horários são UTC, no Brasil (UTC−3) o primeiro início corresponde a 21h de 2 de novembro. Não espere pelo último dia para descobrir que uma automação depende da API.
O que muda na integração
A substituta é POST /2.0/workspaces/{workspace}/codesearch. A documentação oficial da API de busca por workspace diz que a busca se limita aos repositórios que a credencial usada pode acessar. O corpo precisa ser JSON e incluir query.search_term; a consulta pode incluir filtros e uma configuração de resultados, com máximo de 100 por página. A busca é lexical, isto é, encontra termos no código, e não interpreta intenção ou significado como uma busca semântica.
Um corpo mínimo fica parecido com este:
{
"query": {
"search_term": "minha função"
},
"config": {
"max_results": 50
}
}
O workspace informado na URL define automaticamente o escopo. A Atlassian alerta para não enviar um filtro namespace no corpo: ele pode fazer a requisição retornar erro 400. Se o resultado vier paginado, a aplicação deve reaproveitar o identificador da consulta e o cursor seguinte; os termos e filtros precisam permanecer iguais entre páginas.
Também confira a autenticação antes de trocar a chamada. Para tokens de API e apps Forge, a documentação exige os escopos read:repository:bitbucket e read:workspace:bitbucket. A Atlassian diz que credenciais que não identificam o usuário, como app passwords e certos tokens ou integrações legadas, serão recusadas com 403. A nova rota, portanto, pode exigir uma revisão de permissões além da alteração de método e payload.
Um roteiro curto para migrar com segurança
Comece procurando os três caminhos antigos em repositórios de aplicação, scripts de manutenção, variáveis de configuração, ferramentas internas e workflows de CI. Procure não só pela URL inteira, mas também por search/code, para encontrar chamadas que montam o endereço dinamicamente. Registre quem consome cada integração e quais resultados espera: nomes de repositório, caminhos, trechos e paginação.
Depois atualize método, URL e JSON em conjunto. Revise o tipo de credencial e conceda apenas os escopos necessários. Faça testes com uma consulta conhecida e compare o conjunto de repositórios e arquivos retornados, lembrando que a nova API só pesquisa o que o usuário autenticado pode acessar. Se a integração usa filtros, teste casos com AND/OR, filtros de linguagem e caminhos; se percorre muitos resultados, confira a lógica do cursor. A referência da API descreve filtros, escopo e paginação, detalhes que podem revelar diferenças em relação ao comportamento antigo.
Por fim, teste a automação durante uma janela de brownout. Esse ensaio confirma que a chamada antiga já não é necessária e que a aplicação trata erros temporários e limites de acesso de forma compreensível. Não transforme cada HTTP 410 em repetição agressiva: durante o período anunciado, o erro é um sinal útil de que ainda há uma dependência para migrar. Após a transição, monitore 401, 403, 400 e 429 separadamente, pois apontam problemas diferentes de credencial, escopo, formato ou limite de requisições.
O que a data muda para quem mantém software
Integrações pequenas costumam ficar fora do inventário principal: um script de suporte, um painel para encontrar uma função duplicada ou uma etapa auxiliar de CI. O cronograma progressivo ajuda a localizá-las, mas só se houver alguém observando os resultados. Vale abrir uma tarefa por consumidor encontrado, atribuir responsável e guardar a consulta de teste usada na comparação.
Se a equipe já está revisando automações de entrega, pode ser útil conferir também este guia sobre workflows do GitHub Actions e versões de dependências. Para pipelines de compilação no ecossistema Vercel, veja o contexto sobre execução seletiva com Turborepo. São mudanças diferentes, mas reforçam a mesma prática: inventariar integrações, testar os caminhos críticos e documentar permissões e dependências.
A ação imediata é confirmar se existe uso das rotas antigas e concluir a migração antes de 3 de novembro de 2026. A janela de 15 de novembro é o limite final, não uma data segura para começar.
