iTranslated by AI
Building an Azure System Using Only GitHub for Mobile
This is the article for day 7 of the Microsoft Azure Tech Advent Calendar 2025.
Introduction
Recently, I have been using GitHub Copilot more and more to help me with various tasks.
Naturally, I usually work while sitting in front of a PC, but I suddenly wondered, "How much of my current work can be completed by an agent?" So, I decided to take on the challenge of seeing if building a system on Azure could be completed entirely within the GitHub App on a smartphone.
It involved a lot of trial and error, and it wasn't all smooth sailing—I had to rewrite AGENTS.md many times and faced my fair share of difficulties—but I hope to share those failures along with the results in this article.
By the way, here is the TODO app that was created.
UI of the TODO app
Infrastructure architecture of the TODO app
A somewhat "serious" system—featuring App Gateway + WAF, VNet-integrated App Service, and DB access via Private Endpoint + Entra ID authentication—was easily designed and built right from a smartphone.
Setup
For this project, I used the standard GitHub Copilot Coding Agent[1] along with an instruction file for the agent (AGENTS.md). The Coding Agent is currently available if you have a Copilot Pro plan or higher[2].
The only part where humans need to work hard is setting up the Coding Agent to access Azure resources; after that, it's just a matter of repeatedly giving instructions from a smartphone during spare moments. The setup mainly consists of the following tasks:
- Creating the repository
- Customizing
AGENTS.md(.github/copilot-instructions.md) - Issuing a service principal for the Coding Agent and configuring RBAC
- Configuring the Coding Agent environment
- Setting environment variables for credentials (e.g.,
AZURE_CLIENT_ID) - Installing Azure CLI and Azure Developer CLI
- Setting up the Azure MCP Server
- Setting up the firewall allowlist
- Setting environment variables for credentials (e.g.,
Creating the Repository
Create a new repository with an account that has access to the Coding Agent.
The purpose of the Coding Agent is software development; in this case, it operates with the goal of creating Bicep files or scripts (and testing them), so it likely doesn't have resource deployment in its immediate scope. Therefore, we customize this using AGENTS.md (.github/copilot-instructions.md). We'll include instructions like, "I'm giving you management permissions for Azure resources, so please handle the deployment of both infrastructure and applications."
In addition, organize the repository by including other useful items (e.g., .gitignore, README, devcontainer). I have published a template below, so please feel free to refer to it.
The main directory structure of the template repository is as follows:
.
├── .devcontainer/ # Dev Container settings
├── .vscode/ # VS Code settings (Note: MCP settings here are for local use and unrelated to Coding Agent)
├── docs/ # Documentation and verification results
├── scripts/ # Setup and execution scripts
├── .env.example # Environment variable template
├── .gitignore # Git exclusion settings
├── AGENTS.md # Agent instruction file
├── README.md # Project description
└── TODO.md # Task management
Coding Agent Execution Environment
Next, we need to prepare the environment so that the Coding Agent can operate Azure resources. The following two things are mainly required:
- ID Issuance and Authorization: Set up RBAC settings so that the Coding Agent (Principal ID) can operate resources.
-
Installation of Management Tools: Install tools such as
az,azd, and the Azure MCP Server in the Coding Agent environment.
For ID and authorization settings, issue a Managed Identity or Service Principal for the Coding Agent and add RBAC settings to that ID. This allows the Coding Agent to operate Azure resources. For role assignments, adhere to the principle of least privilege by limiting the scope to the resource group being tested. Then, register the credentials as secrets or environment variables in the repository's Environment so they can be referenced by the workflow.
Meanwhile, the Coding Agent's execution environment can be controlled via .github/workflows/copilot-setup-steps.yml. By adding installation steps for azd or az in the workflow definition, you can add these commands. Please refer to the official documentation for details.
However, the MCP Server must be added from a separate management panel. This is described in the following documentation.
What? Too much trouble?
azd has a convenient feature to quickly perform this series of setups: the azure.coding-agent extension.
By using azure.coding-agent, you can execute the following commands to set up a Coding Agent environment where the Azure Developer CLI, Azure CLI, and Azure MCP Server are available, as well as create a Managed ID and grant it Reader permissions (to a specific resource group) all at once.
azd extension install azure.coding-agent
azd coding-agent config
Running this command creates a new resource group and a User-Assigned Managed Identity for the Coding Agent inside it (existing ones can also be used). Then, a Reader role at the resource group scope is assigned to this MI.
Additionally, for this use case, permissions for resource creation will be required. Don't forget to separately assign permissions such as Contributor.
Next, the gh command is used to perform the necessary settings on the GitHub repository side. First, an environment for the Coding Agent is created, and the credentials for the previously mentioned MI are registered as environment variables.
Finally, a Pull Request is issued to change the execution environment of the Coding Agent (by adding .github/workflows/copilot-setup-steps.yml). By default, it sets up an environment with az and azd installed. If there are no issues, simply merge it to reflect the changes.
Once you have finished running the commands, the final step is to configure the firewall and MCP settings for the Coding Agent execution environment from the panel below.
Regarding MCP, a sample is provided by the azd coding-agent config command, so you can use it as-is. For example, if you want to add it along with the MS Learn Docs MCP, you would register the following JSON:
{
"mcpServers": {
"microsoft-docs-mcp": {
"type": "http",
"url": "https://learn.microsoft.com/api/mcp",
"tools": ["*"]
},
"azure-mcp-server": {
"type": "local",
"command": "npx",
"args": [
"-y",
"@azure/mcp@latest",
"server",
"start"
],
"tools": ["*"]
}
}
}
For firewall rules, add the Azure CLI connectivity requirements to the Custom allowlist. To be honest, it's quite difficult to cover everything, so in practice, you should be prepared for an operation like "allowing endpoints whenever a block is reported." By the way, if a connection fails, the Coding Agent will provide a list of the failed endpoints in a PR comment.
management.azure.com
management.core.windows.net
batch.core.windows.net
gallery.azure.com
login.microsoftonline.com
graph.windows.net
graph.microsoft.com
datalake.azure.net
rest.media.azure.net
ossrdbms-aad.database.windows.net
api.applicationinsights.io
api.loganalytics.io
dc.applicationinsights.azure.com
dev.azuresynapse.net
attest.azure.net
portal.azure.com
raw.githubusercontent.com
aka.ms
azcliextensionsync.blob.core.windows.net
azcliprod.blob.core.windows.net
azurecliextensionsync.blob.core.windows.net
live-data.bicep.azure.com
Verification of Setup
Once setup is complete, it's a good idea to verify that az and MCP are actually working.
Looking at the session logs, you can see the MCP server starting up and the Coding Agent executing commands via the Azure CLI. If issues arise, I recommend checking these session logs to troubleshoot.
By the way, since the artifacts created during this check aren't necessary, you can just close the PR.
The Outcome
After that, it's just a matter of sending instructions on GitHub.
Since there are no requirements in the repository at first, you need to start with an Issue to define the requirements (and confirm the scope of verification). I gave a rough instruction like, "Build a secure 3-tier TODO web application using AppGW - App Service (.NET) - SQL Server."
In the end, after closing 7 PRs, the challenge was successful, and a .NET-based TODO app (SPA) like the one below was completed. In terms of time, I think it was created with a lead time of roughly 3 to 4 hours.
Architecture
Deployed Resources
Repository Status After the Challenge
As instructed in AGENTS.md, various artifacts have been created.
First, the README was designed to function as an entry point. Specifically, it describes everything from the background to what was executed and what was learned. It also includes the architecture and communication flow, making it easy to understand what was done even when seeing the repository for the first time.
Since I had instructed the agent to add execution logs and ADRs (Architecture Decision Records), those documents are also abundantly available.
Additionally, the application source code and scripts are naturally recorded. I gave a general instruction to follow an azd-like style, so it ended up being a script that executes deployment group create using infra/main.bicep, but I think it's sufficient for deploying a verification environment. With this, anyone can reproduce the environment immediately.
Lessons Learned
Higher Autonomous Capability Than Expected
I found that the agent can complete much more work in a single instruction than expected. The standard Coding Agent functions well enough. For example, the following tasks were all completed in a single instruction:
- Resource creation for Application Gateway, App Service, SQL Database, etc.
- VNet, Subnet, and Private Endpoint configuration
- NSG rules and WAF configuration
- Automatic generation of Bicep code
- Operation verification and log recording
During the setup process, when an error occurred in the Private Endpoint subnet configuration, the agent checked the error logs, identified that there was a problem with the subnet delegations settings, and automatically fixed it. If the requirements (tasks) are clear, there is a very high probability that it will handle the work.
Review is Essential
Not a single PR passed the merge check on the first try. In particular, I got the impression that there were many issues related to state management, such as insufficient documentation maintenance or mismatches between the state of the code/Azure resources and the TODO list.
It seemed necessary to incorporate mechanisms that naturally check consistency into the workflow using things like pre-commit.
However, for issues related to system functionality or Azure resource management, such as security reviews, GitHub Copilot pointed out most of them when asked, so I didn't have much to do. I think having the MS Learn Docs MCP in the environment (enabling the Coding Agent to search for best practices) played a large role in this.
Fallback from Azure CLI to Azure MCP
While Azure MCP is sufficient for simply letting the Coding Agent manage Azure resources, I wanted to script the work so that humans could reuse it, which meant I needed to utilize the Azure CLI this time.
However, since there were many instances where az didn't work due to connection errors in the Coding Agent's sandbox environment, I established a mechanism to fall back to Azure MCP.
This allows MCP to act as a substitute even when the Coding Agent cannot execute commands via the Azure CLI.
Importance of AGENTS.md Design Skills
With the AGENTS.md I used initially, the agent would stop after generating the script even for an instruction like "deploy the app." I believe this was due to the Coding Agent's system prompt.
Therefore, when I explicitly stated the principle that "the agent should manage Azure resources autonomously," it became possible to automate everything up to the execution of the deployment. I realized that it's important to describe instructions carefully, especially when directing it to do something out of the ordinary.
Here are a few effective description patterns:
# Patterns to encourage autonomous execution
- Autonomously execute the creation, update, and deletion of Azure resources.
- After generating scripts, actually complete the deployment.
- If an error occurs, check the logs and attempt self-repair.
# Patterns to instruct a fallback
- If a connection error occurs with the Azure CLI, use the Azure MCP Server.
- In case of a permission error, report the required permissions in a PR comment.
# Patterns to force document generation
- Record execution logs for each task in docs/logs/.
- Record architecture decisions in ADR format in docs/adr/.
Also, since session logs for the agent cannot be checked from the GitHub mobile app on Android, having it attach execution logs/ADRs helped with the ease of review. Having it record detailed work logs that a human would find too troublesome to include will likely become one of my agent instruction patterns from now on.
Summary
This time, I experimented with building an Azure verification environment using only a smartphone.
As a result, I was able to build a 3-tier architecture from Application Gateway to SQL Database in 3 to 4 hours. By imposing the constraint of a "hands-off environment" on myself, I feel like I've gained some insight into the tips for delegating to AI agents.
However, when letting an agent operate Azure resources, it is important to apply the same governance principles as when a human operates them.
- Least Privilege: e.g., limit permissions to the resource group scope + Contributor or lower.
- Monitoring and Observability: e.g., track operations in activity logs and detect anomalies.
- Cost Management: e.g., set budget alerts to prevent unexpected spending.
- Guardrails: e.g., set guardrails using Azure Policy.
Building on this experiment, I want to continue taking on challenges so that various tasks can be completed with simple instructions.
-
While custom agents are also available, I wanted to see how capable the standard Coding Agent is. ↩︎
Discussion