使用 azd 擴展連接 GitHub Copilot 雲端代理與 Azure MCP Server

使用 Azure Developer CLI （azdazure.coding-agent）擴充功能，讓 GitHub Copilot 雲端代理擁有安全且有範圍的 Azure 存取權限，並使用受管理身份。延伸模組會建立受控識別、設定同盟認證，並在存放庫中設定 GitHub Actions 工作流程。

請參閱擴充功能概觀，以瞭解擴充功能如何新增至 azd。

先決條件

安裝 Azure 開發人員 CLI （azd）。請參閱安裝說明。
Azure 訂用帳戶，可讓您建立資源群組和受控識別。
這是你啟用的 GitHub 倉庫的本地複製品，讓 Copilot 雲端代理使用。
存放庫權限：
- 更新 copilot GitHub 環境。
- 設定 Copilot 雲端代理設定。
- 將變更推送至 .github/workflows 資料夾。
儲存庫需要至少一個已設定的 Git 遠端（此為聯合身份驗證所需）。

安裝或升級 Copilot 雲端代理擴充套件

首次安裝

azd extension install azure.coding-agent

升級至最新版本

azd extension upgrade azure.coding-agent

確認它是否已安裝：
```
azd extension list --installed
```
您應該在列表中看到 azure.coding-agent 。

使用 Copilot 雲端代理擴充功能

Copilot 雲端代理擴充功能透過管理身份自動化配置 Copilot 雲端代理的 Azure 存取權限。您還需要執行一些手動步驟才能完成設定。

啟用 Azure 存取

在本機儲存庫目錄的根目錄內，執行下列命令：
```
azd coding-agent config
```
依照螢幕上的提示完成擴充功能工作流程。

在設定期間，擴充功能：
- 建立（或重複使用）資源群組。
- 建立 Azure 受控識別。
- 將 [讀取者] 角色指派給範圍為資源群組的身分識別。
- 建立將 GitHub 存放庫連結至受控識別的同盟認證。
- 新增（或更新） copilot-setup-steps.yml 工作流程和相關資產。
- 引導您完成 copilot 環境的 GitHub 環境設定。

驗證設定（選用）

列出已建立（或更新）資源群組中的受控識別：
```
az identity list --resource-group <resource-group-name>
```
在 GitHub 中，開啟設定>環境>Copilot環境，並確認引用管理識別的同盟認證項目，主體發行者應顯示為 GitHub。

設定 Copilot 雲端代理程式的 Azure MCP 伺服器

azd coding-agent擴充套件會為分支建立拉取請求，其中包含位於origin/azd-enable-copilot-coding-agent-with-azure的新 GitHub 工作流程檔案。如果您想要在分支中使用 main Azure MCP 伺服器連線，請合併此 PR。

主控台的拉取請求描述和擴充功能的輸出日誌都包含一個 JSON 設定片段，可以用來設定 Copilot 雲端代理的 Azure MCP 伺服器：
```
{
    "mcpServers": {
        "Azure": {
            "type": "local",
            "command": "npx",
            "args": [
                "-y",
                "@azure/mcp@latest",
                "server",
                "start"
            ],
            "tools": [
                "*"
            ]
        }
    }
}
```
若要設定 Azure MCP 伺服器，請移至存放庫的 [ 設定 ] 頁面。
在左側導覽列中選取 Copilot>雲端代理程式。
將 PR 中的 JSON 程式碼片段貼到 MCP 設定 方塊中，然後選取 [儲存 MCP 設定]。

測試 Copilot 雲端代理擴充功能

導覽至 GitHub 中的存放庫。
選取右上角導覽列上的 開啟客服專員面板 圖示。
在飛出視窗面板中，選取您用於 azd 命令的存放庫和分支。如果您將產生的提取要求合併到 main中，請選取 main。
輸入一個明確指示 Copilot 雲端代理使用你設定的 Azure MCP 伺服器的提示，例如：
```
Use the Azure MCP Server to list the resource groups in my subscription.
Do not traverse or analyze the repository at all. Use only the Azure MCP Server.
```
按下 Enter 鍵執行提示，並指示 Copilot 雲端代理建立並執行新任務。

備註

你也可以在快顯面板中選取該分支，在 main 以外的分支上執行 Copilot 雲端代理程式工作。
選取面板底部顯示的任務，以導覽至任務詳細資料頁面。
查看輸出內容，即可看到 Copilot 雲端代理程式：
- 啟動 Azure MCP 伺服器：
- 呼叫各種工具來收集 Azure 資源的相關資訊：
- 在最終輸出中顯示資源群組：

設定受控識別的許可權

azd coding-agent延伸模組會建立 Azure 受控身份識別，供 Azure MCP 伺服器用來存取您的資源。此設定允許你為受管理身份指派不同角色，以控制 Azure MCP 伺服器的能力與權限。

根據預設，擴充功能只會將 Reader 角色指派給資源群組範圍。如果代理需要更多功能，請指派其他角色或擴大範圍。請參閱內建角色。

例如，若要在 Contributor 資源群組範圍指派角色：

az role assignment create --assignee <principal-id-or-client-id> --role Contributor --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>

故障排除

以下各節重點介紹了您可能遇到的常見問題。

未設定 git 遠端儲存庫

新增遠端，以便產生聯合認證：

git remote add origin <https://github.com/<your-org>/<your-repo>.git>
git fetch origin

必須具有存放庫的管理員權限

為 Copilot 雲端代理設定 GitHub 倉庫需要管理員權限。沒有這些權限，你無法更新 Copilot 環境以使用受管理身份憑證，或更新儲存庫的 MCP 設定。

如果您看到此錯誤，則需要提升您的使用者權限。

(!) An error occurred, see the readme for troubleshooting and prerequisites:
    https://github.com/Azure/azure-dev/blob/main/cli/azd/extensions/azure.coding-agent/README.md
Error: failed to create GitHub environment copilot in repository owner/repository: exit code: 1, stdout: {"message":"Must have admin rights to Repository.","documentation_url":"https://docs.github.com/rest/deployments/environments#create-or-update-an-environment","status":"403"}, stderr: gh: Must have admin rights to Repository. (HTTP 403)

刷新令牌已過期

再次登入：

azd auth login

視需要新增旗標，例如 --tenant-id <tenant-id> 或 --use-device-code 。

改善診斷輸出

使用偵錯模式：

azd coding-agent config --debug

所有內部命令及其輸出都會列印到控制台。

後續步驟

使用角色指派擴充身分識別權限（僅視需要）
透過擴充工作流程來整合額外的自動化 .github/workflows/
探索其他擴充功能：擴充功能概觀
檢閱 Azure RBAC 概念

Contributing

若要參與 Azure 開發人員 CLI 資源，請參閱參與指南。拉取請求可能需要簽署貢獻者許可協議。

行為規範

此專案遵循 Microsoft 開放原始碼行為準則。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-07-18