O que ela habilita
Faça login com a Microsoft
Conecte sua conta do Azure DevOps por meio do fluxo de código de dispositivo, sem nenhum tratamento de senha dentro do aplicativo.
Navegue pelos repositórios
Liste repositórios Git em todas as organizações e projetos que sua conta consegue acessar.
Tokens criptografados
Os tokens de acesso e de atualização são criptografados em repouso com o keychain do sistema operacional e nunca são expostos ao renderer.
Atualização automática
O Orkestral atualiza o token de acesso em segundo plano enquanto houver um token de atualização disponível.
Requisitos
- Uma conta corporativa ou de estudante da Microsoft com acesso a pelo menos uma organização do Azure DevOps.
- Os repositórios que você quer usar precisam estar no Azure Repos (Git). O Orkestral lista apenas repositórios que expõem uma URL de clonagem.
- Um keychain do sistema operacional funcional para que o Orkestral possa criptografar os tokens. No macOS é o Keychain, no Windows é o Credential Manager, no Linux é um provedor Secret Service. Se a criptografia não estiver disponível, a conexão falha com um erro.
- Uma conexão com a internet para alcançar
login.microsoftonline.com,app.vssps.visualstudio.comedev.azure.com.
O Orkestral solicita os escopos
user_impersonation (no recurso do Azure DevOps) e offline_access. O escopo offline_access é o que permite ao Orkestral obter um token de atualização e manter sua sessão ativa.Como conectar
Abra a integração
Vá até a área de integrações ou configurações e escolha Azure DevOps, depois inicie a conexão.
Inicie o fluxo de dispositivo
O Orkestral solicita um código de dispositivo à Microsoft e mostra a você um código de usuário curto, além de um link de verificação.
Aprove no navegador
Abra a URL de verificação (o Orkestral pode abri-la para você), faça login com sua conta da Microsoft e insira o código de usuário. Aprove as permissões solicitadas.
Aguarde a confirmação
O Orkestral consulta a Microsoft até você aprovar. Quando o fluxo retorna
authorized, os detalhes da sua conta e as organizações aparecem no aplicativo.Estados do fluxo de dispositivo
Enquanto você conclui a etapa no navegador, o Orkestral consulta a Microsoft e reage a cada estado que ela retorna.| Estado | Significado |
|---|---|
pending | Você ainda não aprovou. O Orkestral continua consultando. |
slow_down | A Microsoft pede que o Orkestral consulte com menos frequência. O intervalo aumenta automaticamente. |
expired | O código de usuário expirou. Inicie a conexão novamente. |
denied | Você recusou a solicitação ou o acesso foi negado. |
authorized | O login foi bem-sucedido. Sua conta e organizações foram salvas. |
Opções de configuração
A integração funciona com os padrões internos. As variáveis de ambiente a seguir permitem apontar o Orkestral para um tenant do Microsoft Entra (Azure AD) ou para um registro de aplicativo diferente, o que é útil em configurações de tenant único ou corporativas.O tenant do Microsoft Entra usado para a URL de autoridade (
https://login.microsoftonline.com/<tenant>). Use common para login multi-tenant, ou um ID de tenant específico para restringir o login a um único diretório.O ID do aplicativo (cliente) usado para o fluxo de código de dispositivo. Substitua-o para usar seu próprio registro de aplicativo.
O que é armazenado
Quando você conecta, o Orkestral salva um único registro de conta do Azure DevOps. Os campos públicos, não secretos, que você pode ver no aplicativo são:| Campo | Descrição |
|---|---|
displayName | Seu nome, lido a partir do ID token. |
email | Seu nome de login (preferred_username) ou e-mail. |
tenantId | O ID do tenant para o qual o token foi emitido. |
scope | Os escopos OAuth concedidos. |
connectedAt | Quando a conta foi conectada pela primeira vez. |
expiresAt | Quando o token de acesso atual expira. |
organizations | As organizações do Azure DevOps vinculadas à sua conta. |
Como funciona a listagem de repositórios
Quando você lista repositórios, o Orkestral:- Obtém um token de acesso válido, atualizando-o antes caso ele expire em cerca de 90 segundos.
- Determina quais organizações consultar. Ele usa uma organização específica se você passar uma, caso contrário usa as organizações salvas na sua conta, caso contrário as descobre a partir do seu perfil.
- Para cada organização, lista os projetos e, em seguida, lista os repositórios Git em cada projeto.
- Retorna apenas repositórios que têm uma URL de clonagem, ordenados pelo nome completo (
organization/project/repo).
A descoberta percorre todas as organizações e projetos aos quais você tem acesso, então a listagem pode levar um momento em contas grandes. Repositórios sem uma URL remota utilizável são ignorados.
Desconectando
Desconectar exclui a conta do Azure DevOps armazenada, incluindo os tokens criptografados de acesso e de atualização. Após desconectar, você precisa executar o fluxo de dispositivo novamente para reconectar. As fontes que você já adicionou permanecem configuradas, mas o Orkestral não consegue mais buscar dados atualizados para elas até você reconectar.Recursos e limites
- O Orkestral lê metadados de repositórios para navegação e adição de fontes. Ele age com suas próprias permissões do Azure DevOps por meio de
user_impersonation. - Apenas repositórios do Azure Repos (Git) são listados. Repositórios TFVC e repositórios sem uma URL de clonagem não aparecem.
- A sessão permanece ativa automaticamente enquanto houver um token de atualização. Se o token de acesso expirar e não existir nenhum token de atualização, você é solicitado a conectar novamente.
- A criptografia de tokens depende do keychain do sistema operacional. Em ambientes onde ele não está disponível, a conexão e a leitura de tokens falham.
Solução de problemas
Criptografia indisponível
Criptografia indisponível
O Orkestral não conseguiu acessar o keychain do sistema operacional para criptografar ou descriptografar os tokens. Verifique se o seu keychain ou armazenamento de credenciais está desbloqueado e disponível, depois tente conectar novamente. No Linux, confirme que um provedor Secret Service (como o GNOME Keyring) está em execução.
O código de usuário expirou antes de eu aprovar
O código de usuário expirou antes de eu aprovar
O código de dispositivo tem vida curta. Inicie a conexão novamente para obter um novo código, depois aprove-o prontamente no navegador.
Sessão expirada. Conecte novamente.
Sessão expirada. Conecte novamente.
Seu token de acesso expirou e nenhum token de atualização foi armazenado, ou a atualização falhou. Desconecte e execute o fluxo de dispositivo novamente para obter uma nova sessão.
Nenhuma organização ou repositório aparece
Nenhuma organização ou repositório aparece
Confirme que sua conta pertence a pelo menos uma organização do Azure DevOps e que os repositórios são baseados em Git. O Orkestral descobre organizações a partir do seu perfil, então certifique-se de que seu perfil esteja acessível. Se você usa uma configuração de tenant único, verifique se
ORKESTRAL_AZURE_TENANT_ID aponta para o diretório correto.O login é recusado ou o acesso é negado
O login é recusado ou o acesso é negado
O fluxo retornou
denied. Execute a conexão novamente e aprove todas as permissões solicitadas. Se a sua organização aplica políticas de acesso condicional, pode ser necessário que um administrador autorize o registro do aplicativo.Um repositório que eu espero está faltando
Um repositório que eu espero está faltando
O Orkestral ignora repositórios que não expõem uma URL de clonagem e lista apenas o Azure Repos (Git). Verifique se o repositório existe em um projeto ao qual você tem acesso e se é um repositório Git.
Relacionados
Fontes
Adicione repositórios conectados como fontes para os seus agentes.
Integrações
Veja os outros provedores que você pode conectar ao Orkestral.