# GitHub Actions Automated Deployment Setup
This guide shows how to deploy the Azure VM using GitHub Actions with **OIDC (OpenID Connect)** for secure Azure authentication.
> **💡 Alternative:** If automated deployment fails, use the manual installation guide: [`docs/AZURE_SELFHOSTED_RUNNER_SETUP.md`](../../docs/AZURE_SELFHOSTED_RUNNER_SETUP.md#manual-installation)
## Prerequisites
- Azure subscription with permissions to create app registrations
- GitHub repository admin access
- Office 365 license for Excel
## Setup (One-Time)
### Step 1: Create Azure App Registration with Federated Credentials (OIDC)
**Using Azure CLI:**
```bash
# Login to Azure
az login
# Get your subscription ID
SUBSCRIPTION_ID=$(az account show --query id --output tsv)
# Create app registration
APP_ID=$(az ad app create \
--display-name "github-excel-runner-oidc" \
--query appId \
--output tsv)
echo "App ID: $APP_ID"
# Create service principal
az ad sp create --id $APP_ID
# Add federated credential for GitHub Actions
az ad app federated-credential create \
--id $APP_ID \
--parameters "{
\"name\": \"github-excel-runner\",
\"issuer\": \"https://token.actions.githubusercontent.com\",
\"subject\": \"repo:sbroenne/mcp-server-excel:ref:refs/heads/main\",
\"audiences\": [\"api://AzureADTokenExchange\"]
}"
# Assign Contributor role to subscription
az role assignment create \
--assignee $APP_ID \
--role Contributor \
--scope /subscriptions/$SUBSCRIPTION_ID
# Get tenant ID
TENANT_ID=$(az account show --query tenantId --output tsv)
echo ""
echo "✅ Setup complete! Add these to GitHub Secrets:"
echo "AZURE_CLIENT_ID: $APP_ID"
echo "AZURE_TENANT_ID: $TENANT_ID"
echo "AZURE_SUBSCRIPTION_ID: $SUBSCRIPTION_ID"
```
**Using Azure Portal:**
1. Go to **Azure Active Directory** → **App registrations**
2. Click **New registration**
- Name: `github-excel-runner-oidc`
- Click **Register**
3. Note the **Application (client) ID** and **Directory (tenant) ID**
4. Go to **Certificates & secrets** → **Federated credentials**
5. Click **Add credential**
- Federated credential scenario: **GitHub Actions deploying Azure resources**
- Organization: `sbroenne`
- Repository: `mcp-server-excel`
- Entity type: **Branch**
- GitHub branch name: `main`
- Name: `github-excel-runner`
- Click **Add**
6. Go to **Subscriptions** → Select your subscription → **Access control (IAM)**
7. Click **Add role assignment**
- Role: **Contributor**
- Assign access to: **User, group, or service principal**
- Select: `github-excel-runner-oidc`
- Click **Review + assign**
### Step 2: Add Azure Information to GitHub Secrets
1. Go to your repository: `https://github.com/sbroenne/mcp-server-excel`
2. Navigate to **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret** for each:
| Secret Name | Value | Where to Find |
|-------------|-------|---------------|
| `AZURE_CLIENT_ID` | Application (client) ID | From Step 1 or App Registration overview |
| `AZURE_TENANT_ID` | Directory (tenant) ID | From Step 1 or Azure AD overview |
| `AZURE_SUBSCRIPTION_ID` | Subscription ID | From Step 1 or Subscriptions page |
**No Azure client secret needed!** OIDC uses federated credentials instead.
## Deployment
### Get GitHub Runner Registration Token
Before deploying, you need a runner registration token:
1. Go to your repository: `https://github.com/sbroenne/mcp-server-excel`
2. Navigate to **Settings** → **Actions** → **Runners**
3. Click **New self-hosted runner**
4. Select **Windows** as the OS
5. Copy the token from the configuration command (starts with `A...`)
- ⚠️ **Important**: Token expires after 1 hour - use it immediately
- Token format: Long alphanumeric string (e.g., `A3E7G...`)
### Deploy via GitHub Actions UI
1. Go to **Actions** tab in your repository
2. Select **Deploy Azure Self-Hosted Runner** workflow
3. Click **Run workflow**
4. Fill in the parameters:
- **Resource Group:** `rg-excel-runner` (or your preference)
- **Admin Password:** Strong password for VM (e.g., `MySecurePass123!`)
- **Runner Token:** Paste the token you copied from Settings → Actions → Runners
5. Click **Run workflow**
**Deployment takes ~5 minutes**
### After Deployment
1. Check workflow run for VM FQDN (displayed in logs)
2. RDP to the VM using the FQDN and credentials
3. Install Office 365 Excel (30 minutes):
- Sign in to https://portal.office.com
- Install Office 365 apps
- Select Excel only during installation
- Activate with your Office 365 account
4. Reboot VM
5. Runner auto-starts and registers with GitHub
### Verify Deployment
**Check runner status:**
```
https://github.com/sbroenne/mcp-server-excel/settings/actions/runners
```
Should show:
- Name: `azure-excel-runner`
- Status: Idle (green)
- Labels: `self-hosted`, `windows`, `excel`
## Why This Approach?
**Benefits:**
- ✅ **Simple** - Just get a runner token and deploy
- ✅ **Secure Azure authentication** - Uses OIDC (no client secrets)
- ✅ **No credential rotation** - Azure federated credentials don't expire
- ✅ **Repeatable** - Same process every time
- ✅ **Audit trail** - Every deployment logged in GitHub Actions
**Trade-offs:**
- ⚠️ **Manual token generation** - Need to get a new token each time (expires after 1 hour)
- ⚠️ **Not fully automated** - Requires manual step before deployment
**This is the simplest approach for occasional deployments.** If you deploy frequently, consider setting up a GitHub App or PAT for automated token generation.
## Troubleshooting
### "Invalid runner token" error
**Cause:** Runner token expired (tokens expire after 1 hour)
**Solution:**
1. Generate a new token from Settings → Actions → Runners → New self-hosted runner
2. Re-run the workflow with the new token
### "Deployment failed" or "Runner setup failed" error
**Check:**
1. Azure credentials are correct
2. Service principal has Contributor role
3. Subscription has quota for B2ms VMs in Sweden Central
**View detailed error:**
- Check workflow logs in Actions tab
- Look for error messages in "Deploy Bicep Template" step
**Check VM extension logs (via RDP):**
If the VM was created but runner setup failed, RDP to the VM and check:
```powershell
# View setup script log
Get-Content C:\runner-setup.log
# Check CustomScriptExtension logs
Get-Content C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\*\*.log
```
**Common causes:**
- Runner token expired (regenerate and retry)
- Network connectivity issues (check NSG rules)
- GitHub rate limiting (wait and retry)
**Fallback:** Use manual installation guide: [`docs/MANUAL_RUNNER_INSTALLATION.md`](../../docs/MANUAL_RUNNER_INSTALLATION.md)
### Azure Login failed
**Check:**
1. `AZURE_CREDENTIALS` secret contains valid JSON
2. Service principal exists: `az ad sp list --display-name "github-excel-runner-deployer"`
3. Service principal has Contributor role
## Cost
- **Monthly:** ~$61 (24/7 operation in Sweden Central)
- **One-time setup:** Free (GitHub Actions minutes)
## Cleanup
To delete all resources:
```bash
az group delete --name rg-excel-runner --yes --no-wait
```
Or use Azure Portal → Resource Groups → Delete
## Security Best Practices
1. **Use OIDC for Azure** instead of service principal credentials (more secure)
2. **Runner Token Security**:
- Never commit runner tokens to code
- Tokens expire after 1 hour
- Generate new token for each deployment
3. **Limit service principal** to specific resource group
4. **Enable Azure Security Center** for VM monitoring
5. **Review permissions** regularly
6. **Secure VM password** - Use strong password, store securely
## Support
- **Azure Issues:** Check workflow logs in Actions tab
- **Repository Issues:** https://github.com/sbroenne/mcp-server-excel/issues
- **Azure Docs:** https://docs.microsoft.com/azure/developer/github/connect-from-azure
---
**Deployment time:** 5 min (automated) + 30 min (Excel install)
**Cost:** ~$61/month
