將 Work IQ 開發工具整合至 Microsoft 365 Copilot 外掛程式 CI/CD

使用 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 管線pwsh:步驟中執行。 請勿將生命週期或評估認證插入任一提供者不受信任的提取要求工作。

來源驗證會檢查已儲存的宣告式代理程式來源,並需要可讀的外掛程式專案 JSON 檔案。 它不會完全驗證最上層的應用程式資訊清單架構、獨立技能、根連接器或參考的 API 和 OpenAPI 內容。 僅技能或僅連接器外掛程式無法報告沒有宣告式代理程式來源涵蓋範圍,並不是每個元件都有效。 檢閱傳回的已檢查檔案清單和結果。

--mode source明確指定離線工作。 裸機 wiqd plugin validate 預設為 package,會上傳已建立的 ZIP,而且可能必須登入。 請參閱 WIQD 驗證命令參考。

如需其他離線發佈整備檢查,請執行下列命令並套用相同的結束程式碼和 JSON 檢查:

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

此檢查不會提交外掛程式。 系統會停用執行階段和網路檢查,且當沒有代理程式存在時,會略過宣告式代理程式階段。 離線檢查不會取代組建套件的驗證,也不會在目標 Microsoft 365 體驗中進行測試。

設定信任工作的驗證

佈建、封裝驗證和發佈需要提取要求工作所沒有的認證。 請與租用戶系統管理員檢閱記載的驗證模式,確認所選 WIQD 版本中的支援,然後只將認證插入信任的步驟。

警告

請勿使用使用者名稱/密碼驗證。 確認所選 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明確對應秘密變數。 在叫用 WIQD 之前,請使用這些繫結並拒絕未解析的 $(NAME) 巨集:

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 範例涵蓋需要佈建或更新其租用戶資源的候選項目。 設定驗證之後,請在信任的作業內執行它。 如果選取的環境已是身分識別繫結,而且不需要佈建更新,請省略 provision 命令。 只有當來源的輸入已變更時,才重複來源驗證。 以您的候選組態取代專案路徑和 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 該封裝會取用。 如果環境已受身分識別繫結且不需要佈建更新,請省略針對現有狀態的佈建命令和封裝。 重新佈建會使用該身分識別,但全新結帳不會自動保留它。 在執行之間安全地保留穩定的 ID;請勿將環境檔案、使用者密碼檔案、驗證快取或整個工作區發佈為成品。

逾時之後,請勿自動重試佈建或發佈。 在授權重新執行之前,請檢查現有的作業和資源。

測試和評估已部署的候選項目

在每個目標體驗中測試候選人,包括其所需的連接、權限、技能和遠程服務。 封裝驗證無法確定每個功能都能在執行階段運作。

對於包含宣告式代理程式的外掛程式,請新增品質閘道:

  1. 識別已部署的宣告式代理程式元件的標題識別碼。 請勿取代獨立外掛程式的目錄標題識別碼。
  2. 為代表性工作準備已檢閱的提示檔案和接受閾值。 在將候選項目與基線進行比較時,請保持套件不變。
  3. 在預期的執行器上設定評估 CLI 的 Microsoft 365 代理程式連線驗證和必要的租用戶核准。 個別設定所選法官的認證,並在 CI 外部完成評估 CLI 所需的 EULA 同意。
  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 命令參考文件僅提示工作區和明確的代理程式識別碼。 評估工作流程文件閾值處理:閾值遺漏和上游失敗都會傳回非零結束,並在 JSON 中具有不同的錯誤代碼。

生命週期重新整理權杖不會驗證評估。 評估 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 接受專案和環境,而不是先前透過 建置的 --package-fileZIP。 驗證擷取的 ZIP 並不能證明發佈提交了這些確切的位元組。 保持核准的來源與環境狀態不變、限定釘選 WIQD 發行的發佈行為,並驗證結果所提交的版本。 請勿將此描述為一成不變的 ZIP 升級工作流程。

WIQD 為這些發佈路由提供個別的命令:

Operation 結果 剩餘動作
wiqd plugin publish 提交至租用戶組織應用程式目錄 使用者探索外掛程式之前的系統管理員核准
wiqd plugin share 具名使用者或租用戶的直接存取權 驗證授權的對象、安裝和連線
wiqd publish pc 針對外掛程式套件 合作夥伴中心供應項目準備、上傳、授權提交和狀態追蹤 Microsoft 控制認證與即時發佈

如需公開提交,請 遵循使用 WIQD 發佈至合作夥伴中心。 Marketplace 驗證與本文中使用的核心管線認證不同。 自動提交需要明確授權和受信任的持續執行器,具有先前建立的互動式賣方工作階段,並可存取其受保護的作業系統憑證存放區。 Marketplace 發佈不支援 Clean-runner、service-principal 和工作負載身分識別驗證;當不符合這些執行器需求時,請使用經過驗證的運算子。

WIQD 不會記錄外掛程式、登錄、位置升級或復原命令。 在發行之前建立支援的取代或復原程序,而且不要假設套件更新會還原個別操作的服務或權限。 追蹤: 改善和更新您的外掛程式 ,以進行推出驗證和復原規劃。

保留證據並清除候選項目

保留所需的辨識項以追蹤已核准的更新,而不會將租用戶認證或評估資料公開給未經授權的讀取者。

  1. 保留核准的來源修訂、WIQD 版本、套件身分識別和版本、清理過的驗證和評估結果,以及發佈狀態。
  2. 限制評估結果存取,因為提示和回應可以包含組織資料。
  3. 移除候選部署之前,請先確認生產更新。
  4. 如果暫存候選項目具有個別的資源身分識別且不再需要,請明確授權其刪除。 僅針對該候選者的環境和身分識別使用記載的 WIQD 外掛程式刪除命令 。

不要讓破壞性清理成為無條件的管線階段,或刪除已發行外掛程式的身分識別作為候選清理的一部分。 如果測試和發行使用相同的身分識別,請勿將其刪除為暫時候選項目。