Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Use as Ferramentas de Desenvolvimento do Work IQ (WIQD) para adicionar verificações de integração contínua e entrega contínua (CI/CD) ao seu projeto de plug-in do Microsoft 365 Copilot. Este artigo separa verificações de solicitação de pull baratas do teste de candidato autenticado e do envio de versão aprovado.
Este guia é para desenvolvedores que integram o WIQD a um sistema de CI/CD existente. Ele documenta os requisitos e as sequências de comandos, não como configurar um ambiente completo de CI/CD. Espera-se que você configure os trabalhos, os gatilhos, os executores, os segredos, as aprovações e o tratamento de artefatos do sistema e integre os exemplos a esse sistema. Antes de começar, prepare o executor, os ambientes e as credenciais listados em Pré-requisitos.
O destino da versão é o catálogo de aplicativos da organização do locatário, em que um administrador aprova os plug-ins enviados antes que os usuários possam descobri-los. O compartilhamento direto é um método de distribuição separado. Esse fluxo de trabalho não automatiza a aprovação do administrador ou a publicação do repositório público por meio do Partner Center.
Pré-requisitos
Para executar os comandos WIQD em seus pipelines ou fluxos de trabalho existentes, certifique-se de ter:
- Um projeto de plug-in WIQD controlado pelo código-fonte com seus arquivos de ciclo de vida, testes de componentes e configuração de ambiente não secreto. Consulte Criar um plug-in com as Ferramentas de Desenvolvimento do Work IQ.
- Um sistema de CI/CD existente com check-out de origem, executores, segredos protegidos e controles de aprovação de versão. Você sabe como configurar trabalhos, gatilhos e manipulação de artefatos nesse sistema.
- Node.js 24.15.0 ou posterior e uma autorização WIQD aprovada exata no corredor. Siga as instruções de instalação do WIQD e registre a versão instalada com
wiqd --version. - PowerShell 7 para usar os exemplos de comando neste artigo.
- Um ambiente WIQD configurado para comandos com suporte de locatário. Siga a configuração de ambiente WIQD para preparar os arquivos de ambiente. Ambientes de teste e produção separados ou locatários do Microsoft 365 são opcionais, não pré-requisitos.
dev,stagingeprodsão nomes convencionais, não garantias sobre o locatário ou o escopo da implantação. - Uma identidade do Microsoft 365 autorizada para as operações selecionadas de provisionamento, validação profunda e publicação, com o consentimento delegado necessário. Conceda apenas as permissões necessárias para essas operações, conforme listado no consentimento e nos limites de recursos do WIQD.
- Para avaliações de agente declarativo, um destino provisionado, um arquivo de prompts revisado, um limite de qualidade aprovado e autenticação de avaliação configurada separadamente e aceitação de EULA. Siga o guia de avaliação do agente WIQD para obter configuração e requisitos detalhados. A avaliação do agente não é necessária para plug-ins sem agentes, como plug-ins somente de habilidade ou somente de ferramenta; manter seus testes de componente e experiência-alvo aplicáveis.
Siga a documentação do seu provedor de CI/CD para configurar a plataforma e criar o fluxo de trabalho. Por exemplo, confira Criar seu primeiro pipeline do Azure ou Implementar o GitHub Actions.
Escolha os cenários de pipeline
Configure trabalhos separados para que alterações não confiáveis não possam acessar as credenciais de implantação ou enviar uma versão.
| Cenário | Quando executar | Operações WIQD | Portão |
|---|---|---|---|
| Validação de solicitação de pull | Quando uma solicitação de pull é aberta e após cada atualização das alterações propostas | Validação de plugin offline; Preparação opcional para publicação offline | As verificações estáticas foram aprovadas, com seus limites de cobertura registrados |
| Compilação e teste de candidatos | Alterações aprovadas em um branch confiável ou uma execução manual autorizada | Provisione o plug-in no ambiente selecionado, empacote, valide profundamente, teste e avalie os agentes aplicáveis | Verificações de pacote, componente, experiência e qualidade aprovadas |
| Envio de versão | Candidato aprovado e autorização de liberação | Confirme a configuração da versão e o pacote validado e, em seguida, publique no catálogo de aplicativos da organização | Envio bem-sucedido seguido pela aprovação do administrador e verificação da distribuição |
Mantenha a compilação e os testes do componente do projeto. O WIQD não fornece um comando de compilação universal para cada plug-in nem atualiza os serviços remotos aos quais seu plug-in faz referência.
Se você adaptar o guia de configuração de pipeline WIQD a um projeto de plug-in, use as sequências de wiqd plugin comando deste artigo. Os exemplos de ciclo de vida desse guia são direcionados a projetos de wiqd agent agentes, não a projetos de plug-ins independentes.
Adicionar verificações de solicitação de pull baratas
Executar a validação offline sem credenciais do Microsoft 365. Essas verificações não provisionam recursos, invocam um agente ou enviam nada ao Registro.
Para adicionar uma marca estática a um trabalho existente:
- Confira a fonte proposta e instale a versão aprovada do WIQD.
- Execute os testes de componentes aplicáveis do projeto.
- Execute a etapa WIQD a seguir, substituindo
.\plugins\contosopelo caminho do projeto edevpelo contexto de ambiente pretendido. - Exigir êxito de saída nativa e um envelope de êxito JSON antes que o trabalho possa passar.
Esta etapa do GitHub Actions verifica a superfície de origem do agente declarativo em um projeto de plug-in independente:
- name: Validate plugin source
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false
$text = wiqd plugin validate --path .\plugins\contoso --env dev --mode static --json
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = ($text -join "`n") | ConvertFrom-Json
if ($result.status -cne 'success') { throw 'Plugin source validation failed.' }
O mesmo corpo do PowerShell pode ser executado em uma etapa do Azure Pipelinespwsh:. Não injete credenciais de ciclo de vida ou avaliação no trabalho de solicitação de pull não confiável de nenhum dos provedores.
A validação estática abrange manifestos de agente declarativo e arquivos referenciados de plug-in de API ou OpenAPI. Ele não valida o manifesto do aplicativo de nível superior, o conteúdo de habilidade autônomo ou as declarações do conector raiz. Um plug-in somente de habilidade ou somente conector pode ser aprovado porque nenhuma verificação de agente declarativo se aplica, não porque todos os componentes são válidos.
Para uma marcar adicional de preparação para publicação offline, execute o seguinte comando e aplique as mesmas verificações de código de saída e JSON:
wiqd plugin publish --path .\plugins\contoso --env dev --dry-run --no-runtime --no-network --json
Essa marca não envia o plug-in. As verificações de tempo de execução e rede são desativadas e as fases do agente declarativo são ignoradas quando nenhum agente está presente. Nenhuma das marcas offline substitui a validação profunda ou os testes do pacote na experiência de destino do Microsoft 365.
Configurar a autenticação para trabalhos confiáveis
O provisionamento, a validação profunda e a publicação exigem credenciais que o trabalho de solicitação de pull não tem. Examine os modos de autenticação documentados com o administrador de locatários, confirme o suporte na versão WIQD selecionada e injete credenciais apenas nas etapas confiáveis.
Aviso
Não use autenticação de nome de usuário/senha. Use o modo de token de atualização assim que o suporte em sua versão WIQD selecionada for confirmado. Use o modo de senha somente quando a política de segurança da sua organização permitir explicitamente. Não enfraqueça os requisitos de MFA ou Acesso Condicional para que o pipeline seja bem-sucedido. Os tokens de atualização também são credenciais confidenciais e exigem armazenamento protegido e acesso restrito.
Importante
O guia de autenticação de pipeline WIQD marca a autenticação de token de atualização como ainda não lançada ou totalmente validada. Os exemplos de token de atualização são diretrizes de integração, não um caminho de autenticação confirmado pronto para produção. Confirme a disponibilidade de lançamento, a aprovação de segurança e o consentimento ao vivo e as verificações de operação para a versão exata do WIQD selecionada antes de usar esses exemplos.
| Modo | Entradas de processo necessárias | Entradas a serem removidas |
|---|---|---|
| Atualizar token |
CI_ENABLED=true, um GUID de locatário em M365_TENANT_IDe protegido M365_REFRESH_TOKEN |
Remover definições e M365_ACCOUNT_NAMEM365_ACCOUNT_PASSWORD, até mesmo vazias |
| Nome de usuário e senha |
CI_ENABLED=true, protegido M365_ACCOUNT_NAMEe protegido M365_ACCOUNT_PASSWORD |
Remover M365_REFRESH_TOKEN; M365_TENANT_ID é opcional neste modo |
Para autenticação de token de atualização:
- Siga o procedimento de bootstrap local privado na autenticação de pipeline WIQD.
- Coloque o token resultante diretamente no repositório de segredos do pipeline aprovado. Não o confirme, passe-o como um argumento de comando ou inclua-o em logs ou artefatos.
- Mapeie o locatário e o token no processo de comando confiável.
- Verifique a versão, a identidade, o executor e as operações necessárias do WIQD selecionados em uma execução controlada antes de habilitar o envio de versão.
Para uma etapa confiável do GitHub Actions, use estas associações de ambiente:
env:
CI_ENABLED: 'true'
M365_TENANT_ID: ${{ vars.M365_TENANT_ID }}
M365_REFRESH_TOKEN: ${{ secrets.M365_REFRESH_TOKEN }}
O Azure Pipelines requer mapeamento explícito env para variáveis secretas. Use estas associações e rejeite macros não resolvidas $(NAME) antes de invocar o WIQD:
env:
CI_ENABLED: 'true'
M365_TENANT_ID: $(M365_TENANT_ID)
M365_REFRESH_TOKEN: $(M365_REFRESH_TOKEN)
Essas são associações de ambiente, não definições completas de pipeline. Para modos de autenticação e verificações específicas do provedor, siga os exemplos do pipeline WIQD.
CI_ENABLED deve ser exatamente minúsculo true; genérico CI=true não é suficiente. Invocar comandos do ciclo de vida diretamente, não wiqd auth login na CI. Essas são credenciais delegadas, não uma identidade somente de aplicativo, e não ignoram MFA, acesso condicional, consentimento ou permissões.
O WIQD não alterna o repositório secreto do pipeline. Quando a autenticação exigir entrada humana ou consentimento, resolva o problema de política ou consentimento e substitua o segredo por meio do procedimento local documentado. Não mude para outra identidade automaticamente.
Criar e validar um candidato
Crie e teste um candidato em seu ambiente WIQD selecionado antes do envio do lançamento. O teste pode usar o mesmo locatário, configuração de ambiente e identidade autorizada do Microsoft 365 que o lançamento; Um ambiente de teste separado é opcional. Mantenha os comandos relacionados no mesmo projeto e estado do ambiente.
Aviso
Se o candidato e o plug-in lançado usarem a mesma identidade de recurso de plug-in, o provisionamento poderá atualizar os recursos usados pelos usuários existentes antes do envio do catálogo ou da aprovação do administrador. Use essa identidade para atualizações candidatas somente quando essas alterações forem autorizadas e o acesso for controlado. Uma identidade de candidato separada é opcional, mas isola as alterações de candidato do plug-in lançado.
Para preparar um candidato:
- Selecione a revisão de origem aprovada e a versão do pacote de plug-ins.
- Se o ambiente selecionado já estiver provisionado, disponibilize seu estado de ambiente estabelecido por meio do mecanismo de persistência segura aprovado. Preserve todos os valores necessários pelo ciclo de vida, não apenas a ID do aplicativo. Não restaure credenciais baixando um arquivo morto do projeto ou cache de autenticação.
- Execute compilações de componentes, testes e validação de plug-in offline.
- Provisione ou atualize o ambiente selecionado, se necessário, para este candidato.
- Se o provisionamento alterar as entradas cobertas pela validação estática, revalide a origem afetada.
- Empacote o projeto.
- Valide profundamente o ZIP gerado exato.
- Mantenha o ZIP, o resultado da validação, a revisão da origem, a versão do pacote, a versão do WIQD e a identidade do ambiente com o registro do candidato.
O exemplo do PowerShell a seguir abrange um candidato que requer provisionamento ou uma atualização para seus recursos de locatário. Execute-o dentro de um trabalho confiável após a autenticação ser configurada. Se o ambiente selecionado já estiver vinculado à identidade e nenhuma atualização de provisionamento for necessária, omita o comando provision. Repita a validação estática somente quando suas entradas forem alteradas. Substitua o caminho e dev o ambiente do projeto pela configuração do candidato. O auxiliar para em erros nativos, JSON malformado ou um envelope malsucedido.
O exemplo grava o JSON .artifacts\validation.json de validação completa como evidência intermediária. Restrinja o acesso e examine o conteúdo para obter informações de locatário, identificadores, URLs e conteúdo confidencial antes de retê-lo ou compartilhá-lo. Higienize as evidências antes do upload; Não carregue o diretório de artefatos automaticamente.
$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false
function Invoke-WiqdJson([string[]]$Arguments) {
$text = & wiqd @Arguments
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = ($text -join "`n") | ConvertFrom-Json
if ($result.status -cne 'success') { throw 'WIQD operation failed.' }
return $result
}
$project = (Resolve-Path .\plugins\contoso).Path
$environment = 'dev'
$artifactDirectory = Join-Path $PWD '.artifacts'
New-Item -ItemType Directory -Path $artifactDirectory -Force | Out-Null
$package = Join-Path $artifactDirectory 'plugin-dev.zip'
$common = @('--path', $project, '--env', $environment, '--json')
Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'static') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'provision') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'static') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'package', '--output', $package) + $common) | Out-Null
if (-not (Test-Path -LiteralPath $package -PathType Leaf)) { throw 'Package output is missing.' }
$validation = Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'deep', '--package-file', $package) + $common)
$validation | ConvertTo-Json -Depth 100 | Set-Content -LiteralPath (Join-Path $artifactDirectory 'validation.json')
A validação profunda envia o ZIP criado para a Biblioteca de Validação de Aplicativos da plataforma e relata suas verificações de pacote. Ele não estabelece o comportamento de tempo de execução, a preparação da conexão, a integridade do serviço remoto ou a aceitação do Partner Center. Ele requer acesso de serviço autenticado e não é um marcar de solicitação de pull offline. A autenticação ausente, uma falha de serviço ou um pacote rejeitado bloqueia o candidato.
O provisionamento normalmente precede o empacotamento, pois grava o arquivo de ambiente selecionado e o que o TEAMS_APP_ID empacotamento consome. Se o ambiente já estiver vinculado à identidade e nenhuma atualização de provisionamento for necessária, omita o comando provisionar e o pacote em relação a esse estado existente. O reprovisionamento usa essa identidade, mas um novo check-out não a preserva automaticamente. Reter com segurança as IDs estáveis entre as execuções; Não publique arquivos de ambiente, arquivos secretos do usuário, caches de autenticação ou todo o espaço de trabalho como artefatos.
Não tente provisionar ou publicar automaticamente após um tempo limite. Inspecione a operação e os recursos existentes antes de autorizar uma nova execução.
Testar e avaliar o candidato implantado
Teste o candidato em todas as experiências de destino, incluindo suas conexões, permissões, habilidades e serviços remotos necessários. A validação de pacote não estabelece que todos os recursos funcionam em runtime.
Para um plug-in que inclui um agente declarativo, adicione um portão de qualidade:
- Identifique o ID do título do componente do agente declarativo implantado. Não substitua a ID do título do catálogo do plug-in autônomo.
- Prepare um arquivo de prompts revisados e um limite de aceitação para tarefas representativas. Mantenha o pacote inalterado ao comparar o candidato com a linha de base.
- Configure a autenticação de conexão de agente do Microsoft 365 da CLI de Avaliação e a aprovação necessária do locatário no executor pretendido. Configure as credenciais do juiz selecionado separadamente e conclua o consentimento de EULA exigido pela CLI de Avaliação fora da CI.
- Corra
wiqd agent evalem relação a esse componente implantado e mantenha o resultado com o candidato. - Bloquear versão se a avaliação falhar, o limite não for atingido ou o executor não puder autenticar.
Este exemplo avalia um agente implantado no evals\contoso espaço de trabalho. Coloque o arquivo de prompts revisados em evals\contoso\evals\prompts.json, relativo à raiz de check-out. O caminho de saída é resolvido em relação a esse workspace. Substitua <deployed-agent-title-id> pela ID do título do componente candidato. O 0.85 limite é um exemplo; escolha a barra de qualidade exigida pelo seu cenário.
$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false
$agentId = '<deployed-agent-title-id>'
$text = wiqd agent eval --path .\evals\contoso --agent-id $agentId --env dev --threshold 0.85 --output .evals\results.json --json
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = ($text -join "`n") | ConvertFrom-Json
if ($result.status -cne 'success') { throw 'Agent evaluation failed.' }
O comando WIQD Eval faz referência a documentos de workspaces somente prompts e IDs de agente explícitas. O tratamento de limite de documentos de fluxo de trabalho de Aval: um erro de limite e uma falha de upstream retornam uma saída diferente de zero, com códigos de erro diferentes em JSON.
Os tokens de atualização do ciclo de vida não autenticam avaliações. A Eval CLI usa sua própria autenticação do Microsoft 365, enquanto o juiz usa credenciais separadas do GitHub Copilot ou do Azure. As fontes do WIQD não fornecem um bootstrap completo de credenciais de avaliação autônoma para executores hospedados arbitrários. Qualifique essa configuração em seu corredor antes de torná-lo um portão automatizado; Se não puder ser executado sem supervisão, exija uma avaliação autorizada e suas evidências, em vez de tratar uma corrida ignorada como sucesso.
wiqd agent eval não é um avaliador de plug-in completo e não avalia habilidades autônomas, conectores raiz ou agentes de mecanismo personalizados. Para esses recursos, mantenha os testes de componente e experiência de destino exigidos por Validar e testar seu plug-in.
Se os testadores precisarem de acesso direto, autorize o público explicitamente e siga o compartilhamento do plugin WIQD. O compartilhamento requer AGENT_SCOPE=shared no arquivo de ambiente selecionado e uma implantação compartilhada correspondente; nomear um ambiente dev não estabelece esse escopo. Não renomeie uma implantação pessoal nem copie suas IDs para ignorar o requisito de compartilhamento.
Enviar uma atualização aprovada para o catálogo de aplicativos da organização
Use um trabalho de versão protegida para enviar uma atualização para o catálogo de aplicativos da organização. O teste candidato não autoriza a mutação de produção ou a aprovação do administrador.
Para lançar uma atualização:
- Aprove a revisão da fonte candidata, a versão do pacote, os resultados da validação, as evidências de avaliação, quando aplicável, e o público-alvo de produção pretendido.
- Disponibilize o estado de ambiente estabelecido do destino de lançamento para o trabalho. Preserve sua identidade de plug-in existente para uma atualização em vez de criar um novo registro de aplicativo em cada execução.
- Se a versão usar uma configuração de ambiente ou identidade de recurso de plug-in diferente do candidato testado, repita o provisionamento, o empacotamento, a validação e os testes afetados para esse destino.
- Se apenas a identidade autenticada do Microsoft 365 for alterada, verifique seu locatário, consentimento delegado, permissões e acesso às operações necessárias. Uma alteração de identidade de autenticação por si só não requer a recriação do pacote.
- Confirme se o pacote e a implantação do destino de lançamento passaram nos testes aplicáveis. Se a configuração, o pacote e o estado de implantação efetivos não forem alterados, reutilize a evidência candidata sem repetir a validação de destino.
- Envie o projeto provisionado para o destino de lançamento por meio do WIQD e registre o resultado.
- Entregue o envio ao administrador para aprovação e, em seguida, verifique a entrada do catálogo de aplicativos atualizada, a versão do pacote, a disponibilidade e a experiência do usuário.
Depois de validar o destino da versão e autorizar o envio, esse comando publica o plug-in do projeto selecionado no catálogo de aplicativos da organização.
prod é um exemplo de nome de ambiente; Use seu ambiente de liberação configurado, que pode ser o mesmo ambiente usado para testes de candidatos.
$ErrorActionPreference = 'Stop'
$PSNativeCommandUseErrorActionPreference = $false
$text = wiqd plugin publish --path .\plugins\contoso --env prod --json
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$result = ($text -join "`n") | ConvertFrom-Json
if ($result.status -cne 'success') { throw 'Plugin submission failed.' }
Manter o resultado da publicação com o registro de lançamento.
wiqd plugin publish aceita um projeto e um ambiente, não um ZIP criado anteriormente por meio do --package-file. A validação profunda de um ZIP capturado não prova que a publicação envia esses bytes exatos. Mantenha a origem aprovada e o estado do ambiente fixos, qualifique o comportamento de publicação de sua versão WIQD fixada e verifique a versão enviada resultante. Não descreva isso como um fluxo de trabalho imutável de promoção ZIP.
O guia de plug-ins WIQD distingue esses resultados:
| Operação | Resultado | Ação restante |
|---|---|---|
wiqd plugin publish |
Envio para o catálogo de aplicativos da organização do locatário | Aprovação do administrador antes que os usuários possam descobrir o plug-in |
wiqd plugin share |
Acesso direto para usuários nomeados ou para o locatário | Verifique o público-alvo, a instalação e as conexões autorizadas |
wiqd plugin package seguido de envio do Partner Center |
Pacote preparado para um processo de repositório público | O envio, a certificação e a publicação do Partner Center não são automatizados pelo WIQD |
O WIQD não documenta um comando de registro de plug-in slot-promotion ou rollback. Estabeleça o procedimento de substituição ou recuperação com suporte antes do lançamento e não presuma que uma atualização de pacote restaura serviços ou permissões operados separadamente. Siga Melhore e atualize seu plug-in para verificação de distribuição e planejamento de recuperação.
Reter evidências e limpar candidatos
Mantenha as evidências necessárias para rastrear uma atualização aprovada sem expor as credenciais de locatário ou dados de avaliação a leitores não autorizados.
- Retenha a revisão de origem aprovada, a versão WIQD, as identidades e versões dos pacotes, os resultados de validação e avaliação limpos e o status de publicação.
- Restrinja o acesso aos resultados da avaliação porque solicitações e respostas podem conter dados organizacionais.
- Verifique a atualização de produção antes de remover uma implantação candidata.
- Se um candidato temporário tiver uma identidade de recurso separada e não for mais necessário, autorize sua exclusão explicitamente. Use o comando de exclusão do plugin WIQD documentado apenas para o ambiente e a identidade desse candidato.
Não faça da limpeza destrutiva um estágio incondicional do pipeline ou exclua a identidade do plug-in lançado como parte da limpeza de candidatos. Se o teste e o lançamento usarem a mesma identidade, não o exclua como um candidato temporário.
Conteúdo relacionado
- Configuração e autenticação do pipeline WIQD
- Empacotar seu plug-in do Microsoft 365 Copilot
- Compartilhamento de plug-in de Ferramentas de Desenvolvimento do Work IQ
- Publicar ou compartilhar seu plug-in do Microsoft 365 Copilot
- Publicar seu plug-in em sua organização
- Disponibilizar seu plug-in e controlar o acesso