Интеграция средств разработчика Work IQ в подключаемый модуль CI / CD подключаемого модуля Microsoft 365 Copilot

Используйте средства разработчика Work IQ (WIQD) для добавления проверок непрерывной интеграции и непрерывной доставки (CI/CD) в ваш проект подключаемого модуля Microsoft 365 Copilot. В этой статье недорогие проверки запросов на вытягивание отделяются от тестирования аутентифицированных кандидатов и утвержденной отправки релиза.

Это руководство предназначено для разработчиков, интегрирующих WIQD в существующую систему CI/CD. В нем описываются требования и последовательности команд, а не настройка полноценной среды CI/CD. Ожидается, что вы настроите задания, триггеры, средства запуска, секреты, утверждения и обработку артефактов вашей системы, а также интегрируете примеры в эту систему. Прежде чем начать, подготовьте средство выполнения, среды и учетные данные, перечисленные в разделе "Предварительные требования".

Местом назначения выпуска является каталог приложений организации вашего клиента, где администратор утверждает отправленные подключаемые модули, прежде чем пользователи смогут их обнаружить. Прямой доступ — это отдельный метод распространения. Этот рабочий процесс не автоматизирует утверждение администратором. Для подачи заявок в Центре общедоступных партнеров используется отдельный wiqd publish pc рабочий процесс.

Необходимые условия

Чтобы запускать команды WIQD в существующих конвейерах или рабочих процессах, убедитесь, что у вас есть:

  • Проект подключаемого модуля WIQD с управлением исходным кодом с файлами жизненного цикла, тестами компонентов и конфигурацией несекретной среды. См. раздел "Создание подключаемого модуля с помощью средств разработчика для Work IQ".
  • Существующая система CI/CD с извлечением источника, средствами запуска, защищенными секретами и средствами контроля утверждения выпусков. Вы знаете, как настроить задания, триггеры и обработку артефактов в этой системе.
  • Node.js 24.15.0 или более поздней версии и точно утвержденный выпуск WIQD на бегунке. Следуйте инструкциям по установке WIQD и запишите установленную версию с помощью wiqd --version.
  • PowerShell 7 для использования примеров команд из этой статьи.
  • Настроенная среда WIQD для команд, поддерживаемых клиентом. Следуйте настройкам среды WIQD для подготовки файлов среды. Отдельные среды тестирования и рабочая среды или клиенты Microsoft 365 не являются обязательными, а не обязательными условиями. dev, stagingи prod являются условными именами, а не гарантиями относительно клиента или области развертывания.
  • Удостоверение Microsoft 365, авторизованное для выбранных операций подготовки, проверки пакетов и публикации с требуемым делегированным согласием. Предоставляйте только те разрешения, которые необходимы для этих операций, как указано в согласии WIQD и ограничениях ресурсов.
  • Для оценок декларативного агента — подготовленный целевой объект, проверенный файл запросов, утвержденный порог качества и отдельно настроенная проверка подлинности оценки и принятие EULA. Следуйте руководству по оценке агента WIQD для получения подробных сведений о настройке и требованиях. Оценка агента не требуется для плагинов без агентов, таких как плагины только для навыков или только для инструментов; Сохраните применимые тесты компонентов и целевого опыта.

Следуйте документации поставщика CI/CD для настройки платформы и создания рабочих процессов. Например, см. статьи Создание первого конвейера Azure или Реализация GitHub Actions.

Выбор сценариев конвейера

Настройте отдельные задания, чтобы ненадежные изменения не могли получить доступ к учетным данным развертывания или отправить выпуск.

Сценарий Когда бежать Операции WIQD Ворота
Проверка запроса пулла При открытии запроса на вытягивание и после каждого обновления предлагаемых изменений Автономная проверка источника; Необязательная готовность к автономной публикации Проверки источника пройдены, с записью их пределов покрытия
Сборка и тестирование кандидатов Утвержденные изменения в доверенной ветви или авторизованный запуск вручную Подготовка подключаемого модуля в выбранной среде, сборка и проверка пакета, тестирование и оценка применимых агентов Пройдены проверки пакета, компонента, опыта и качества
Отправка выпуска Утвержденный кандидат и разрешение на освобождение Подтвердите конфигурацию выпуска и проверенный пакет, а затем опубликуйте в каталоге приложений организации Успешная отправка с последующим утверждением администратором и проверкой развертывания

Сохраняйте сборку и тесты компонентов проекта. WIQD не предоставляет универсальную команду компиляции для каждого плагина или обновления удаленных сервисов, на которые ссылается ваш плагин.

Если вы адаптируете руководство по настройке конвейера WIQD к проекту плагина, используйте последовательности команд из wiqd plugin этой статьи. Примеры жизненного цикла этого руководства wiqd agent предназначены для проектов агентов, а не для автономных проектов подключаемых модулей.

Добавьте недорогие проверки запросов на вытягивание

Выполняйте автономную проверку без использования учетных данных Microsoft 365. Эти проверки не подготавливают ресурсы, не вызывают агента и ничего не отправляют в реестр.

Чтобы добавить проверку источника в существующее задание:

  1. Ознакомьтесь с предложенным исходным кодом и установите утвержденный выпуск WIQD.
  2. Запустите применимые тесты компонентов вашего проекта.
  3. Запустите следующий шаг WIQD, заменив .\plugins\contoso его путем к проекту и dev предполагаемым контекстом среды.
  4. Требование собственного успеха выхода и оболочки успешного завершения JSON перед прохождением задания.

Этот шаг GitHub Actions проверяет поверхность исходного кода декларативного агента в отдельном проекте подключаемого модуля:

- name: Validate plugin source
  shell: pwsh
  run: |
    $ErrorActionPreference = 'Stop'
    $PSNativeCommandUseErrorActionPreference = $false
    $text = wiqd plugin validate --path .\plugins\contoso --env dev --mode source --json
    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
    $result = ($text -join "`n") | ConvertFrom-Json
    if ($result.status -cne 'success') { throw 'Plugin source validation failed.' }

Один и тот же текст PowerShell может выполняться на шаге Azure Pipelinespwsh:. Не внедряйте учетные данные жизненного цикла или оценки в ненадежное задание запроса на вытягивание любого поставщика.

Проверка источника проверяет сохраненный исходный код декларативного агента и требует читаемых JSON-файлов проекта плагина. Он не проверяет полностью схему манифеста приложения верхнего уровня, автономные навыки, корневые соединители или указанное содержимое API и OpenAPI. Плагин только для навыков или только для соединителя не может сообщать об охвате источника декларативного агента, а не о том, что каждый компонент действителен. Просмотрите возвращенный список проверенных файлов и полученные результаты.

Явно укажите --mode source для автономного задания. Голое wiqd plugin validate значение по умолчанию — package, при котором загружается уже созданный ZIP-архив и может требоваться вход в систему. См. справочник по командам проверки WIQD.

Для дополнительной автономной проверки готовности к публикации запустите следующую команду и примените те же проверки exit-code и JSON:

wiqd plugin publish --path .\plugins\contoso --env dev --dry-run --no-runtime --no-network --json

Эта проверка не отправляет подключаемый модуль. Проверки среды выполнения и сети отключены, а этапы декларативного агента пропускаются при отсутствии агента. Ни автономная проверка не заменяет проверку собранного пакета или тестов в целевом интерфейсе Microsoft 365.

Настройка проверки подлинности для доверенных заданий

Подготовка, проверка пакета и публикация требуют учетных данных, которых нет у задания запроса на вытягивание. Просмотрите задокументированные режимы проверки подлинности вместе с администратором клиента, подтвердите поддержку в выбранном выпуске WIQD, а затем вводите учетные данные только в доверенные этапы.

Предупреждение

Не используйте проверку подлинности по имени пользователя и паролю. Используйте режим refresh-token после подтверждения поддержки в выбранном выпуске WIQD. Используйте режим пароля только в том случае, если это явно разрешено политикой безопасности организации. Не ослабляйте требования MFA или условного доступа для успешного конвейера. Маркеры обновления также являются конфиденциальными учетными данными и требуют защищенного хранилища и ограниченного доступа.

Важно

Руководство по проверке подлинности конвейера WIQD помечает проверку подлинности маркеров обновления как еще не выпущенную или полностью проверенную. Примеры токенов обновления — это руководство по интеграции, а не подтвержденный путь проверки подлинности, готовый к рабочей среде. Подтвердите доступность выпуска, утверждение безопасности, а также динамические проверки согласия и работы для точной версии WIQD, выбранной перед использованием этих примеров.

Мода Обязательные входные данные процесса Входные данные, которые нужно удалить
Маркер обновления CI_ENABLED=true, GUID клиента в M365_TENANT_IDи защищенном M365_REFRESH_TOKEN Удаление обоих M365_ACCOUNT_NAME и M365_ACCOUNT_PASSWORD, даже пустых определений
Имя пользователя и пароль CI_ENABLED=true, защищено M365_ACCOUNT_NAMEи защищено M365_ACCOUNT_PASSWORD Удалить M365_REFRESH_TOKEN; M365_TENANT_ID не является обязательным в этом режиме

Для проверки подлинности токена обновления:

  1. Выполните частную локальную начальную загрузку при проверке подлинности конвейера WIQD.
  2. Поместите полученный маркер непосредственно в утвержденное секретное хранилище конвейера. Не фиксируйте его, передавайте как командный аргумент, не включайте его в журналы или артефакты.
  3. Сопоставьте клиент и маркер с доверенным командным процессом.
  4. Проверьте выбранный выпуск WIQD, удостоверение, бегун и необходимые операции в управляемом запуске, прежде чем включить отправку выпуска.

Для доверенного шага GitHub Actions используйте следующие привязки среды:

env:
  CI_ENABLED: 'true'
  M365_TENANT_ID: ${{ vars.M365_TENANT_ID }}
  M365_REFRESH_TOKEN: ${{ secrets.M365_REFRESH_TOKEN }}

Для Azure Pipelines требуется явное env сопоставление секретных переменных. Используйте следующие привязки и отклоните неразрешенные $(NAME) макросы перед вызовом WIQD:

env:
  CI_ENABLED: 'true'
  M365_TENANT_ID: $(M365_TENANT_ID)
  M365_REFRESH_TOKEN: $(M365_REFRESH_TOKEN)

Это привязки среды, а не полные определения конвейеров. Как для режимов аутентификации, так и для проверок, специфичных для поставщика, следуйте примерам конвейера WIQD.

CI_ENABLED должен быть в точности строчными ; trueобщего CI=true недостаточно. Вызывать команды жизненного цикла напрямую, а не wiqd auth login в CI. Это делегированные учетные данные, а не удостоверение только приложения, и они не обходят MFA, условный доступ, согласие или разрешения.

WIQD не вращает секретное хранилище конвейера. Если для проверки подлинности требуется вход человека или согласие, устраните проблему политики или согласия и замените секрет с помощью задокументированной локальной процедуры. Не переключайтесь на другое удостоверение автоматически.

Создание и проверка кандидата

Создайте и протестируйте кандидат в выбранной вами среде WIQD перед отправкой релиза. Тестирование может использовать тот же клиент, конфигурацию среды и авторизованное удостоверение Microsoft 365, что и выпуск. Отдельная среда тестирования необязательна. Сохраняйте связанные команды в одном состоянии проекта и среды.

Предупреждение

Если кандидат и выпущенный подключаемый модуль используют один и тот же идентификатор ресурса подключаемого модуля, подготовка может обновить ресурсы, используемые существующими пользователями, до отправки каталога или утверждения администратором. Используйте это удостоверение для обновлений кандидатов только в том случае, если эти изменения разрешены и доступ к ним контролируется. Отдельный идентификатор кандидата не является обязательным, но изолирует изменения-кандидаты от выпущенного подключаемого модуля.

Подготовка кандидата:

  1. Выберите утвержденную версию исходного кода и версию пакета плагина.
  2. Если выбранная среда уже подготовлена, предоставьте доступ к ее установленному состоянию с помощью утвержденного вами механизма безопасного сохраняемости. Сохранение всех значений, необходимых для жизненного цикла, а не только идентификатора приложения. Не восстанавливайте учетные данные путем загрузки архива проекта или кэша проверки подлинности.
  3. Запускайте сборки компонентов, тесты и автономную проверку исходного кода.
  4. Подготовьте или обновите выбранную среду, если это необходимо для этого кандидата.
  5. Если при подготовке изменяются входные данные, охватываемые проверкой источника, повторно проверьте затронутый источник.
  6. Упакуйте проект.
  7. Проверьте точно созданный ZIP-архив в режиме пакета.
  8. Сохраните ZIP-архив, результат проверки, редакцию исходного кода, версию пакета, версию WIQD и удостоверение среды с записью-кандидатом.

Следующий пример PowerShell охватывает кандидата, которому требуется подготовка или обновление ресурсов клиента. Запустите его в доверенном задании после настройки проверки подлинности. Если выбранная среда уже привязана к удостоверению и обновление подготовки не требуется, пропустите команду подготовки. Повторная проверка источника только после изменения входных данных. Замените путь проекта и dev среду своей конфигурацией кандидатов. Вспомогательная функция останавливается на исходных ошибках, искаженном формате JSON или неудачном конверте.

В примере полная проверка JSON записывается в .artifacts\validation.json качестве промежуточного свидетельства. Ограничьте доступ и просматривайте полезные данные для сведений об арендаторе, идентификаторов, URL-адресов и конфиденциального содержимого, прежде чем сохранить его или предоставить общий доступ. Очистите доказательства перед загрузкой; Не отправляйте каталог артефакта автоматически.

$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', 'source') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'provision') + $common) | Out-Null
Invoke-WiqdJson (@('plugin', 'validate', '--mode', 'source') + $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', 'package', '--package-file', $package) + $common)
$validation | ConvertTo-Json -Depth 100 | Set-Content -LiteralPath (Join-Path $artifactDirectory 'validation.json')

В режиме пакета пакет отправляет уже созданный ZIP-файл в службу проверки пакетов платформы и сообщает о своих результатах. Он не создает ZIP-архив и не выполняет автоматический вход, не устанавливает поведение среды выполнения, готовность подключения, работоспособность удаленной службы или принятие Центром партнеров. Для этого требуется авторизованный доступ к службе, а не автономная проверка запроса на вытягивание. Отсутствие проверки подлинности, сбой службы или отклоненный пакет блокируют кандидата.

Подготовка обычно предшествует упаковке, так как при ней записывается выбранный файл среды, а TEAMS_APP_ID потребляемый пакетом файл. Если среда уже привязана к удостоверению и обновление подготовки не требуется, пропустите команду подготовки и пакет в этом существующем состоянии. При повторной подготовке используется это удостоверение, но новое извлечение не сохраняет его автоматически. Надежное хранение стабильных идентификаторов между запусками; Не публикуйте файлы среды, секретные файлы, кэши проверки подлинности или всю рабочую область как артефакты.

Не пытайтесь автоматически повторить подготовку или публикацию после тайм-аута. Перед авторизацией повторного запуска проверяйте существующую операцию и ресурсы.

Тестирование и оценка развернутого кандидата

Протестируйте кандидата во всех целевых интерфейсах, включая необходимые подключения, разрешения, навыки и удаленные службы. Проверка пакета не позволяет подтвердить, что все возможности работают во время выполнения.

Для подключаемого модуля, содержащего декларативный агент, добавьте шлюз качества:

  1. Определите идентификатор заголовка развернутого компонента декларативного агента. Не подставляйте идентификатор названия каталога автономного подключаемого модуля.
  2. Подготовьте проверенный файл запросов и порог приемлемости для показательных задач. При сравнении кандидата с базовым уровнем оставьте набор неизменным.
  3. Настройте проверку подлинности подключения к агенту Microsoft 365 в интерфейсе командной строки Eval и обязательное утверждение клиента для целевого средства запуска. Настройте полномочия выбранного судьи отдельно и заполните необходимое согласие EULA Eval CLI за пределами CI.
  4. Используйте wiqd agent eval этот развернутый компонент и сохраните результат с кандидатом.
  5. Блокировка выпуска, если оценка не пройдена, пороговое значение не достигнуто или средство выполнения не может пройти проверку подлинности.

В этом примере оценивается развернутый агент из evals\contoso рабочей области. Поместите файл проверенных запросов в , evals\contoso\evals\prompts.jsonотносительно корня извлечения. Выходной путь разрешается относительно этой рабочей области. Замените <deployed-agent-title-id> его идентификатором названия компонента-кандидата. Пороговое значение является примером. Выберите 0.85 шкалу качества, требуемую для вашего сценария.

$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.' }

Команда WIQD Eval ссылается на документы, рабочие пространства только для запросов и явные идентификаторы агентов. Рабочий процесс Eval документирует обработку пороговых значений: промах порога и вышестоящий сбой возвращают ненулевой выход с разными кодами ошибок в JSON.

Маркеры обновления жизненного цикла не проверяют подлинность оценок. Eval CLI использует собственную проверку подлинности Microsoft 365, в то время как судья использует отдельные учетные данные GitHub Copilot или Azure. Источники WIQD не предоставляют полной автоматической загрузки оценки учетных данных для произвольных размещенных бегунков. Квалифицируйте эту установку на своем бегуне, прежде чем сделать его автоматическими воротами; Если он не может быть запущен без присмотра, требуйте авторизованной оценки и ее доказательств, а не относитесь к пропущенному прохождению как к успеху.

wiqd agent eval не является оценщиком всего подключаемого модуля и не оценивает отдельные навыки, корневые соединители или агентов пользовательского движка. Для этих возможностей сохраните тесты компонента и целевого интерфейса, необходимые для проверки и тестирования подключаемого модуля.

Если тестировщикам нужен прямой доступ, явно авторизуйте аудиторию и следите за обменом плагинами WIQD. Для совместного использования требуется AGENT_SCOPE=shared выбранный файл среды и соответствующее общее развертывание; именование среды dev не устанавливает эту область. Не изменяйте метки личных развертываний и не копируйте их идентификаторы, чтобы обойти требование общего доступа.

Отправка утвержденного обновления в каталог приложений организации

Используйте защищенное задание выпуска для отправки обновления в каталог приложений организации. Тестирование кандидатов не санкционирует производственную мутацию или одобрение администратора.

Выпуск обновления:

  1. Утвердите редакцию исходного кода, версию пакета, результаты проверки, данные оценки (если применимо) и предполагаемую рабочую аудиторию.
  2. Сделайте установленное состояние среды целевого объекта выпуска доступным для задания. Сохраняйте существующий идентификатор подключаемого модуля для обновления, а не создавайте новую регистрацию приложения при каждом запуске.
  3. Если в выпуске используется конфигурация среды или идентификатор ресурса подключаемого модуля, отличный от тестируемого кандидата, повторите затронутые процессы подготовки, упаковки, проверки и тестирования для этого целевого объекта.
  4. Если изменяется только удостоверение Microsoft 365, прошедшее проверку подлинности, проверьте его клиента, делегированное согласие, разрешения и доступ к необходимым операциям. Одно только изменение удостоверения проверки подлинности не требует повторной сборки пакета.
  5. Убедитесь, что пакет и развертывание для целевого выпуска прошли применимые тесты. Если действующая конфигурация, пакет и состояние развертывания не изменились, повторно используйте свидетельство-кандидат без повторной целевой проверки.
  6. Отправьте подготовленный проект для целевого выпуска через WIQD и запишите результат.
  7. Передайте отправку администратору на утверждение, а затем проверьте обновленную запись каталога приложений, версию пакета, доступность и впечатления от использования.

После проверки целевого выпуска и авторизации отправки эта команда публикует подключаемый модуль выбранного проекта в каталоге приложений организации. prod является примером имени окружения; Используйте настроенную среду выпуска, которая может быть той же средой, которая использовалась для тестирования кандидатов.

$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.' }

Сохраните результат публикации вместе с записью о выпуске.

wiqd plugin publish принимает проект и среду, а не ранее созданный ZIP-архив с помощью --package-file. Проверка захваченного ZIP-файла не доказывает, что публикация отправляет именно эти байты. Сохраняйте утвержденный источник и состояние среды фиксированными, уточняйте поведение при публикации закрепленного выпуска WIQD и проверяйте полученную отправленную версию. Не описывайте это как неизменяемый рабочий процесс продвижения по ZIP.

WIQD предоставляет отдельные команды для этих маршрутов распространения:

Операция Результат Оставшееся действие
wiqd plugin publish Отправка в каталог приложений организации клиента Утверждение администратором для обнаружения подключаемого модуля пользователями
wiqd plugin share Прямой доступ для именованных пользователей или клиента Проверка авторизованной аудитории, установки и подключений
wiqd publish pc для пакета подключаемого модуля Подготовка предложения в Центре партнеров, отправка, авторизованная отправка и отслеживание состояния Средства сертификации и динамической публикации средств Майкрософт

Для публичного представления следуйте инструкциям в Центре партнеров с WIQD. Проверка подлинности Marketplace отделена от основных учетных данных конвейера, используемых в этой статье. Для автоматической отправки требуется явная авторизация и доверенное постоянное средство выполнения с ранее созданным интерактивным сеансом продавца и доступом к защищенному хранилищу учетных данных операционной системы. Проверка подлинности чистого средства запуска, субъекта-службы и удостоверения рабочей нагрузки не поддерживаются для публикации в Marketplace. Используйте аутентифицированный оператор, если эти требования к средству выполнения не выполняются.

WIQD не документирует команду продвижения или отката слота реестра плагинов. Установите поддерживаемую процедуру замены или восстановления до выпуска и не предполагайте, что обновление пакета восстанавливает отдельно управляемые службы или разрешения. Следуйте инструкциям в статье "Улучшение и обновление подключаемого модуля " для проверки развертывания и планирования восстановления.

Сохраняйте доказательства и удаляйте кандидатов

Сохраняйте доказательства, необходимые для отслеживания утвержденного обновления, без раскрытия учетных данных клиента или данных оценки неавторизованным читателям.

  1. Сохранение утвержденной редакции исходного кода, выпуска WIQD, идентификаторов и версий пакетов, очищенных результатов проверки и оценки, а также состояния публикации.
  2. Ограничьте доступ к результатам оценки, так как запросы и ответы могут содержать данные организации.
  3. Перед удалением развертывания-кандидата проверяйте производственное обновление.
  4. Если временный кандидат имеет отдельное удостоверение ресурса и больше не нужен, авторизуйте его удаление явным образом. Используйте задокументированную команду удаления плагина WIQD только для среды и личности этого кандидата.

Не делайте деструктивную очистку безусловным этапом конвейера и не удаляйте удостоверение выпущенного плагина как часть очистки кандидатов. Если в тестировании и выпуске используется одно и то же удостоверение, не удаляйте его в качестве временного кандидата.