diff --git a/.github/agents/azure-template-generator.agent.md b/.github/agents/azure-template-generator.agent.md index 79e8b4d..69e4807 100644 --- a/.github/agents/azure-template-generator.agent.md +++ b/.github/agents/azure-template-generator.agent.md @@ -423,6 +423,15 @@ graph LR Storage AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef storage fill:#fef3c7,stroke:#92400e,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class Internet internet + class FuncApp compute + class Storage storage + class AppInsights monitor ``` **Web App + Database Stack:** @@ -441,6 +450,17 @@ graph LR Storage AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef storage fill:#fef3c7,stroke:#92400e,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class Internet internet + class WebApp compute + class SQL,SQLServer data + class Storage storage + class AppInsights monitor ``` **Microservices Stack:** @@ -461,6 +481,17 @@ graph TD Cosmos AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef gateway fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef container fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class Internet internet + class APIM gateway + class CA1,CA2 container + class Cosmos data + class AppInsights monitor ``` **For multi-resource deployments**, always generate the diagram showing: diff --git a/.github/skills/azure-resource-visualizer/SKILL.md b/.github/skills/azure-resource-visualizer/SKILL.md index 900fd87..0405926 100644 --- a/.github/skills/azure-resource-visualizer/SKILL.md +++ b/.github/skills/azure-resource-visualizer/SKILL.md @@ -95,6 +95,19 @@ graph TB FUNC -.->|"instrumentation key"| APPI APP -->|"secrets"| KV FUNC -->|"secrets"| KV + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef storage fill:#fef3c7,stroke:#92400e,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + classDef secret fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + class Internet internet + class APP,FUNC compute + class SQL data + class STORAGE storage + class APPI monitor + class KV secret ``` **Diagram Rules:** diff --git a/.gitignore b/.gitignore index 1bc0bc9..bd55f7f 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ website/node_modules/ website/build/ website/.docusaurus/ + +# Playwright MCP test artifacts +.playwright-mcp/ diff --git a/docs/APE.png b/APE.png similarity index 100% rename from docs/APE.png rename to APE.png diff --git a/README.md b/README.md index 5aaa41b..6d2dafc 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Git-Ape APE logo](docs/APE.png) +![Git-Ape APE logo](APE.png) # Git-Ape @@ -86,7 +86,7 @@ Reload VS Code; the `@git-ape` agent and Git-Ape skills will appear in Copilot C ### 2. Configure Azure access 1. Sign in with `az login`. -2. Configure the Azure MCP server in VS Code — see [docs/AZURE_MCP_SETUP.md](docs/AZURE_MCP_SETUP.md). +2. Configure the Azure MCP server in VS Code — see the [Azure Setup](https://azure.github.io/git-ape/docs/getting-started/azure-setup) guide. ### 3. Use the agents @@ -104,11 +104,11 @@ When you're done, clean up with: ## Where To Go Next -- [docs/EXAMPLES.md](docs/EXAMPLES.md): Longer end-to-end examples and sample conversations. -- [docs/AZURE_MCP_SETUP.md](docs/AZURE_MCP_SETUP.md): Azure MCP server configuration for VS Code. -- [docs/DEPLOYMENT_STATE.md](docs/DEPLOYMENT_STATE.md): How deployment artifacts are stored and reused. -- [docs/ONBOARDING.md](docs/ONBOARDING.md): Repository onboarding, OIDC, RBAC, and GitHub environment setup. -- [docs/CODESPACES.md](docs/CODESPACES.md): GitHub Codespaces and dev container setup. +- [Examples](https://azure.github.io/git-ape/docs/deployment/examples): End-to-end deployment walkthroughs. +- [Azure Setup](https://azure.github.io/git-ape/docs/getting-started/azure-setup): Azure MCP server configuration for VS Code. +- [State Management](https://azure.github.io/git-ape/docs/deployment/state): How deployment artifacts are stored and reused. +- [Onboarding](https://azure.github.io/git-ape/docs/getting-started/onboarding): Repository onboarding, OIDC, RBAC, and GitHub environment setup. +- [Codespaces](https://azure.github.io/git-ape/docs/getting-started/codespaces): GitHub Codespaces and dev container setup. ## Architecture diff --git a/docs/AZURE_MCP_SETUP.md b/docs/AZURE_MCP_SETUP.md deleted file mode 100644 index 06959e6..0000000 --- a/docs/AZURE_MCP_SETUP.md +++ /dev/null @@ -1,305 +0,0 @@ -# Azure MCP Server Configuration - -> [!WARNING] -> EXPERIMENTAL ONLY: This setup is for development and sandbox testing. -> Do **not** use this repository or its generated workflows for production Azure operations. -> Review permissions and commands carefully before running them. - -This document explains how to configure the Azure MCP server to enable Azure deployment capabilities for the Git-Ape agent system. - -## Prerequisites - -1. **VS Code Insiders** (or VS Code with GitHub Copilot extension) -2. **GitHub Copilot subscription** (with access to Copilot Chat) -3. **Azure CLI** installed and configured -4. **Azure MCP Server extension** (should be installed automatically with Azure extensions) - -## Extension Installation - -The Azure MCP server is provided by the `ms-azuretools.vscode-azure-mcp-server` extension. It should be automatically available if you have Azure Tools for VS Code installed. - -Verify installation: -```bash -code --list-extensions | grep azure-mcp -``` - -You should see: `ms-azuretools.vscode-azure-mcp-server` - -## Configuration - -### 1. VS Code Settings - -Add the following to your VS Code settings (`.vscode/settings.json` or User Settings): - -```json -{ - "azureMcp.serverMode": "namespace", - "azureMcp.enabledServices": [ - "deploy", - "bestpractices", - "group", - "subscription", - "resourcehealth", - "monitor", - "functionapp", - "storage", - "sql", - "cosmos", - "bicepschema", - "cloudarchitect" - ], - "azureMcp.readOnly": false -} -``` - -**Configuration Options:** - -- **`serverMode`**: Controls how MCP tools are exposed - - `"single"`: One tool that routes to 100+ internal commands - - `"namespace"`: ~30 logical groups by service (recommended) - - `"all"`: Every MCP tool exposed directly (100+ tools) - -- **`enabledServices`**: Array of service namespaces to expose - - Only specified services will be available to agents - - Reduces tool clutter and improves agent focus - -- **`readOnly`**: When `true`, prevents destructive operations - - Set to `false` to allow deployments - - Set to `true` for testing/validation only - -### 2. Azure Authentication - -Authenticate with Azure CLI: - -```bash -# Login to Azure -az login - -# Set default subscription (optional but recommended) -az account set --subscription "Your Subscription Name or ID" - -# Verify authentication -az account show -``` - -The Azure MCP server uses your Azure CLI credentials automatically. - -### 3. Environment Variables (Optional) - -Create a `.env` file in your workspace root for default values: - -```bash -# Azure Subscription -AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - -# Default Region -AZURE_DEFAULT_REGION=eastus - -# Default Resource Group (optional) -AZURE_DEFAULT_RESOURCE_GROUP=rg-git-ape-dev-eastus -``` - -## Available Azure MCP Services - -The following services are used by the Git-Ape agents: - -### Core Deployment Services - -- **`deploy`** - ARM template deployment, what-if analysis, validation -- **`bestpractices`** - Security and configuration recommendations -- **`cloudarchitect`** - Architecture diagram generation - -### Resource Management - -- **`group`** - Resource group operations -- **`subscription`** - Subscription queries and management -- **`resourcehealth`** - Resource status and health monitoring -- **`monitor`** - Logging, metrics, and monitoring - -### Compute Services - -- **`functionapp`** - Azure Functions management -- **`aks`** - Azure Kubernetes Service (optional) -- **`acr`** - Azure Container Registry (optional) - -### Data Services - -- **`storage`** - Blob, Table, Queue, File storage -- **`sql`** - Azure SQL Database -- **`cosmos`** - Cosmos DB -- **`mysql`**, **`postgres`** - Database services (optional) - -### Infrastructure - -- **`bicepschema`** - Bicep/ARM template schemas -- **`keyvault`** - Secrets, keys, certificates - -## Verification - -After configuration, verify the MCP server is working: - -1. Open VS Code -2. Open GitHub Copilot Chat -3. Type: `@git-ape` -4. You should see "Git-Ape" in the agent picker - -To test Azure MCP tools are accessible: - -``` -In Copilot Chat: -"List available Azure subscriptions" - -Expected: The agent should use Azure MCP tools to query subscriptions -``` - -## Troubleshooting - -### Issue: "Unknown tool 'mcp_azure_mcp/*'" - -**Cause:** Azure MCP server not loaded or not configured - -**Solution:** -1. Verify extension is installed: `code --list-extensions | grep azure-mcp` -2. Reload VS Code window: `Cmd/Ctrl + Shift + P` → "Reload Window" -3. Check settings have `azureMcp.serverMode` configured - -### Issue: Azure authentication fails - -**Cause:** Azure CLI not authenticated or token expired - -**Solution:** -```bash -# Re-authenticate -az login - -# Verify -az account show - -# If multiple subscriptions, set default -az account set --subscription "Your Subscription" -``` - -### Issue: "Permission denied" on deployments - -**Cause:** Azure account lacks Contributor role on subscription/resource group - -**Solution:** -1. Verify your role: `az role assignment list --assignee $(az account show --query user.name -o tsv)` -2. You need at least "Contributor" role for deployments -3. Contact your Azure administrator to grant appropriate permissions - -### Issue: MCP tools are slow or unresponsive - -**Cause:** Too many services enabled or network latency - -**Solution:** -1. Reduce `enabledServices` to only what you need -2. Use `"namespace"` mode instead of `"all"` -3. Check Azure service health: https://status.azure.com - -### Issue: Agent doesn't see Azure services - -**Cause:** Services not in `enabledServices` list - -**Solution:** -Add required services to `azureMcp.enabledServices` array in settings.json - -## Security Considerations - -### Credential Storage - -- **Never commit** Azure credentials to version control -- Use `.env` for local development (add to `.gitignore`) -- In production/CI, use managed identities or Azure DevOps service connections - -### Least Privilege - -The agents require these minimum Azure permissions: - -- **Requirements Gatherer**: `Reader` role -- **Template Generator**: `Reader` role -- **Resource Deployer**: `Contributor` role on target resource groups - -Consider creating a custom role: - -```json -{ - "Name": "Git-Ape Deployer", - "Description": "Deploy Azure resources via Git-Ape agent", - "Actions": [ - "Microsoft.Resources/deployments/*", - "Microsoft.Resources/subscriptions/resourceGroups/*", - "Microsoft.Web/sites/*", - "Microsoft.Storage/storageAccounts/*", - "Microsoft.Insights/components/*" - ], - "AssignableScopes": [ - "/subscriptions/{subscription-id}" - ] -} -``` - -### Production Deployments - -For production deployments: - -1. Set `azureMcp.readOnly: false` only when deploying -2. Use approval gates (the agent requires user confirmation) -3. Enable Azure Policy to restrict resource types/regions -4. Use separate subscriptions for dev/staging/prod -5. Review ARM templates before confirming deployment - -## Advanced Configuration - -### Custom MCP Server Mode - -If you want more control over which specific tools are available: - -```json -{ - "azureMcp.serverMode": "all", - "azureMcp.toolFilter": [ - "deploy_group_create", - "deploy_group_what_if", - "storage_account_create", - "functionapp_create" - ] -} -``` - -This exposes only specific tool commands instead of entire service namespaces. - -### Multiple Azure Accounts - -If you work with multiple Azure tenants/subscriptions: - -```bash -# Login to different tenant -az login --tenant "tenant-id" - -# Switch between subscriptions -az account set --subscription "subscription-1" -# Deploy resources... - -az account set --subscription "subscription-2" -# Deploy to different subscription... -``` - -The agent will use whichever subscription is currently active in Azure CLI. - -## Next Steps - -After configuration: - -1. Test the agent with a simple deployment: `@git-ape deploy a resource group` -2. Review the [README.md](../../README.md) for example workflows -3. Customize workspace instructions in [copilot-instructions.md](../copilot-instructions.md) -4. Add your organization's naming conventions and policies - -## Resources - -- [Azure MCP Server Documentation](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-mcp-server) -- [Azure CLI Documentation](https://docs.microsoft.com/en-us/cli/azure/) -- [GitHub Copilot Custom Agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents) -- [ARM Template Reference](https://docs.microsoft.com/en-us/azure/templates/) diff --git a/docs/CODESPACES.md b/docs/CODESPACES.md deleted file mode 100644 index 1b9a003..0000000 --- a/docs/CODESPACES.md +++ /dev/null @@ -1,90 +0,0 @@ -# GitHub Codespaces Dev Environment - -Git-Ape includes a ready-to-use [dev container](https://containers.dev/) configuration so you can start contributing or using the project instantly in GitHub Codespaces (or any dev container-compatible tool like VS Code Dev Containers). - -## Quick Start - -### Option 1: GitHub Codespaces (recommended) - -1. Navigate to the [Git-Ape repository](https://github.com/Azure/git-ape). -2. Click **Code** → **Codespaces** → **Create codespace on main**. -3. Wait for the container to build and the post-create setup to finish. -4. Sign in to Azure with `az login` when prompted. - -### Option 2: VS Code Dev Containers (local) - -1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). -2. Clone the repository and open it in VS Code. -3. When prompted, click **Reopen in Container** (or run the command `Dev Containers: Reopen in Container`). -4. Sign in to Azure with `az login`. - -## What's Included - -### Base Image - -`mcr.microsoft.com/devcontainers/base:ubuntu` — a lightweight Ubuntu image maintained by Microsoft. - -### Dev Container Features - -| Feature | Version | Purpose | -|---------|---------|---------| -| Azure CLI | latest | Azure resource management and deployments | -| GitHub CLI | latest | PR creation, issue management, workflow dispatch | -| Python | 3.12 | Checkov IaC scanner and scripting | -| Node.js | 20 | Tooling and automation scripts | -| PowerShell | latest | PSRule, ARM-TTK, and Azure PowerShell modules | -| Common utilities | — | Zsh with Oh My Zsh as default shell | - -### Post-Create Setup - -The `post-create.sh` script runs automatically after the container is built and installs: - -- **Checkov** — IaC security scanner supporting ARM, Bicep, and Terraform templates. -- **PSRule for Azure** — WAF-aligned validation rules for ARM and Bicep templates. -- **ARM-TTK** — Microsoft's ARM Template Test Toolkit for template validation. - -### VS Code Extensions - -The following extensions are automatically installed in the container: - -| Extension | Purpose | -|-----------|---------| -| GitHub Copilot | AI coding assistant | -| GitHub Copilot Chat | Chat-based AI assistance | -| Azure Resource Groups | Browse and manage Azure resource groups | -| Azure Functions | Develop and deploy Azure Functions | -| Azure MCP Server | Azure MCP integration for Copilot agents | -| PSRule | Run PSRule validation from VS Code | - -### VS Code Settings - -The Azure MCP server is preconfigured with: - -- `azureMcp.serverMode`: `namespace` — organizes tools by Azure service. -- `azureMcp.readOnly`: `false` — allows read and write operations. - -## After Setup - -Once the environment is ready: - -1. **Sign in to Azure**: Run `az login` to authenticate. For Codespaces, `az login --use-device-code` works best. -2. **Verify the setup**: Run `az account show` to confirm your subscription. -3. **Start using Git-Ape**: Open Copilot Chat and try `@git-ape deploy a Python function app`. - -## Customization - -To add features or tools to the dev container: - -- **Dev container features**: Add entries to the `features` object in `.devcontainer/devcontainer.json`. -- **Post-create tools**: Add installation commands to `.devcontainer/post-create.sh`. -- **VS Code extensions**: Add extension IDs to `customizations.vscode.extensions` in `.devcontainer/devcontainer.json`. - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| Codespace build fails | Check the creation log for errors. Common cause: feature version conflicts. | -| `az login` fails in Codespaces | Use `az login --use-device-code` for browser-based auth. | -| ARM-TTK not found | Run `pwsh` and verify the profile loaded: `Get-Module arm-ttk -ListAvailable`. | -| Checkov not found | Run `pip install --user checkov` manually. | -| Extensions missing | Reload the window (`Ctrl+Shift+P` → `Developer: Reload Window`). | diff --git a/docs/DEPLOYMENT_STATE.md b/docs/DEPLOYMENT_STATE.md deleted file mode 100644 index ec8b41c..0000000 --- a/docs/DEPLOYMENT_STATE.md +++ /dev/null @@ -1,608 +0,0 @@ -# Deployment State Management - -> [!WARNING] -> EXPERIMENTAL ONLY: State formats, file schemas, and lifecycle behavior may change at any time. -> Do **not** rely on this project for production deployment tracking, audit, or recovery. - -This document explains how Git-Ape persists deployment artifacts, manages state, and enables deployment reuse. - -## Overview - -Every deployment creates a timestamped directory under `.azure/deployments/` containing: - -- Complete audit trail of the deployment process -- Reusable configuration for future deployments -- Test results and logs for debugging -- Error information for failure analysis - -## Deployment Lifecycle - -A deployment moves through a defined set of states tracked in `metadata.json`. Valid `status` values are `initialized`, `gathering-requirements`, `generating-template`, `awaiting-confirmation`, `deploying`, `testing`, `succeeded`, `failed`, `rolled-back`, `destroy-requested`, and `destroyed`. Terminal states (`succeeded`, `failed`, `rolled-back`, `destroyed`) are persisted in git for audit. - -```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -stateDiagram-v2 - state "gathering-requirements" as gatheringRequirements - state "generating-template" as generatingTemplate - state "awaiting-confirmation" as awaitingConfirmation - state "rolled-back" as rolledBack - state "destroy-requested" as destroyRequested - - [*] --> initialized: deployment dir created - initialized --> gatheringRequirements: Requirements Gatherer - gatheringRequirements --> generatingTemplate: Template Generator - generatingTemplate --> awaitingConfirmation: security gate passed - generatingTemplate --> generatingTemplate: security gate blocked
(fix loop) - awaitingConfirmation --> deploying: user / PR approval - awaitingConfirmation --> [*]: declined - deploying --> testing: az deployment ok - deploying --> failed: deployment error - testing --> succeeded: tests pass - testing --> failed: tests fail - failed --> rolledBack: rollback initiated - succeeded --> destroyRequested: PR sets metadata - destroyRequested --> destroyed: git-ape-destroy.yml - succeeded --> [*] - rolledBack --> [*] - destroyed --> [*] - - classDef terminal fill:#dcfce7,stroke:#15803d,color:#14532d - classDef error fill:#fecaca,stroke:#b91c1c,color:#7f1d1d - class succeeded,destroyed terminal - class failed,rolledBack error -``` - -## Directory Structure - -``` -.azure/deployments/ -├── deploy-20260218-143022/ # Successful deployment -│ ├── metadata.json # Deployment metadata -│ ├── requirements.json # User requirements -│ ├── template.json # ARM template -│ ├── parameters.json # Template parameters -│ ├── architecture.md # Mermaid architecture diagram -│ ├── deployment.log # Deployment progress -│ └── tests.json # Test results -│ -├── deploy-20260218-151030/ # Failed deployment -│ ├── metadata.json -│ ├── requirements.json -│ ├── template.json -│ ├── architecture.md -│ ├── deployment.log -│ └── error.log # Error details -│ -└── deploy-20260218-163500/ # Rolled back deployment - ├── metadata.json - ├── requirements.json - ├── template.json - ├── architecture.md - ├── deployment.log - └── rollback.log # Rollback actions -``` - -## File Formats - -### metadata.json - -Contains deployment tracking information: - -```json -{ - "deploymentId": "deploy-20260218-143022", - "timestamp": "2026-02-18T14:30:22Z", - "user": "arnaud@example.com", - "status": "succeeded", - "resources": [ - { - "type": "Microsoft.Web/sites", - "name": "func-api-dev-eastus", - "id": "/subscriptions/.../resourceGroups/rg-api-dev-eastus/providers/Microsoft.Web/sites/func-api-dev-eastus", - "status": "succeeded" - } - ], - "estimatedCost": 12.50, - "actualDuration": 245 -} -``` - -**Status values:** -- `initialized` - Deployment directory created -- `gathering-requirements` - Collecting user input -- `generating-template` - Creating ARM template -- `awaiting-confirmation` - Waiting for user approval -- `deploying` - Deployment in progress -- `testing` - Running integration tests -- `succeeded` - Completed successfully -- `failed` - Deployment failed -- `rolled-back` - Resources removed after failure - -### requirements.json - -User requirements collected by the Requirements Gatherer agent: - -```json -{ - "deploymentId": "deploy-20260218-143022", - "timestamp": "2026-02-18T14:30:22Z", - "user": "arnaud@example.com", - "type": "multi-resource", - "resources": [ - { - "type": "Microsoft.Web/sites", - "kind": "functionapp", - "name": "func-api-dev-eastus", - "region": "eastus", - "resourceGroup": "rg-api-dev-eastus", - "sku": "Y1", - "runtime": "python", - "runtimeVersion": "3.11", - "configuration": { - "httpsOnly": true, - "alwaysOn": false, - "appInsights": true - } - }, - { - "type": "Microsoft.Storage/storageAccounts", - "name": "stfuncdeveastus8k3m", - "region": "eastus", - "resourceGroup": "rg-api-dev-eastus", - "sku": "Standard_LRS", - "kind": "StorageV2" - } - ], - "dependencies": [ - { - "source": "stfuncdeveastus8k3m", - "target": "func-api-dev-eastus", - "type": "storage-connection" - } - ], - "validation": { - "subscriptionAccess": true, - "resourceGroupExists": false, - "namesAvailable": true, - "regionSupported": true, - "quotaAvailable": true - }, - "estimatedCost": 12.50 -} -``` - -### template.json - -Generated ARM template (standard Azure format): - -```json -{ - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "functionAppName": { - "type": "string", - "defaultValue": "func-api-dev-eastus" - }, - "location": { - "type": "string", - "defaultValue": "eastus" - } - }, - "variables": { - "storageAccountName": "stfuncdeveastus8k3m" - }, - "resources": [ - { - "type": "Microsoft.Storage/storageAccounts", - "apiVersion": "2021-04-01", - "name": "[variables('storageAccountName')]", - "location": "[parameters('location')]", - "sku": { - "name": "Standard_LRS" - }, - "kind": "StorageV2" - }, - { - "type": "Microsoft.Web/sites", - "apiVersion": "2021-02-01", - "name": "[parameters('functionAppName')]", - "location": "[parameters('location')]", - "kind": "functionapp", - "dependsOn": [ - "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]" - ], - "properties": { - "httpsOnly": true, - "siteConfig": { - "appSettings": [ - { - "name": "AzureWebJobsStorage", - "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2021-04-01').keys[0].value)]" - } - ] - } - } - } - ], - "outputs": { - "functionAppUrl": { - "type": "string", - "value": "[concat('https://', reference(parameters('functionAppName')).defaultHostName)]" - } - } -} -``` - -### deployment.log - -Human-readable deployment progress log: - -``` -[2026-02-18T14:30:22Z] Deployment initialized: deploy-20260218-143022 -[2026-02-18T14:30:22Z] User: arnaud@example.com -[2026-02-18T14:30:22Z] Target: Resource Group 'rg-api-dev-eastus' (East US) - -[2026-02-18T14:31:45Z] Stage 1: Requirements Gathering -[2026-02-18T14:31:45Z] ✓ Subscription access verified -[2026-02-18T14:31:46Z] ✓ Resource naming validated -[2026-02-18T14:31:47Z] ✓ Requirements document saved - -[2026-02-18T14:32:10Z] Stage 2: Template Generation -[2026-02-18T14:32:11Z] ✓ ARM template generated -[2026-02-18T14:32:12Z] ✓ Schema validation passed -[2026-02-18T14:32:13Z] ✓ Best practices applied - -[2026-02-18T14:33:00Z] Stage 3: User Confirmation -[2026-02-18T14:33:00Z] Awaiting user approval... -[2026-02-18T14:33:45Z] ✓ User confirmed deployment - -[2026-02-18T14:33:46Z] Stage 4: Deployment Execution -[2026-02-18T14:33:46Z] Creating resource group: rg-api-dev-eastus -[2026-02-18T14:33:50Z] ✓ Resource group created -[2026-02-18T14:33:51Z] Deploying ARM template... -[2026-02-18T14:34:05Z] ⧗ Deployment in progress (15s) -[2026-02-18T14:34:20Z] ⧗ Deployment in progress (30s) -[2026-02-18T14:37:22Z] ✓ Deployment succeeded (3m36s) - -[2026-02-18T14:37:23Z] Stage 5: Integration Testing -[2026-02-18T14:37:30Z] ✓ Function App accessible -[2026-02-18T14:37:31Z] ✓ HTTPS enforced -[2026-02-18T14:37:32Z] ✓ Application Insights connected - -[2026-02-18T14:37:33Z] Deployment completed successfully -[2026-02-18T14:37:33Z] Total duration: 7m11s -``` - -### tests.json - -Integration test results: - -```json -{ - "deploymentId": "deploy-20260218-143022", - "timestamp": "2026-02-18T14:37:33Z", - "resourceType": "Microsoft.Web/sites", - "resourceName": "func-api-dev-eastus", - "tests": [ - { - "name": "HTTPS Endpoint Accessibility", - "category": "connectivity", - "status": "passed", - "duration": 245, - "details": "Response: 200 OK in 245ms" - }, - { - "name": "Response Time", - "category": "performance", - "status": "passed", - "threshold": 3000, - "actual": 245, - "details": "Well within threshold" - }, - { - "name": "HTTPS Enforcement", - "category": "security", - "status": "passed", - "details": "HTTP redirects to HTTPS" - }, - { - "name": "Application Insights", - "category": "monitoring", - "status": "passed", - "details": "Instrumentation key configured" - } - ], - "summary": { - "total": 4, - "passed": 4, - "failed": 0, - "warnings": 0 - }, - "overallStatus": "healthy" -} -``` - -### architecture.md - -Mermaid architecture diagram generated during template creation. Shown to user during confirmation and saved for reference: - -````markdown -# Architecture Diagram - -```mermaid -graph LR - Internet["🌐 Internet"] --> FuncApp["⚡ func-api-dev-eastus"] - FuncApp --> Storage["💾 stfuncapidev8k3m"] - FuncApp -.->|"instrumentation key"| AppInsights["📊 appi-api-dev-eastus"] - - subgraph rg-api-dev-eastus - FuncApp - Storage - AppInsights - end -``` - -## Resource Inventory - -| Resource | Type | Name | Region | CAF | -|----------|------|------|--------|-----| -| Function App | Microsoft.Web/sites | func-api-dev-eastus | East US | ✓ func | -| Storage Account | Microsoft.Storage/storageAccounts | stfuncapidev8k3m | East US | ✓ st | -| Application Insights | Microsoft.Insights/components | appi-api-dev-eastus | East US | ✓ appi | -```` - -### error.log - -Error details for failed deployments: - -``` -[2026-02-18T14:35:15Z] ERROR: Deployment Failed -[2026-02-18T14:35:15Z] Resource: Microsoft.Web/sites/func-api-dev-eastus -[2026-02-18T14:35:15Z] Error Code: QuotaExceeded -[2026-02-18T14:35:15Z] Message: The subscription has reached its quota limit for Function Apps in East US region - -Possible Causes: -1. Subscription quota limit reached (check: az vm list-usage --location eastus) -2. Region capacity constraints -3. Trial/free tier limitations - -Recommended Actions: -A. Request quota increase via Azure Portal -B. Try different region (e.g., West US 2) -C. Delete unused Function Apps to free quota -D. Upgrade subscription tier - -Stack Trace: - at Microsoft.Azure.Management.WebSites.SitesOperationsExtensions.CreateOrUpdate - at Git-Ape.ResourceDeployer.DeployResource - at Git-Ape.Orchestrator.ExecuteDeployment - -Related Documentation: -- https://learn.microsoft.com/azure/azure-resource-manager/management/request-limits-and-throttling -- https://learn.microsoft.com/azure/azure-functions/functions-scale -``` - -## Using the Deployment Manager - -The `.github/scripts/deployment-manager.sh` utility helps manage deployment state: - -### List All Deployments - -```bash -.github/scripts/deployment-manager.sh list -``` - -Output: -``` -Recent Deployments ------------------------------------------------------------ -✓ deploy-20260218-163500 - Status: succeeded | Resources: 3 | Time: 2026-02-18T16:35:00Z - -↶ deploy-20260218-151030 - Status: rolled-back | Resources: 1 | Time: 2026-02-18T15:10:30Z - -✗ deploy-20260218-143022 - Status: failed | Resources: 0 | Time: 2026-02-18T14:30:22Z -``` - -### Show Deployment Details - -```bash -.github/scripts/deployment-manager.sh show deploy-20260218-163500 -``` - -### Export as Reusable Template - -```bash -.github/scripts/deployment-manager.sh export deploy-20260218-163500 templates/my-function-app.json -``` - -Creates: -- `templates/my-function-app.json` - ARM template -- `templates/my-function-app.parameters.json` - Parameters file - -### Clean Up Old Deployments - -```bash -# Keep 10 most recent deployments, delete older ones -.github/scripts/deployment-manager.sh clean 10 -``` - -### Validate Deployment State - -```bash -.github/scripts/deployment-manager.sh validate deploy-20260218-163500 -``` - -Checks: -- ✓ metadata.json exists and is valid JSON -- ✓ requirements.json exists and is valid JSON -- ✓ template.json exists and is valid JSON -- ⚠ deployment.log present (optional) -- ⚠ tests.json present (optional) - -## Reusing Deployments - -### Simple Reuse - -``` -User: @git-ape deploy the same Function App as last time - -Agent: Found previous deployment: deploy-20260218-163500 - -Resources from previous deployment: -- Python Function App (3.11, Consumption) -- Storage Account (Standard_LRS) -- Application Insights - -Would you like to: -A. Use the same configuration (I'll update names/timestamps) -B. Modify the configuration before deployment -C. Choose a different previous deployment - -User: A - -Agent: I'll update the names and deploy: -- func-api-dev-eastus → func-api-dev-eastus2 -- stfuncdeveastus8k3m → stfuncdeveastus9p7r - -Proceed? -``` - -### Selective Reuse - -``` -User: @git-ape use the storage configuration from deploy-20260218-143022 but for a different region - -Agent: Loading storage configuration from deploy-20260218-143022... - -Previous config: -- Storage Account: Standard_LRS -- Region: East US -- Kind: StorageV2 -- HTTPS only: true - -What region would you like? - -User: West Europe - -Agent: I'll create: -- Storage Account: stfuncdevwesteurope4k2m -- Region: West Europe -- Same SKU and configuration as previous deployment - -Proceed? -``` - -## Best Practices - -### Audit Trail - -Keep deployment state as an audit trail: - -```bash -# Never delete .azure/deployments/ directory -# Add to .gitignore if contains sensitive data -echo ".azure/deployments/" >> .gitignore - -# Or commit for team visibility (remove sensitive values first) -git add .azure/deployments/*/metadata.json -git add .azure/deployments/*/requirements.json -git commit -m "Record deployment metadata" -``` - -### Cost Tracking - -Use deployment state to track costs over time: - -```bash -# Extract estimated costs from all deployments -jq -r '.estimatedCost' .azure/deployments/*/metadata.json | awk '{sum+=$1} END {print "Total estimated monthly cost: $" sum}' -``` - -### Disaster Recovery - -Export critical deployments as templates: - -```bash -# Export production deployments -for deploy in $(ls -d .azure/deployments/deploy-*-prod-*); do - .github/scripts/deployment-manager.sh export $(basename "$deploy") "backups/$(basename "$deploy").json" -done -``` - -### Documentation - -Link deployment IDs in documentation: - -```markdown -## Production Environment - -Current deployment: `deploy-20260218-163500` - -Resources: -- Function App: func-api-prod-eastus -- Storage: stfuncprodeastus8k3m -- App Insights: appi-api-prod-eastus - -See `.azure/deployments/deploy-20260218-163500/` for full configuration. -``` - -## Troubleshooting - -### Missing Deployment Files - -If a deployment is missing files: - -```bash -# Validate what's missing -.github/scripts/deployment-manager.sh validate deploy-20260218-143022 - -# Shows: -# ✗ Missing requirements.json -# ✓ metadata.json found -# ✗ template.json not found -``` - -**Cause:** Deployment was interrupted before saving all files. - -**Solution:** Re-run the deployment or manually create missing files. - -### Corrupted JSON Files - -```bash -# Validate automatically detects corrupted JSON -.github/scripts/deployment-manager.sh validate deploy-20260218-143022 - -# Shows: -# ✓ metadata.json found -# ✗ Invalid JSON format -``` - -**Cause:** File was truncated or manually edited incorrectly. - -**Solution:** -```bash -# Check JSON syntax -jq '.' .azure/deployments/deploy-20260218-143022/metadata.json - -# Fix manually or delete and re-run deployment -``` - -### Old Deployments Taking Space - -```bash -# Check disk usage -du -sh .azure/deployments/*/ - -# Clean up (keep 5 most recent) -.github/scripts/deployment-manager.sh clean 5 -``` - -## Related Documentation - -- [Azure MCP Setup Guide](./AZURE_MCP_SETUP.md) -- [Integration Testing Guide](../skills/azure-integration-tester/SKILL.md) -- [ARM Template Best Practices](https://learn.microsoft.com/azure/azure-resource-manager/templates/best-practices) diff --git a/docs/EXAMPLES.md b/docs/EXAMPLES.md deleted file mode 100644 index 14e69b8..0000000 --- a/docs/EXAMPLES.md +++ /dev/null @@ -1,94 +0,0 @@ -# Git-Ape Examples - -This file keeps the longer usage examples out of the main README. - -## Example 1: Deploy a Python Function App - -```text -User: @git-ape deploy a Python function app - -Agent: I'll help you deploy an Azure Function App through the guided workflow. - -Stage 1: Requirements -- Region: East US -- Runtime: Python 3.11 -- Plan: Consumption -- Monitoring: Application Insights enabled - -Stage 2: Review -- Function App: func-api-dev-eastus -- Storage Account: stfuncapidev8k3m -- App Insights: appi-api-dev-eastus -- Security: HTTPS only, managed identity, TLS 1.2 -- Cost estimate: about $0.40/month for a light workload - -Agent: Confirm deployment. -User: yes - -Stage 3: Deploy -- Resource group created -- Storage account created -- App Insights created -- Function App created - -Stage 4: Validate -- Endpoint reachable -- HTTPS enforced -- Monitoring connected -``` - -## Example 2: Deploy a Web App with SQL Database - -```text -User: @git-ape deploy a web app with SQL database - -Agent: I will collect the app, plan, database, and connectivity requirements. - -Review summary: -- App Service Plan: asp-webapp-dev-eastus -- Web App: app-webapp-dev-eastus -- SQL Server: sql-webapp-dev-eastus -- SQL Database: sqldb-webapp-dev -- Application Insights: appi-webapp-dev-eastus - -Agent: Generated template, security review, and estimated cost. -User: proceed - -Result: -- Resources deployed successfully -- Web app reachable -- Database connectivity validated -``` - -## Example 3: Run the Integration Tester - -```text -User: /azure-integration-tester - -Agent: Provide the deployment or resource details. - -User: Test func-api-dev-eastus in rg-api-dev-eastus - -Agent: Running checks... -- HTTPS endpoint accessible -- Response time within threshold -- Application Insights connected -- Managed identity present -``` - -## Example 4: Typical Workflow - -```text -1. Configure Azure MCP and sign in with Azure CLI. -2. Ask @git-ape to deploy a resource or stack. -3. Review the generated template, security output, and cost estimate. -4. Confirm deployment. -5. Review the saved artifacts under .azure/deployments/. -``` - -## Related Docs - -- [AZURE_MCP_SETUP.md](AZURE_MCP_SETUP.md) -- [ONBOARDING.md](ONBOARDING.md) -- [DEPLOYMENT_STATE.md](DEPLOYMENT_STATE.md) -- [DRIFT_DETECTION.md](DRIFT_DETECTION.md) \ No newline at end of file diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md deleted file mode 100644 index a6c0525..0000000 --- a/docs/ONBOARDING.md +++ /dev/null @@ -1,810 +0,0 @@ -# Git-Ape Onboarding Guide - -> [!WARNING] -> EXPERIMENTAL ONLY: This onboarding flow is provided for testing and evaluation. -> Do **not** use Git-Ape in production environments. -> Validate all generated configuration manually before any real deployment. - -Set up a GitHub repository to use Git-Ape's CI/CD pipelines for Azure deployments. This guide covers Entra ID (Azure AD) configuration, OIDC federation, RBAC, and GitHub repository setup. - -Git-Ape supports two onboarding modes: - -| Mode | Use case | GitHub Environments | Secrets scope | -|------|----------|-------------------|---------------| -| **Single environment** | One Azure subscription for all deployments | `azure-deploy`, `azure-destroy` | Repository-level | -| **Multi-environment** | Separate subscriptions per stage (dev/staging/prod) | `azure-deploy-dev`, `azure-deploy-staging`, `azure-deploy-prod`, `azure-destroy` | Environment-level | - -## How OIDC Authentication Works - -Git-Ape uses OpenID Connect (OIDC) federation between GitHub Actions and Microsoft Entra ID. No client secrets are stored — GitHub mints a short-lived token at workflow runtime, and Entra exchanges it for an Azure access token based on a trust relationship you configure once. - -```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -sequenceDiagram - autonumber - participant GH as GitHub Actions
(workflow run) - participant Entra as Microsoft Entra ID
(App Registration) - participant ARM as Azure Resource Manager - - GH->>GH: Mint OIDC token
subject: repo:org/repo:ref:refs/heads/main - GH->>Entra: Exchange token
(client_id + federated credential) - Entra->>Entra: Verify subject matches
federated credential - Entra-->>GH: Azure access token
(short-lived, ~1h) - GH->>ARM: az deployment sub create
Authorization: Bearer [token] - ARM->>ARM: Check RBAC role assignment
on subscription - ARM-->>GH: Deployment result -``` - -**Trust components you configure during onboarding:** - -```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -graph LR - GH["GitHub Repo
org/repo"] - FC["Federated Credential
subject: repo:org/repo:..."] - APP["Entra App Registration
client_id + tenant_id"] - SP["Service Principal
object_id"] - SUB["Azure Subscription
subscription_id"] - ROLE["RBAC Role
Contributor / UAA"] - - GH -->|trusts| FC - FC -->|attached to| APP - APP -->|backed by| SP - SP -->|assigned| ROLE - ROLE -->|scoped to| SUB - - classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 - classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 - classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d - - class GH,FC gh - class APP,SP entra - class SUB,ROLE azure -``` - -The **Quick Start** below automates all of this. The **Manual Setup** section walks through each component individually. - -## Quick Start (Automated) - -You can run onboarding from Copilot Chat with: - -```text -@Git-Ape Onboarding onboard this repository -``` - -or directly invoke the skill: - -```text -/git-ape-onboarding -``` - -Both paths execute the same onboarding playbook through Copilot Chat. - -The skill-driven onboarding flow will gather or use: -1. **GitHub repository URL** — e.g. `https://github.com/your-org/your-repo` -2. **Entra ID App Registration name** — e.g. `sp-git-ape-your-repo` -3. **Single or multi-environment mode** — choose whether to deploy to one or multiple Azure subscriptions -4. **Azure subscription(s)** — defaults to your current `az` subscription -5. **RBAC role(s)** — Contributor (default) or Contributor + User Access Administrator - -### Parameterized Usage - -**Single environment:** - -```text -/git-ape-onboarding onboard https://github.com/your-org/your-repo on subscription 00000000-0000-0000-0000-000000000000 with Contributor -``` - -**Multi-environment:** - -```text -/git-ape-onboarding onboard https://github.com/your-org/your-repo with dev on 11111111-1111-1111-1111-111111111111 as Contributor, staging on 22222222-2222-2222-2222-222222222222 as Contributor, prod on 33333333-3333-3333-3333-333333333333 as Contributor+UserAccessAdministrator -``` - -Each multi-environment entry creates: -- A GitHub environment `azure-deploy-{name}` with environment-level secrets -- A federated credential scoped to that environment -- An RBAC role assignment on the specified subscription - ---- - -## Manual Setup - -If you prefer to inspect or execute each component manually, follow the steps below. - -### Prerequisites - -> **Tip:** Run `/prereq-check` in Copilot Chat to automatically validate all tools and auth sessions. - -| Tool | Minimum Version | Purpose | -|------|-----------------|---------| -| Azure CLI (`az`) | 2.50+ | Azure resource management, RBAC, OIDC | -| GitHub CLI (`gh`) | 2.0+ | Repo secrets, environments, OIDC detection | -| jq | 1.6+ | JSON parsing in scripts and workflows | -| git | any | Version control (usually pre-installed) | - -**Install (pick your platform):** - -
macOS (Homebrew) - -```bash -brew install azure-cli gh jq -``` -
- -
Ubuntu / Debian - -```bash -# Azure CLI -curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash - -# GitHub CLI -(type -p wget >/dev/null || sudo apt-get install wget -y) \ - && sudo mkdir -p -m 755 /etc/apt/keyrings \ - && out=$(mktemp) && wget -nv -O"$out" https://cli.github.com/packages/githubcli-archive-keyring.gpg \ - && cat "$out" | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \ - && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \ - && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ - && sudo apt-get update && sudo apt-get install gh -y - -# jq -sudo apt-get install -y jq -``` -
- -
Windows (PowerShell) - -```powershell -winget install Microsoft.AzureCLI -winget install GitHub.cli -winget install jqlang.jq -``` - -> **Note:** Git-Ape skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash. -
- -You must be logged in to both: -```bash -az login # Azure — needs Owner or User Access Administrator on the subscription(s) -gh auth login # GitHub — needs admin access to the target repository -``` - -### Step 1: Create an Entra ID App Registration - -This creates the identity that GitHub Actions will use to authenticate with Azure. - -```bash -# Choose a name for your app registration -SP_NAME="sp-git-ape-your-repo" - -# Create the app registration -CLIENT_ID=$(az ad app create --display-name "$SP_NAME" --query appId -o tsv) -echo "Client ID: $CLIENT_ID" - -# Create the service principal -az ad sp create --id "$CLIENT_ID" - -# Note your tenant ID -TENANT_ID=$(az account show --query tenantId -o tsv) -echo "Tenant ID: $TENANT_ID" -``` - -### Step 2: Configure OIDC Federated Credentials - -OIDC eliminates stored secrets by letting GitHub Actions exchange a short-lived token for Azure access at runtime. The number of federated credentials depends on your mode. - -```bash -# Get the app object ID (different from client ID) -OBJECT_ID=$(az ad app show --id "$CLIENT_ID" --query id -o tsv) - -# Your GitHub repo (org/repo format) -REPO="your-org/your-repo" - -# Detect whether the GitHub org uses default or customized OIDC subjects -USE_DEFAULT_SUBJECT=$(gh api "orgs/${REPO%%/*}/actions/oidc/customization/sub" --jq '.use_default' 2>/dev/null || echo true) - -if [[ "$USE_DEFAULT_SUBJECT" == "false" ]]; then - REPO_ID=$(gh api "repos/$REPO" --jq '.id') - OWNER_ID=$(gh api "repos/$REPO" --jq '.owner.id') - OIDC_PREFIX="repository_owner_id:${OWNER_ID}:repository_id:${REPO_ID}" -else - OIDC_PREFIX="repo:$REPO" -fi -``` - -Use `$OIDC_PREFIX` for all subjects below. On orgs with a customized subject template, `repo:org/repo:...` will fail with `AADSTS700213`. - -#### 2a. Main Branch (merge-triggered deployments) - -```bash -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-main-branch", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':ref:refs/heads/main", - "description": "Main branch deployments", - "audiences": ["api://AzureADTokenExchange"] -}' -``` - -#### 2b. Pull Requests (plan validation) - -```bash -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-pull-request", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':pull_request", - "description": "Pull request validation", - "audiences": ["api://AzureADTokenExchange"] -}' -``` - -#### 2c. Deploy Environment(s) - -
-Single environment mode - -Create one federated credential for the `azure-deploy` environment: - -```bash -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy", - "description": "Deploy environment", - "audiences": ["api://AzureADTokenExchange"] -}' -``` - -
- -
-Multi-environment mode - -Create one federated credential per environment. Each maps to a separate GitHub environment: - -```bash -# Dev environment -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy-dev", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-dev", - "description": "Deploy environment (dev)", - "audiences": ["api://AzureADTokenExchange"] -}' - -# Staging environment -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy-staging", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-staging", - "description": "Deploy environment (staging)", - "audiences": ["api://AzureADTokenExchange"] -}' - -# Production environment -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy-prod", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-prod", - "description": "Deploy environment (prod)", - "audiences": ["api://AzureADTokenExchange"] -}' -``` - -
- -#### 2d. Destroy Environment (shared across all modes) - -```bash -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-destroy", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-destroy", - "description": "Destroy environment", - "audiences": ["api://AzureADTokenExchange"] -}' -``` - -#### Verify Credentials - -```bash -az ad app federated-credential list --id "$OBJECT_ID" --query "[].{name:name, subject:subject}" -o table -``` - -**Single environment** — expected 4 credentials: -``` -Name Subject ------------------ ----------------------------------------------- -fc-main-branch :ref:refs/heads/main -fc-pull-request :pull_request -fc-env-deploy :environment:azure-deploy -fc-env-destroy :environment:azure-destroy -``` - -**Multi-environment (3 envs)** — expected 6 credentials: -``` -Name Subject ----------------------- --------------------------------------------------- -fc-main-branch :ref:refs/heads/main -fc-pull-request :pull_request -fc-env-deploy-dev :environment:azure-deploy-dev -fc-env-deploy-staging :environment:azure-deploy-staging -fc-env-deploy-prod :environment:azure-deploy-prod -fc-env-destroy :environment:azure-destroy -``` - -### Step 3: Assign RBAC Roles - -Grant the service principal permissions on your Azure subscription(s). - -#### Single Environment - -```bash -SUBSCRIPTION_ID=$(az account show --query id -o tsv) -SP_OBJECT_ID=$(az ad sp show --id "$CLIENT_ID" --query id -o tsv) - -# Contributor — create, modify, and delete resources -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "Contributor" \ - --scope "/subscriptions/$SUBSCRIPTION_ID" -``` - -If your templates include RBAC role assignments (e.g., managed identity access to storage), also add: - -```bash -# User Access Administrator — manage role assignments -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "User Access Administrator" \ - --scope "/subscriptions/$SUBSCRIPTION_ID" -``` - -#### Multi-Environment - -Assign roles on each target subscription. Each environment can have a different role if needed: - -```bash -SP_OBJECT_ID=$(az ad sp show --id "$CLIENT_ID" --query id -o tsv) - -# Dev — Contributor only -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "Contributor" \ - --scope "/subscriptions/$DEV_SUBSCRIPTION_ID" - -# Staging — Contributor only -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "Contributor" \ - --scope "/subscriptions/$STAGING_SUBSCRIPTION_ID" - -# Production — Contributor + User Access Administrator -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "Contributor" \ - --scope "/subscriptions/$PROD_SUBSCRIPTION_ID" - -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "User Access Administrator" \ - --scope "/subscriptions/$PROD_SUBSCRIPTION_ID" -``` - -> **Note:** If multiple environments share the same subscription, you only need one set of role assignments for that subscription. - -#### Verify RBAC - -```bash -az role assignment list --assignee "$SP_OBJECT_ID" --query "[].{role:roleDefinitionName, scope:scope}" -o table -``` - -### Step 4: Configure GitHub Repository - -#### 4a. Set GitHub Secrets - -These are **identifiers**, not credentials — OIDC means no actual secrets are stored. - -
-Single environment mode - -Set secrets at the **repository level** (shared by all workflows): - -```bash -REPO="your-org/your-repo" - -echo "$CLIENT_ID" | gh secret set AZURE_CLIENT_ID -R "$REPO" -echo "$TENANT_ID" | gh secret set AZURE_TENANT_ID -R "$REPO" -echo "$SUBSCRIPTION_ID" | gh secret set AZURE_SUBSCRIPTION_ID -R "$REPO" -``` - -
- -
-Multi-environment mode - -Set shared secrets at the **repository level**, then set the subscription per **environment**: - -```bash -REPO="your-org/your-repo" - -# Repo-level secrets (shared) -echo "$CLIENT_ID" | gh secret set AZURE_CLIENT_ID -R "$REPO" -echo "$TENANT_ID" | gh secret set AZURE_TENANT_ID -R "$REPO" - -# Per-environment secrets -# Dev -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-dev" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-dev" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-dev" --body "$DEV_SUBSCRIPTION_ID" - -# Staging -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-staging" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-staging" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-staging" --body "$STAGING_SUBSCRIPTION_ID" - -# Production -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-prod" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-prod" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-prod" --body "$PROD_SUBSCRIPTION_ID" - -# Destroy environment (uses first subscription as default) -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-destroy" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-destroy" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-destroy" --body "$DEV_SUBSCRIPTION_ID" -``` - -> **Tip:** Environment-level secrets override repo-level secrets. By setting `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` at the environment level, you can later switch to separate app registrations per environment without modifying workflows. - -
- -#### 4b. Create GitHub Environments - -
-Single environment mode - -**azure-deploy** — for deployment jobs: - -```bash -# Create environment with branch policy (main only) -gh api -X PUT "repos/$REPO/environments/azure-deploy" --input - <<'EOF' -{ - "deployment_branch_policy": { - "protected_branches": false, - "custom_branch_policies": true - } -} -EOF - -# Allow main branch -gh api -X POST "repos/$REPO/environments/azure-deploy/deployment-branch-policies" --input - <<'EOF' -{ - "name": "main", - "type": "branch" -} -EOF -``` - -
- -
-Multi-environment mode - -Create one environment per deployment target: - -```bash -for ENV_NAME in dev staging prod; do - # Create environment with branch policy (main only) - gh api -X PUT "repos/$REPO/environments/azure-deploy-${ENV_NAME}" --input - <<'EOF' -{ - "deployment_branch_policy": { - "protected_branches": false, - "custom_branch_policies": true - } -} -EOF - - # Allow main branch - gh api -X POST "repos/$REPO/environments/azure-deploy-${ENV_NAME}/deployment-branch-policies" --input - <<'EOF' -{ - "name": "main", - "type": "branch" -} -EOF -done -``` - -
- -**azure-destroy** — for destroy jobs (same for both modes): - -```bash -gh api -X PUT "repos/$REPO/environments/azure-destroy" --input - <<'EOF' -{ - "deployment_branch_policy": null -} -EOF -``` - -#### 4c. (Optional) Required Reviewers - -For production deployments, add required reviewers to the deploy environment: - -1. Go to **Settings → Environments → azure-deploy** (or **azure-deploy-prod** in multi-env mode) -2. Check **Required reviewers** -3. Add team members who should approve deployments - -In multi-environment mode, you might want: -- `azure-deploy-dev` — no reviewer required (fast iteration) -- `azure-deploy-staging` — optional reviewer -- `azure-deploy-prod` — required reviewer (gate for production) - -### Step 5: Copy Git-Ape Workflows - -Copy the workflow files to your repository: - -```bash -# Clone the git-ape repo if you haven't -git clone https://github.com/your-org/git-ape.git /tmp/git-ape - -# Copy workflows to your repo -cp /tmp/git-ape/.github/workflows/git-ape-*.yml your-repo/.github/workflows/ - -# Commit and push -cd your-repo -git add .github/workflows/ -git commit -m "feat: add Git-Ape deployment workflows" -git push -``` - -The following workflows will be added: - -| Workflow | Trigger | Purpose | -|----------|---------|---------| -| `git-ape-plan.yml` | PR with template changes | Validate, security scan, what-if, cost estimate | -| `git-ape-deploy.yml` | Merge to main or `/deploy` comment | Execute ARM deployment | -| `git-ape-destroy.yml` | Merge PR with `destroy-requested` status | Delete resource group | -| `git-ape-verify.yml` | Manual dispatch | Verify OIDC, RBAC, and pipeline health | - -> **Note:** Drift detection and TTL-based cleanup are being replaced by agentic workflows — coming soon. - -### Step 6: Verify Setup - -Create a test deployment to verify the pipeline works: - -```bash -# Create a minimal test template -mkdir -p .azure/deployments/deploy-test - -cat > .azure/deployments/deploy-test/template.json <<'EOF' -{ - "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "location": { "type": "string", "defaultValue": "eastus" } - }, - "resources": [] -} -EOF - -cat > .azure/deployments/deploy-test/parameters.json <<'EOF' -{ - "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", - "contentVersion": "1.0.0.0", - "parameters": { - "location": { "value": "eastus" } - } -} -EOF - -# Open a PR -git checkout -b test/git-ape-onboarding -git add .azure/deployments/deploy-test/ -git commit -m "test: verify git-ape pipeline" -git push -u origin test/git-ape-onboarding -gh pr create --title "Test: Git-Ape onboarding" --body "Verify the OIDC pipeline works end-to-end." -``` - -If the PR triggers the `Git-Ape: Plan` workflow and it succeeds, your setup is complete. - ---- - -## Optional: Slack Notifications - -To get Slack notifications on deploy/destroy/drift events: - -1. Create a Slack Incoming Webhook: [Slack API → Incoming Webhooks](https://api.slack.com/messaging/webhooks) -2. Set the secret: - ```bash - echo "https://hooks.slack.com/services/T.../B.../..." | gh secret set SLACK_WEBHOOK_URL -R "$REPO" - ``` - ---- - -## Troubleshooting - -### "AADSTS700016: Application not found" - -The federated credential subject doesn't match the workflow's token. Verify: -```bash -az ad app federated-credential list --id "$OBJECT_ID" -o table -``` - -Common issues: -- Repository name is case-sensitive in the `subject` field -- `pull_request` subject is needed for PR-triggered workflows -- `environment:azure-deploy` subject is needed for jobs using `environment: azure-deploy` - -### "AuthorizationFailed" during deployment - -The service principal lacks permissions. Check assignments: -```bash -az role assignment list --assignee "$SP_OBJECT_ID" -o table -``` - -Ensure **Contributor** role is assigned at the subscription scope. - -### "Resource group not found" in plan workflow - -The OIDC token exchange succeeded but the subscription doesn't match. Verify: -```bash -# Check which subscription the service principal can access -az account list --query "[?tenantId=='$TENANT_ID']" -o table -``` - -### GitHub environment not created - -Environment creation requires admin access to the repository. Ask a repo admin to create the `azure-deploy` and `azure-destroy` environments manually via **Settings → Environments**. - ---- - -## Architecture - -### Single Environment Mode - -```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -graph TD - subgraph GH["GitHub Repository"] - direction TB - SEC["Repo Secrets
AZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_SUBSCRIPTION_ID
SLACK_WEBHOOK_URL (optional)"] - ENVD["azure-deploy
main branch only"] - ENVX["azure-destroy
main branch only"] - WF["Workflows
git-ape-plan.yml (PR)
git-ape-deploy.yml (main / azure-deploy)
git-ape-destroy.yml (azure-destroy)
git-ape-verify.yml (dispatch)"] - SEC --- WF - ENVD --- WF - ENVX --- WF - end - - subgraph ENTRA["Microsoft Entra ID"] - APP["App Registration
sp-git-ape-{repo}
client_id + tenant_id"] - FC["Federated Credentials
• repo:org/repo:ref:refs/heads/main
• repo:org/repo:pull_request
• repo:org/repo:environment:azure-deploy
• repo:org/repo:environment:azure-destroy"] - APP --- FC - end - - subgraph AZ["Azure Subscription"] - ROLE["RBAC
Contributor
(+ UAA if templates assign roles)"] - RG1["rg-app-dev"] - RG2["rg-api-prod"] - RG3["rg-data-stg"] - ROLE --- RG1 - ROLE --- RG2 - ROLE --- RG3 - end - - WF -->|"OIDC token exchange"| FC - APP -->|"Service Principal"| ROLE - - classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 - classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 - classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d - - class SEC,ENVD,ENVX,WF gh - class APP,FC entra - class ROLE,RG1,RG2,RG3 azure -``` - -### Multi-Environment Mode - -```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -graph TD - subgraph GH["GitHub Repository"] - direction TB - REPO["Repo-level Secrets
AZURE_CLIENT_ID
AZURE_TENANT_ID"] - EDEV["azure-deploy-dev
SUBSCRIPTION_ID → Dev"] - ESTG["azure-deploy-staging
SUBSCRIPTION_ID → Staging"] - EPRD["azure-deploy-prod
SUBSCRIPTION_ID → Prod
⚠️ Required reviewers"] - EDST["azure-destroy
SUBSCRIPTION_ID → Default"] - end - - subgraph ENTRA["Microsoft Entra ID"] - APP["App Registration
sp-git-ape-{repo}"] - FC["Federated Credentials
• ref:refs/heads/main
• pull_request
• environment:azure-deploy-dev
• environment:azure-deploy-staging
• environment:azure-deploy-prod
• environment:azure-destroy"] - APP --- FC - end - - DEV["Dev Subscription
Contributor
rg-*-dev"] - STG["Staging Subscription
Contributor
rg-*-stg"] - PRD["Prod Subscription
Contributor + UAA
rg-*-prod"] - - REPO --- EDEV - REPO --- ESTG - REPO --- EPRD - REPO --- EDST - - EDEV -->|"OIDC"| FC - ESTG -->|"OIDC"| FC - EPRD -->|"OIDC"| FC - EDST -->|"OIDC"| FC - - APP -->|"Service Principal"| DEV - APP -->|"Service Principal"| STG - APP -->|"Service Principal"| PRD - - classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 - classDef ghprod fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 - classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 - classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d - classDef azureprod fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d - - class REPO,EDEV,ESTG,EDST gh - class EPRD ghprod - class APP,FC entra - class DEV,STG azure - class PRD azureprod -``` - ---- - -## Security Considerations - -| Aspect | Implementation | -|--------|---------------| -| **No stored secrets** | OIDC federated identity — no client secrets or certificates | -| **Scoped access** | Federated credentials are scoped per repo + branch/environment | -| **Least privilege** | Only Contributor role by default; add UAA only if needed | -| **Environment gates** | Deploy environments restricted to `main` branch; reviewers optional | -| **Destructive protection** | `azure-destroy` environment can require manual approval | -| **Subscription isolation** | Multi-env mode targets separate subscriptions per stage | -| **Audit trail** | All deployments logged in `state.json` with actor, timestamp, run URL | - -### Multi-Environment Security Best Practices - -When using multi-environment mode: - -1. **Required reviewers on production** — Always add reviewers to `azure-deploy-prod` -2. **Separate subscriptions** — Use distinct subscriptions for dev, staging, and prod to enforce blast radius isolation -3. **Graduated RBAC** — Use minimal roles in dev (Contributor) and additional roles in prod only when needed -4. **Environment variables for config** — Use GitHub environment variables (not secrets) for non-sensitive environment-specific values like region or resource name prefixes -5. **Deployment promotion** — Deploy to dev first, then staging, then prod — never skip stages - -### Using Environments in Workflows - -With multi-environment mode, update your deploy workflow to select the correct environment: - -```yaml -# In git-ape-deploy.yml, change the environment field to be dynamic: -deploy: - environment: azure-deploy-${{ steps.params.outputs.environment }} - # This resolves to azure-deploy-dev, azure-deploy-staging, or azure-deploy-prod - # based on the "environment" parameter in parameters.json -``` - -The `environment` parameter in your `parameters.json` determines which GitHub environment (and therefore which Azure subscription) is used: - -```json -{ - "parameters": { - "environment": { "value": "prod" }, - "location": { "value": "eastus" }, - "project": { "value": "myapp" } - } -} -``` diff --git a/scripts/generate-docs.js b/scripts/generate-docs.js index b450727..f69d8e4 100644 --- a/scripts/generate-docs.js +++ b/scripts/generate-docs.js @@ -25,7 +25,7 @@ const AGENTS_DIR = path.join(ROOT, '.github', 'agents'); const SKILLS_DIR = path.join(ROOT, '.github', 'skills'); const WORKFLOWS_DIR = path.join(ROOT, '.github', 'workflows'); -const AUTO_HEADER = '\n\n'; +const AUTO_COMMENT = ''; // --------------------------------------------------------------------------- // Helpers @@ -36,8 +36,19 @@ function ensureDir(dir) { } function writeAutoGenerated(filePath, source, content) { - const header = AUTO_HEADER.replace('{source}', source); - fs.writeFileSync(filePath, header + content, 'utf8'); + const comment = AUTO_COMMENT.replace('{source}', source); + // Insert the auto-generated comment AFTER the frontmatter block so Docusaurus + // can parse the `---` fences at line 1. If there is no frontmatter the comment + // is simply prepended. + const fmRegex = /^(---\n[\s\S]*?\n---\n)/; + const match = content.match(fmRegex); + let output; + if (match) { + output = match[1] + '\n' + comment + '\n\n' + content.slice(match[1].length); + } else { + output = comment + '\n\n' + content; + } + fs.writeFileSync(filePath, output, 'utf8'); console.log(` ✓ ${path.relative(ROOT, filePath)}`); } @@ -193,6 +204,17 @@ graph TD IE["IaC Exporter"] OB["Git-Ape Onboarding"] end + + classDef orchestrator fill:#1f6feb,stroke:#0b3d91,stroke-width:2px,color:#ffffff + classDef pipeline fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef advisory fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef utility fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + class GA orchestrator + class RG,TG,WR,RD pipeline + class SG,UC gate + class PA,PO advisory + class IE,OB utility \`\`\` `; @@ -309,6 +331,13 @@ graph LR S3["/${skills.filter(s => s.phase === 'Operations').map(s => s.name).join('\\n/')}"] end Pre --> Post --> Ops + + classDef pre fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef post fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef ops fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + class S1 pre + class S2 post + class S3 ops \`\`\` `; @@ -325,7 +354,7 @@ function generateWorkflowDocs() { const outDir = path.join(DOCS_OUT, 'workflows'); ensureDir(outDir); - const workflowFiles = fs.readdirSync(WORKFLOWS_DIR).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml')); + const workflowFiles = fs.readdirSync(WORKFLOWS_DIR).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml') || f.endsWith('.exampleyml')); const workflows = []; for (const file of workflowFiles) { @@ -340,7 +369,8 @@ function generateWorkflowDocs() { } const name = wf.name || file; - const slug = slugify(file.replace(/\.ya?ml$/, '')); + // Normalise slug: strip both .yml/.yaml and .exampleyml extensions + const slug = slugify(file.replace(/\.(example)?ya?ml$/, '')); const triggers = wf.on || wf.true || {}; const jobs = wf.jobs || {}; const jobNames = Object.keys(jobs); @@ -457,6 +487,17 @@ graph LR DestroyMerge --> DestroyWF["git-ape-destroy.yml
Delete Resources"] Manual["Manual Dispatch"] --> Verify["git-ape-verify.yml
Verify Setup"] + + classDef plan fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef review fill:#fde68a,stroke:#b45309,stroke-width:1px,color:#7c2d12 + classDef deploy fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef destroy fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d + classDef verify fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + class PR,Plan plan + class Review,Merge,Comment review + class Deploy,Test deploy + class Destroy,DestroyMerge,DestroyWF destroy + class Manual,Verify verify \`\`\` `; diff --git a/website/docs/agents/azure-iac-exporter.md b/website/docs/agents/azure-iac-exporter.md index 8d188eb..a8da668 100644 --- a/website/docs/agents/azure-iac-exporter.md +++ b/website/docs/agents/azure-iac-exporter.md @@ -1,11 +1,12 @@ - - --- title: "Azure IaC Exporter" sidebar_label: "Azure IaC Exporter" description: "Export existing Azure resources to ARM templates by analyzing live Azure state. Reverse-engineers deployed resources into IaC templates compatible with Git-Ape. Use when importing existing resources into Git-Ape management." --- + + + # Azure IaC Exporter > Export existing Azure resources to ARM templates by analyzing live Azure state. Reverse-engineers deployed resources into IaC templates compatible with Git-Ape. Use when importing existing resources into Git-Ape management. diff --git a/website/docs/agents/azure-policy-advisor.md b/website/docs/agents/azure-policy-advisor.md index beafacc..d2246be 100644 --- a/website/docs/agents/azure-policy-advisor.md +++ b/website/docs/agents/azure-policy-advisor.md @@ -1,11 +1,12 @@ - - --- title: "Azure Policy Advisor" sidebar_label: "Azure Policy Advisor" description: "Assess Azure Policy compliance for ARM template resources. Queries existing subscription assignments and unassigned custom/built-in definitions, cross-references with Microsoft Learn recommendations. Produces split report: Part 1 (template improvements) and Part 2 (subscription-level policy assignments)." --- + + + # Azure Policy Advisor > Assess Azure Policy compliance for ARM template resources. Queries existing subscription assignments and unassigned custom/built-in definitions, cross-references with Microsoft Learn recommendations. Produces split report: Part 1 (template improvements) and Part 2 (subscription-level policy assignments). diff --git a/website/docs/agents/azure-principal-architect.md b/website/docs/agents/azure-principal-architect.md index 7ef8a47..e253568 100644 --- a/website/docs/agents/azure-principal-architect.md +++ b/website/docs/agents/azure-principal-architect.md @@ -1,11 +1,12 @@ - - --- title: "Azure Principal Architect" sidebar_label: "Azure Principal Architect" description: "Provide expert Azure architecture guidance using the Well-Architected Framework (WAF) 5 pillars. Evaluate deployments against Security, Reliability, Performance, Cost, and Operational Excellence. Use for architecture reviews, trade-off analysis, and design validation." --- + + + # Azure Principal Architect > Provide expert Azure architecture guidance using the Well-Architected Framework (WAF) 5 pillars. Evaluate deployments against Security, Reliability, Performance, Cost, and Operational Excellence. Use for architecture reviews, trade-off analysis, and design validation. diff --git a/website/docs/agents/azure-requirements-gatherer.md b/website/docs/agents/azure-requirements-gatherer.md index 0053667..7f6b607 100644 --- a/website/docs/agents/azure-requirements-gatherer.md +++ b/website/docs/agents/azure-requirements-gatherer.md @@ -1,11 +1,12 @@ - - --- title: "Azure Requirements Gatherer" sidebar_label: "Azure Requirements Gatherer" description: "Gather Azure deployment requirements through guided questions. Validate subscription access, check resource naming conflicts, query existing resources. Use when starting any Azure deployment workflow." --- + + + # Azure Requirements Gatherer > Gather Azure deployment requirements through guided questions. Validate subscription access, check resource naming conflicts, query existing resources. Use when starting any Azure deployment workflow. diff --git a/website/docs/agents/azure-resource-deployer.md b/website/docs/agents/azure-resource-deployer.md index e2f3c9b..c0cbcc6 100644 --- a/website/docs/agents/azure-resource-deployer.md +++ b/website/docs/agents/azure-resource-deployer.md @@ -1,11 +1,12 @@ - - --- title: "Azure Resource Deployer" sidebar_label: "Azure Resource Deployer" description: "Execute ARM template deployments to Azure. Monitor deployment progress, handle failures with rollback options, verify resource creation. Use only after user has confirmed deployment intent." --- + + + # Azure Resource Deployer > Execute ARM template deployments to Azure. Monitor deployment progress, handle failures with rollback options, verify resource creation. Use only after user has confirmed deployment intent. diff --git a/website/docs/agents/azure-template-generator.md b/website/docs/agents/azure-template-generator.md index 1e38c77..3a1f811 100644 --- a/website/docs/agents/azure-template-generator.md +++ b/website/docs/agents/azure-template-generator.md @@ -1,11 +1,12 @@ - - --- title: "Azure Template Generator" sidebar_label: "Azure Template Generator" description: "Generate ARM templates from requirements. Apply Azure best practices, validate schema, show what-if analysis. Echo deployment intent for user confirmation. Use after requirements gathering is complete." --- + + + # Azure Template Generator > Generate ARM templates from requirements. Apply Azure best practices, validate schema, show what-if analysis. Echo deployment intent for user confirmation. Use after requirements gathering is complete. @@ -447,6 +448,15 @@ graph LR Storage AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef storage fill:#fef3c7,stroke:#92400e,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class Internet internet + class FuncApp compute + class Storage storage + class AppInsights monitor ``` **Web App + Database Stack:** @@ -465,6 +475,17 @@ graph LR Storage AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef storage fill:#fef3c7,stroke:#92400e,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class Internet internet + class WebApp compute + class SQL,SQLServer data + class Storage storage + class AppInsights monitor ``` **Microservices Stack:** @@ -485,6 +506,17 @@ graph TD Cosmos AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef gateway fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef container fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class Internet internet + class APIM gateway + class CA1,CA2 container + class Cosmos data + class AppInsights monitor ``` **For multi-resource deployments**, always generate the diagram showing: diff --git a/website/docs/agents/git-ape-onboarding.md b/website/docs/agents/git-ape-onboarding.md index 710b154..edfb87b 100644 --- a/website/docs/agents/git-ape-onboarding.md +++ b/website/docs/agents/git-ape-onboarding.md @@ -1,11 +1,12 @@ - - --- title: "Git-Ape Onboarding" sidebar_label: "Git-Ape Onboarding" description: "Onboard a new repository, subscription(s), and user access for Git-Ape using the git-ape-onboarding skill playbook. Configures OIDC, RBAC, GitHub environments, and secrets." --- + + + # Git-Ape Onboarding > Onboard a new repository, subscription(s), and user access for Git-Ape using the git-ape-onboarding skill playbook. Configures OIDC, RBAC, GitHub environments, and secrets. diff --git a/website/docs/agents/git-ape.md b/website/docs/agents/git-ape.md index 3b13efa..102e292 100644 --- a/website/docs/agents/git-ape.md +++ b/website/docs/agents/git-ape.md @@ -1,11 +1,12 @@ - - --- title: "Git-Ape" sidebar_label: "Git-Ape" description: "Deploy Azure resources through guided workflow: gather requirements, generate ARM templates, verify intent, execute deployment, run integration tests. Use for Azure Functions, App Services, Storage, Databases, Container Apps." --- + + + # Git-Ape > Deploy Azure resources through guided workflow: gather requirements, generate ARM templates, verify intent, execute deployment, run integration tests. Use for Azure Functions, App Services, Storage, Databases, Container Apps. diff --git a/website/docs/agents/overview.md b/website/docs/agents/overview.md index 9276f6c..6c8e481 100644 --- a/website/docs/agents/overview.md +++ b/website/docs/agents/overview.md @@ -1,5 +1,3 @@ - - --- title: "Agents Overview" sidebar_label: "Overview" @@ -7,6 +5,9 @@ sidebar_position: 1 description: "Overview of all Git-Ape agents and their orchestration" --- + + + # Agents Overview Git-Ape uses a multi-agent architecture where `@git-ape` is the central orchestrator that delegates to specialized sub-agents. @@ -53,4 +54,15 @@ graph TD IE["IaC Exporter"] OB["Git-Ape Onboarding"] end + + classDef orchestrator fill:#1f6feb,stroke:#0b3d91,stroke-width:2px,color:#ffffff + classDef pipeline fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef advisory fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef utility fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + class GA orchestrator + class RG,TG,WR,RD pipeline + class SG,UC gate + class PA,PO advisory + class IE,OB utility ``` diff --git a/website/docs/deployment/drift-detection.md b/website/docs/deployment/drift-detection.md index d7d50e2..ced90fc 100644 --- a/website/docs/deployment/drift-detection.md +++ b/website/docs/deployment/drift-detection.md @@ -402,18 +402,25 @@ on: # Allow manual trigger workflow_dispatch: +permissions: + id-token: write + contents: read + issues: write + jobs: detect-drift: runs-on: ubuntu-latest steps: - name: Checkout Repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Azure Login - uses: azure/login@v1 + uses: azure/login@v2 with: - creds: ${{ secrets.AZURE_CREDENTIALS }} + client-id: ${{ secrets.AZURE_CLIENT_ID }} + tenant-id: ${{ secrets.AZURE_TENANT_ID }} + subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} - name: Install Azure CLI run: | @@ -433,7 +440,7 @@ jobs: echo "warning=$WARNING" >> $GITHUB_OUTPUT - name: Upload Drift Report - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: drift-report-${{ github.run_id }} path: drift-report.json @@ -459,7 +466,7 @@ jobs: - name: Create Issue on Critical Drift if: steps.drift-check.outputs.critical > 0 - uses: actions/github-script@v6 + uses: actions/github-script@v7 with: script: | const fs = require('fs'); diff --git a/website/docs/deployment/examples.md b/website/docs/deployment/examples.md index 6d84b92..fc9d2b0 100644 --- a/website/docs/deployment/examples.md +++ b/website/docs/deployment/examples.md @@ -5,46 +5,52 @@ sidebar_position: 3 description: "End-to-end Git-Ape usage examples" --- -# Git-Ape Examples +# Examples -This file keeps the longer usage examples out of the main README. +These walkthroughs show what a typical Git-Ape session looks like from start to finish. Each example follows the four-stage deployment flow: **Requirements → Review → Deploy → Validate**. -## Example 1: Deploy a Python Function App +## Deploy a Python Function App + +The most common starting point. You describe what you want in plain language; Git-Ape handles the rest. ```text User: @git-ape deploy a Python function app Agent: I'll help you deploy an Azure Function App through the guided workflow. -Stage 1: Requirements -- Region: East US -- Runtime: Python 3.11 -- Plan: Consumption -- Monitoring: Application Insights enabled +Stage 1 — Requirements + Region: East US + Runtime: Python 3.11 + Plan: Consumption (serverless) + Monitoring: Application Insights enabled -Stage 2: Review -- Function App: func-api-dev-eastus -- Storage Account: stfuncapidev8k3m -- App Insights: appi-api-dev-eastus -- Security: HTTPS only, managed identity, TLS 1.2 -- Cost estimate: about $0.40/month for a light workload +Stage 2 — Review + Function App: func-api-dev-eastus + Storage Account: stfuncapidev8k3m + App Insights: appi-api-dev-eastus + Security: HTTPS only, managed identity, TLS 1.2 + Estimated cost: ~$0.40/month (light workload) -Agent: Confirm deployment. +Agent: Confirm deployment? User: yes -Stage 3: Deploy -- Resource group created -- Storage account created -- App Insights created -- Function App created +Stage 3 — Deploy + ✓ Resource group created + ✓ Storage account created + ✓ App Insights created + ✓ Function App created -Stage 4: Validate -- Endpoint reachable -- HTTPS enforced -- Monitoring connected +Stage 4 — Validate + ✓ Endpoint reachable + ✓ HTTPS enforced + ✓ Monitoring connected ``` -## Example 2: Deploy a Web App with SQL Database +**What happened behind the scenes:** Git-Ape's Requirements Gatherer collected your intent, the Template Generator produced an ARM template, the Security Analyzer ran a blocking security gate, and the Resource Deployer executed the deployment. All artifacts are saved to `.azure/deployments/deploy-YYYYMMDD-HHMMSS/`. + +## Deploy a Web App with SQL Database + +Multi-resource deployments work the same way. Git-Ape generates a single ARM template with all resources and their dependencies. ```text User: @git-ape deploy a web app with SQL database @@ -52,22 +58,24 @@ User: @git-ape deploy a web app with SQL database Agent: I will collect the app, plan, database, and connectivity requirements. Review summary: -- App Service Plan: asp-webapp-dev-eastus -- Web App: app-webapp-dev-eastus -- SQL Server: sql-webapp-dev-eastus -- SQL Database: sqldb-webapp-dev -- Application Insights: appi-webapp-dev-eastus + App Service Plan: asp-webapp-dev-eastus + Web App: app-webapp-dev-eastus + SQL Server: sql-webapp-dev-eastus + SQL Database: sqldb-webapp-dev + App Insights: appi-webapp-dev-eastus Agent: Generated template, security review, and estimated cost. User: proceed Result: -- Resources deployed successfully -- Web app reachable -- Database connectivity validated + ✓ Resources deployed successfully + ✓ Web app reachable + ✓ Database connectivity validated ``` -## Example 3: Run the Integration Tester +## Run post-deployment tests + +After a deployment, you can verify everything is healthy: ```text User: /azure-integration-tester @@ -77,25 +85,24 @@ Agent: Provide the deployment or resource details. User: Test func-api-dev-eastus in rg-api-dev-eastus Agent: Running checks... -- HTTPS endpoint accessible -- Response time within threshold -- Application Insights connected -- Managed identity present + ✓ HTTPS endpoint accessible + ✓ Response time within threshold + ✓ Application Insights connected + ✓ Managed identity present ``` -## Example 4: Typical Workflow +## Typical end-to-end workflow -```text -1. Configure Azure MCP and sign in with Azure CLI. -2. Ask @git-ape to deploy a resource or stack. -3. Review the generated template, security output, and cost estimate. -4. Confirm deployment. -5. Review the saved artifacts under .azure/deployments/. -``` +Here is the recommended sequence for a new deployment: + +1. **Configure Azure MCP** and sign in with `az login` — see [Azure Setup](../getting-started/azure-setup). +2. **Ask Git-Ape** to deploy: `@git-ape deploy a ...`. +3. **Review** the generated ARM template, security analysis, and cost estimate. +4. **Confirm** the deployment. +5. **Check artifacts** saved under `.azure/deployments/` — see [State Management](./state). -## Related Docs +## Related pages -- [AZURE_MCP_SETUP.md](../getting-started/azure-setup) -- [ONBOARDING.md](../getting-started/onboarding) -- [DEPLOYMENT_STATE.md](../deployment/state) -- [DRIFT_DETECTION.md](../deployment/drift-detection) \ No newline at end of file +- [Azure Setup](../getting-started/azure-setup) — Connect Git-Ape to your Azure subscription. +- [Onboarding](../getting-started/onboarding) — Set up CI/CD pipelines. +- [State Management](./state) — How deployment artifacts are stored. diff --git a/website/docs/deployment/state.md b/website/docs/deployment/state.md index 6721ec6..5437a4f 100644 --- a/website/docs/deployment/state.md +++ b/website/docs/deployment/state.md @@ -364,6 +364,15 @@ graph LR Storage AppInsights end + + classDef internet fill:#e0e7ff,stroke:#4338ca,stroke-width:1px,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef storage fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + class Internet internet + class FuncApp compute + class Storage storage + class AppInsights monitor ``` ## Resource Inventory diff --git a/website/docs/getting-started/azure-setup.md b/website/docs/getting-started/azure-setup.md index 30cd395..dda9995 100644 --- a/website/docs/getting-started/azure-setup.md +++ b/website/docs/getting-started/azure-setup.md @@ -2,41 +2,44 @@ title: "Azure MCP Setup" sidebar_label: "Azure Setup" sidebar_position: 2 -description: "Configure Azure MCP server for VS Code" +description: "Connect Git-Ape to Azure through the Azure MCP server" --- -# Azure MCP Server Configuration +# Azure MCP setup + +This page walks you through connecting Git-Ape to your Azure subscription so it can query resources, generate templates, and deploy infrastructure. :::warning -EXPERIMENTAL ONLY: This setup is for development and sandbox testing. -Do **not** use this repository or its generated workflows for production Azure operations. -Review permissions and commands carefully before running them. +EXPERIMENTAL ONLY — This setup is for development and sandbox testing. Do **not** use this project for production Azure operations. Review permissions and commands carefully before running them. ::: -This document explains how to configure the Azure MCP server to enable Azure deployment capabilities for the Git-Ape agent system. -## Prerequisites +## Before you start + +You need three things: + +1. **VS Code** (Stable or Insiders) with GitHub Copilot enabled. +2. **Azure CLI** installed and authenticated (`az login`). +3. **Azure MCP Server extension** — ships with Azure Tools for VS Code. Verify with: -1. **VS Code Insiders** (or VS Code with GitHub Copilot extension) -2. **GitHub Copilot subscription** (with access to Copilot Chat) -3. **Azure CLI** installed and configured -4. **Azure MCP Server extension** (should be installed automatically with Azure extensions) + ```bash + code --list-extensions | grep azure-mcp + ``` -## Extension Installation + You should see `ms-azuretools.vscode-azure-mcp-server`. If not, install [Azure Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) from the marketplace. -The Azure MCP server is provided by the `ms-azuretools.vscode-azure-mcp-server` extension. It should be automatically available if you have Azure Tools for VS Code installed. +## Step 1: Sign in to Azure -Verify installation: ```bash -code --list-extensions | grep azure-mcp +az login +az account set --subscription "Your Subscription Name or ID" # optional but recommended +az account show # verify ``` -You should see: `ms-azuretools.vscode-azure-mcp-server` - -## Configuration +Git-Ape uses your Azure CLI credentials automatically — there is nothing else to configure for authentication. -### 1. VS Code Settings +## Step 2: Configure the MCP server -Add the following to your VS Code settings (`.vscode/settings.json` or User Settings): +Add these settings to your VS Code configuration (`.vscode/settings.json` or User Settings): ```json { @@ -59,254 +62,103 @@ Add the following to your VS Code settings (`.vscode/settings.json` or User Sett } ``` -**Configuration Options:** - -- **`serverMode`**: Controls how MCP tools are exposed - - `"single"`: One tool that routes to 100+ internal commands - - `"namespace"`: ~30 logical groups by service (recommended) - - `"all"`: Every MCP tool exposed directly (100+ tools) - -- **`enabledServices`**: Array of service namespaces to expose - - Only specified services will be available to agents - - Reduces tool clutter and improves agent focus - -- **`readOnly`**: When `true`, prevents destructive operations - - Set to `false` to allow deployments - - Set to `true` for testing/validation only - -### 2. Azure Authentication - -Authenticate with Azure CLI: - -```bash -# Login to Azure -az login - -# Set default subscription (optional but recommended) -az account set --subscription "Your Subscription Name or ID" - -# Verify authentication -az account show -``` - -The Azure MCP server uses your Azure CLI credentials automatically. - -### 3. Environment Variables (Optional) - -Create a `.env` file in your workspace root for default values: - -```bash -# Azure Subscription -AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - -# Default Region -AZURE_DEFAULT_REGION=eastus - -# Default Resource Group (optional) -AZURE_DEFAULT_RESOURCE_GROUP=rg-git-ape-dev-eastus -``` - -## Available Azure MCP Services - -The following services are used by the Git-Ape agents: - -### Core Deployment Services - -- **`deploy`** - ARM template deployment, what-if analysis, validation -- **`bestpractices`** - Security and configuration recommendations -- **`cloudarchitect`** - Architecture diagram generation - -### Resource Management - -- **`group`** - Resource group operations -- **`subscription`** - Subscription queries and management -- **`resourcehealth`** - Resource status and health monitoring -- **`monitor`** - Logging, metrics, and monitoring - -### Compute Services - -- **`functionapp`** - Azure Functions management -- **`aks`** - Azure Kubernetes Service (optional) -- **`acr`** - Azure Container Registry (optional) +:::tip[Which server mode should I choose?] +- **`namespace`** (recommended) — Groups tools by Azure service (~30 tool groups). Gives agents enough context without overwhelming them. +- **`single`** — One tool that routes to 100+ internal commands. Use this only if your organization limits tool count. +- **`all`** — Exposes every individual MCP tool (100+). Can slow down agent responses. +::: -### Data Services +### Which services do I need? -- **`storage`** - Blob, Table, Queue, File storage -- **`sql`** - Azure SQL Database -- **`cosmos`** - Cosmos DB -- **`mysql`**, **`postgres`** - Database services (optional) +The list above covers the most common Git-Ape scenarios. Here is what each service does: -### Infrastructure +| Service | What it enables | When to add it | +|---------|----------------|----------------| +| `deploy` | ARM template deployment, what-if, validation | **Always** — core deployment | +| `bestpractices` | Security and configuration recommendations | **Always** — security analysis | +| `group` | Resource group operations | **Always** — resource management | +| `subscription` | Subscription queries | **Always** — subscription discovery | +| `functionapp` | Azure Functions management | Deploying Function Apps | +| `storage` | Storage account operations | Most deployments (Functions, web apps) | +| `sql`, `cosmos` | Database operations | Deploying databases | +| `keyvault` | Key Vault access | Templates using Key Vault references | +| `aks`, `acr` | Kubernetes and container registry | Container workloads | -- **`bicepschema`** - Bicep/ARM template schemas -- **`keyvault`** - Secrets, keys, certificates +Start with the recommended list. You can add or remove services at any time. -## Verification +## Step 3: Verify the connection -After configuration, verify the MCP server is working: +1. Reload VS Code (`Cmd+Shift+P` → **Developer: Reload Window**). +2. Open Copilot Chat and type: -1. Open VS Code -2. Open GitHub Copilot Chat -3. Type: `@git-ape` -4. You should see "Git-Ape" in the agent picker + ```text + @git-ape list my Azure subscriptions + ``` -To test Azure MCP tools are accessible: + The agent should use Azure MCP tools and return your subscription details. -``` -In Copilot Chat: -"List available Azure subscriptions" +If it works, you are ready to deploy. Try: -Expected: The agent should use Azure MCP tools to query subscriptions +```text +@git-ape deploy a Python function app in East US ``` ## Troubleshooting -### Issue: "Unknown tool 'mcp_azure_mcp/*'" +
+"Unknown tool 'mcp_azure_mcp/…'" + +The Azure MCP server is not loaded. Fix: -**Cause:** Azure MCP server not loaded or not configured +1. Verify the extension is installed: `code --list-extensions | grep azure-mcp` +2. Reload the VS Code window. +3. Check that `azureMcp.serverMode` is set in your settings. -**Solution:** -1. Verify extension is installed: `code --list-extensions | grep azure-mcp` -2. Reload VS Code window: `Cmd/Ctrl + Shift + P` → "Reload Window" -3. Check settings have `azureMcp.serverMode` configured +
-### Issue: Azure authentication fails +
+Azure authentication fails -**Cause:** Azure CLI not authenticated or token expired +Your Azure CLI session has expired. Fix: -**Solution:** ```bash -# Re-authenticate az login - -# Verify -az account show - -# If multiple subscriptions, set default -az account set --subscription "Your Subscription" +az account show # confirm you are signed in ``` -### Issue: "Permission denied" on deployments - -**Cause:** Azure account lacks Contributor role on subscription/resource group - -**Solution:** -1. Verify your role: `az role assignment list --assignee $(az account show --query user.name -o tsv)` -2. You need at least "Contributor" role for deployments -3. Contact your Azure administrator to grant appropriate permissions - -### Issue: MCP tools are slow or unresponsive - -**Cause:** Too many services enabled or network latency - -**Solution:** -1. Reduce `enabledServices` to only what you need -2. Use `"namespace"` mode instead of `"all"` -3. Check Azure service health: https://status.azure.com - -### Issue: Agent doesn't see Azure services - -**Cause:** Services not in `enabledServices` list +If you have multiple subscriptions, set the default: `az account set --subscription "..."`. -**Solution:** -Add required services to `azureMcp.enabledServices` array in settings.json +
-## Security Considerations +
+"Permission denied" on deployments -### Credential Storage +Your Azure account lacks permissions. You need at least **Contributor** on the target resource group or subscription. -- **Never commit** Azure credentials to version control -- Use `.env` for local development (add to `.gitignore`) -- In production/CI, use managed identities or Azure DevOps service connections - -### Least Privilege - -The agents require these minimum Azure permissions: - -- **Requirements Gatherer**: `Reader` role -- **Template Generator**: `Reader` role -- **Resource Deployer**: `Contributor` role on target resource groups - -Consider creating a custom role: - -```json -{ - "Name": "Git-Ape Deployer", - "Description": "Deploy Azure resources via Git-Ape agent", - "Actions": [ - "Microsoft.Resources/deployments/*", - "Microsoft.Resources/subscriptions/resourceGroups/*", - "Microsoft.Web/sites/*", - "Microsoft.Storage/storageAccounts/*", - "Microsoft.Insights/components/*" - ], - "AssignableScopes": [ - "/subscriptions/{subscription-id}" - ] -} -``` - -### Production Deployments - -For production deployments: - -1. Set `azureMcp.readOnly: false` only when deploying -2. Use approval gates (the agent requires user confirmation) -3. Enable Azure Policy to restrict resource types/regions -4. Use separate subscriptions for dev/staging/prod -5. Review ARM templates before confirming deployment - -## Advanced Configuration - -### Custom MCP Server Mode - -If you want more control over which specific tools are available: - -```json -{ - "azureMcp.serverMode": "all", - "azureMcp.toolFilter": [ - "deploy_group_create", - "deploy_group_what_if", - "storage_account_create", - "functionapp_create" - ] -} +```bash +az role assignment list --assignee "$(az account show --query user.name -o tsv)" -o table ``` -This exposes only specific tool commands instead of entire service namespaces. - -### Multiple Azure Accounts +Contact your Azure administrator if roles are missing. -If you work with multiple Azure tenants/subscriptions: +
-```bash -# Login to different tenant -az login --tenant "tenant-id" - -# Switch between subscriptions -az account set --subscription "subscription-1" -# Deploy resources... - -az account set --subscription "subscription-2" -# Deploy to different subscription... -``` +
+MCP tools are slow or unresponsive -The agent will use whichever subscription is currently active in Azure CLI. +1. Switch to `"namespace"` mode if you are using `"all"`. +2. Reduce the `enabledServices` list to only what you need. +3. Check [Azure service health](https://status.azure.com). -## Next Steps +
-After configuration: +## Security best practices -1. Test the agent with a simple deployment: `@git-ape deploy a resource group` -2. Review the [project README](https://github.com/Azure/git-ape/blob/main/README.md) for example workflows -3. Customize workspace instructions in [`.github/copilot-instructions.md`](https://github.com/Azure/git-ape/blob/main/.github/copilot-instructions.md) -4. Add your organization's naming conventions and policies +- **Never commit** Azure credentials to version control. Use `.env` files (add to `.gitignore`) for local defaults. +- Git-Ape always asks for confirmation before deploying. Review the generated ARM template and cost estimate before approving. +- For production use, consider creating a least-privilege custom role scoped to the resource types you deploy. -## Resources +## What's next? -- [Azure MCP Server Documentation](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azure-mcp-server) -- [Azure CLI Documentation](https://docs.microsoft.com/en-us/cli/azure/) -- [GitHub Copilot Custom Agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents) -- [ARM Template Reference](https://docs.microsoft.com/en-us/azure/templates/) +- **[Onboarding](./onboarding)** — Set up OIDC, RBAC, and GitHub environments for CI/CD pipelines. +- **[Deploy anything](/docs/use-cases/deploy-anything)** — Walk through your first deployment. diff --git a/website/docs/getting-started/codespaces.md b/website/docs/getting-started/codespaces.md index 15d38f2..b958d65 100644 --- a/website/docs/getting-started/codespaces.md +++ b/website/docs/getting-started/codespaces.md @@ -49,6 +49,20 @@ The `post-create.sh` script runs automatically after the container is built and - **Checkov** — IaC security scanner supporting ARM, Bicep, and Terraform templates. - **PSRule for Azure** — WAF-aligned validation rules for ARM and Bicep templates. - **ARM-TTK** — Microsoft's ARM Template Test Toolkit for template validation. +- **Website dependencies** — `npm install` in the `website/` directory for Docusaurus docs. + +### VS Code Tasks + +Pre-configured tasks are available via **Terminal → Run Task** (or `⇧⌘B`): + +| Task | What it does | +|------|-------------| +| **Docs: Dev Server** | Starts Docusaurus in hot-reload mode on port 3333 | +| **Docs: Build (local)** | Generates docs and builds with `baseUrl=/` for local preview | +| **Docs: Build (production)** | Generates docs and builds with `baseUrl=/git-ape/` for GitHub Pages | +| **Docs: Serve** | Builds locally and serves the static output on port 3333 | +| **Docs: Generate** | Runs `generate-docs.js` to regenerate auto-generated pages | +| **Docs: Install** | Installs website npm dependencies | ### VS Code Extensions @@ -95,3 +109,5 @@ To add features or tools to the dev container: | ARM-TTK not found | Run `pwsh` and verify the profile loaded: `Get-Module arm-ttk -ListAvailable`. | | Checkov not found | Run `pip install --user checkov` manually. | | Extensions missing | Reload the window (`Ctrl+Shift+P` → `Developer: Reload Window`). | +| Docs site broken locally | Make sure you use the **Docs: Build (local)** task or set `DOCUSAURUS_BASE_URL=/` before building. The production build uses `/git-ape/` as the base path. | +| Port 3333 already in use | Run `lsof -ti:3333 \| xargs kill -9` to free the port. | diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 56ce775..4f1c08d 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -9,19 +9,31 @@ description: "Install Git-Ape and verify prerequisites" ## Prerequisites -- A Bash-compatible shell (use `git-bash` on Windows). Other shells are untested. -- Azure CLI (`az`), GitHub CLI (`gh`), `jq`, and `git` installed and authenticated. -- Run `/prereq-check` in Copilot Chat to verify everything is in place. +Before you start, make sure you have: -## Install the Plugin +- **A Bash-compatible shell** — macOS and Linux work out of the box. On Windows, install [Git for Windows](https://gitforwindows.org/) and use Git Bash. +- **Azure CLI, GitHub CLI, jq, and git** — installed and authenticated. -Git-Ape ships as a [VS Code agent plugin](https://code.visualstudio.com/docs/copilot/customization/agent-plugins) and as a GitHub Copilot CLI plugin. Pick the path that matches how you use Copilot. +:::tip[Quick check] +Run `/prereq-check` in Copilot Chat after installation. It validates every tool and auth session for you and shows platform-specific install commands for anything missing. +::: -### Option A: VS Code agent plugin (recommended for VS Code users) +## Which installation method should I use? -Prerequisites: VS Code with GitHub Copilot enabled and the `chat.plugins.enabled` setting set to `true` (managed at the organization level). +| Method | Best for | Requirements | +|--------|----------|--------------| +| **VS Code plugin** | Day-to-day Azure deployments from your editor | VS Code + Copilot + `chat.plugins.enabled` | +| **Copilot CLI plugin** | Terminal-first workflows or CI scripting | Copilot CLI | +| **Local dev install** | Contributing to Git-Ape itself | Git clone of the repo | +| **GitHub Codespaces** | Trying Git-Ape without any local setup | GitHub account | -1. Add the marketplace in your VS Code `settings.json`: +Most users should start with the **VS Code plugin**. If you just want to try Git-Ape without installing anything, jump to [Codespaces](./codespaces). + +## Option A: VS Code agent plugin (recommended) {#vscode-plugin} + +Your organization must have the `chat.plugins.enabled` setting set to `true`. If you are unsure, ask your admin or try the steps below — VS Code will tell you if plugins are disabled. + +1. Add the Git-Ape marketplace to your VS Code `settings.json`: ```jsonc "chat.plugins.marketplaces": [ @@ -30,10 +42,12 @@ Prerequisites: VS Code with GitHub Copilot enabled and the `chat.plugins.enabled ``` 2. Open the Extensions view (`⇧⌘X` on macOS, `Ctrl+Shift+X` on Windows/Linux), search for `@agentPlugins`, find **git-ape**, and select **Install**. -3. Alternatively, open the Command Palette (`⇧⌘P` on macOS, `Ctrl+Shift+P` on Windows/Linux), run **Chat: Install Plugin From Source**, and enter `https://github.com/Azure/git-ape`. -4. Verify the agents and skills appear in Copilot Chat (for example, type `@git-ape` or `/prereq-check`). -### Option B: Copilot CLI plugin + Alternatively, open the Command Palette (`⇧⌘P` / `Ctrl+Shift+P`), run **Chat: Install Plugin From Source**, and enter `https://github.com/Azure/git-ape`. + +3. Verify the agents and skills appear in Copilot Chat — type `@git-ape` or `/prereq-check`. + +## Option B: Copilot CLI plugin {#cli-plugin} ```bash copilot plugin marketplace add Azure/git-ape @@ -41,9 +55,15 @@ copilot plugin install git-ape@git-ape copilot plugin list # Should show: git-ape@git-ape ``` -### Option C: Local development install +## Option C: Local development install {#local-dev} + +Use this if you are contributing to Git-Ape or want to test local changes. + +```bash +git clone https://github.com/Azure/git-ape.git +``` -Clone this repository and register the local checkout as a VS Code plugin in `settings.json`: +Register the local checkout in your VS Code `settings.json`: ```jsonc "chat.pluginLocations": { @@ -51,19 +71,38 @@ Clone this repository and register the local checkout as a VS Code plugin in `se } ``` -Reload VS Code; the `@git-ape` agent and Git-Ape skills will appear in Copilot Chat. +Reload VS Code; the `@git-ape` agent and skills will appear in Copilot Chat. -## Verify Installation +## Verify installation -In Copilot Chat, try: +In Copilot Chat, type: -``` +```text @git-ape hello ``` -You should see the Git-Ape orchestrator respond. +You should see the Git-Ape orchestrator respond. If it does not, reload the VS Code window (`Cmd+Shift+P` → **Developer: Reload Window**). + +## What's next? -## Next Steps +You have Git-Ape installed. Here is the recommended path depending on what you want to do: + +```mermaid +flowchart TD + A["Git-Ape installed
(VS Code or CLI)"] --> B{"What do you want to do?"} + B -->|"Try it in a sandbox"| C["Codespaces
Zero-setup dev environment"] + B -->|"Deploy from VS Code"| D["Azure Setup
Configure MCP + Azure CLI"] + B -->|"Set up CI/CD pipelines"| E["Onboarding
OIDC, RBAC, GitHub environments"] + D --> E + + classDef start fill:#e0e7ff,stroke:#4338ca,stroke-width:2px,color:#1e1b4b + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:1px,color:#7c2d12 + classDef next fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + class A start + class B gate + class C,D,E next +``` -- [Configure Azure access](./azure-setup) -- [Set up OIDC, RBAC, and GitHub environments](./onboarding) +- **[Azure Setup](./azure-setup)** — Connect Git-Ape to your Azure subscription so it can deploy resources. +- **[Onboarding](./onboarding)** — Configure OIDC, RBAC, and GitHub environments for CI/CD pipelines. +- **[Codespaces](./codespaces)** — Spin up a ready-to-use dev environment in your browser. diff --git a/website/docs/getting-started/onboarding.md b/website/docs/getting-started/onboarding.md index 9f0688a..9bd8f5f 100644 --- a/website/docs/getting-started/onboarding.md +++ b/website/docs/getting-started/onboarding.md @@ -2,63 +2,87 @@ title: "Repository Onboarding" sidebar_label: "Onboarding" sidebar_position: 3 -description: "OIDC, RBAC, GitHub environments, and secrets setup" +description: "Set up OIDC, RBAC, and GitHub environments for CI/CD pipelines" --- -# Git-Ape Onboarding Guide +# Repository onboarding + +This page helps you connect a GitHub repository to Azure so that Git-Ape's CI/CD workflows can deploy resources automatically. By the end you will have OIDC federation, RBAC roles, and GitHub environments configured. :::warning -EXPERIMENTAL ONLY: This onboarding flow is provided for testing and evaluation. -Do **not** use Git-Ape in production environments. -Validate all generated configuration manually before any real deployment. +EXPERIMENTAL ONLY — This onboarding flow is for testing and evaluation. Do **not** use Git-Ape in production environments. Validate all generated configuration manually before any real deployment. ::: -Set up a GitHub repository to use Git-Ape's CI/CD pipelines for Azure deployments. This guide covers Entra ID (Azure AD) configuration, OIDC federation, RBAC, and GitHub repository setup. -Git-Ape supports two onboarding modes: +## Choose your onboarding path + +Git-Ape can automate the entire setup for you, or you can run each step manually. + +| Path | When to choose it | +|------|-------------------| +| **[Automated](#automated-onboarding)** | You want the fastest path. Copilot Chat runs every command for you. | +| **[Manual](#manual-setup)** | You want to understand each component, or your organization requires manual approval of identity and RBAC changes. | -| Mode | Use case | GitHub Environments | Secrets scope | -|------|----------|-------------------|---------------| -| **Single environment** | One Azure subscription for all deployments | `azure-deploy`, `azure-destroy` | Repository-level | -| **Multi-environment** | Separate subscriptions per stage (dev/staging/prod) | `azure-deploy-dev`, `azure-deploy-staging`, `azure-deploy-prod`, `azure-destroy` | Environment-level | +Both paths produce the same result: an Entra ID App Registration with OIDC federated credentials, RBAC role assignments, and GitHub environments with the required secrets. -## How OIDC Authentication Works +## Choose single or multi-environment mode {#choose-mode} -Git-Ape uses OpenID Connect (OIDC) federation between GitHub Actions and Microsoft Entra ID. No client secrets are stored — GitHub mints a short-lived token at workflow runtime, and Entra exchanges it for an Azure access token based on a trust relationship you configure once. +Before onboarding, decide how many Azure subscriptions you need. ```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% +flowchart TD + A{"How many Azure
subscriptions?"} -->|"One subscription
for everything"| B["Single environment
Simpler setup
Good for personal projects,
demos, and small teams"] + A -->|"Separate subscriptions
per stage"| C["Multi-environment
dev / staging / prod
Blast-radius isolation
Required reviewers on prod"] + + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef simple fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef advanced fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + class A gate + class B simple + class C advanced +``` + +| | Single environment | Multi-environment | +|---|---|---| +| **GitHub environments** | `azure-deploy`, `azure-destroy` | `azure-deploy-dev`, `azure-deploy-staging`, `azure-deploy-prod`, `azure-destroy` | +| **Secrets scope** | Repository-level | Environment-level per stage | +| **Subscriptions** | One | One per stage | +| **Federated credentials** | 4 | 4 + one per extra stage | +| **Best for** | Personal projects, demos, PoCs | Teams, staging gates, production isolation | + +:::tip[Not sure?] +Start with **single environment**. You can switch to multi-environment later by adding more federated credentials and GitHub environments. +::: + +## How OIDC authentication works + +Git-Ape uses OpenID Connect (OIDC) so that **no client secrets are stored** in your repository. GitHub mints a short-lived token at workflow runtime, Entra ID verifies it against a trust relationship you configure once, and returns an Azure access token. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9','actorBkg':'#dbeafe','actorBorder':'#1f6feb','actorTextColor':'#0b3d91','actorLineColor':'#475569','signalColor':'#475569','signalTextColor':'#0f172a','noteBkgColor':'#fef3c7','noteBorderColor':'#b45309','noteTextColor':'#7c2d12'}}}%% sequenceDiagram autonumber - participant GH as GitHub Actions
(workflow run) - participant Entra as Microsoft Entra ID
(App Registration) + participant GH as GitHub Actions + participant Entra as Microsoft Entra ID participant ARM as Azure Resource Manager - GH->>GH: Mint OIDC token
subject: repo:org/repo:ref:refs/heads/main - GH->>Entra: Exchange token
(client_id + federated credential) - Entra->>Entra: Verify subject matches
federated credential - Entra-->>GH: Azure access token
(short-lived, ~1h) - GH->>ARM: az deployment sub create
Authorization: Bearer [token] - ARM->>ARM: Check RBAC role assignment
on subscription + GH->>GH: Mint OIDC token + GH->>Entra: Exchange token (client_id + federated credential) + Entra->>Entra: Verify subject matches + Entra-->>GH: Azure access token (~1h) + GH->>ARM: az deployment sub create ARM-->>GH: Deployment result ``` -**Trust components you configure during onboarding:** +The trust chain you create during onboarding: ```mermaid %%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% graph LR - GH["GitHub Repo
org/repo"] - FC["Federated Credential
subject: repo:org/repo:..."] - APP["Entra App Registration
client_id + tenant_id"] - SP["Service Principal
object_id"] - SUB["Azure Subscription
subscription_id"] - ROLE["RBAC Role
Contributor / UAA"] - - GH -->|trusts| FC - FC -->|attached to| APP - APP -->|backed by| SP - SP -->|assigned| ROLE - ROLE -->|scoped to| SUB + GH["GitHub Repo"] -->|trusts| FC["Federated Credential"] + FC -->|attached to| APP["Entra App Registration"] + APP -->|backed by| SP["Service Principal"] + SP -->|assigned| ROLE["RBAC Role"] + ROLE -->|scoped to| SUB["Azure Subscription"] classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 @@ -69,148 +93,121 @@ graph LR class SUB,ROLE azure ``` -The **Quick Start** below automates all of this. The **Manual Setup** section walks through each component individually. +--- -## Quick Start (Automated) +## Automated onboarding -You can run onboarding from Copilot Chat with: +Run one of these commands in Copilot Chat: ```text @Git-Ape Onboarding onboard this repository ``` -or directly invoke the skill: +or: ```text /git-ape-onboarding ``` -Both paths execute the same onboarding playbook through Copilot Chat. +The skill collects five inputs (or uses sensible defaults): -The skill-driven onboarding flow will gather or use: -1. **GitHub repository URL** — e.g. `https://github.com/your-org/your-repo` -2. **Entra ID App Registration name** — e.g. `sp-git-ape-your-repo` -3. **Single or multi-environment mode** — choose whether to deploy to one or multiple Azure subscriptions +1. **GitHub repository URL** — for example, `https://github.com/your-org/your-repo` +2. **Entra ID App Registration name** — for example, `sp-git-ape-your-repo` +3. **Mode** — single or multi-environment 4. **Azure subscription(s)** — defaults to your current `az` subscription 5. **RBAC role(s)** — Contributor (default) or Contributor + User Access Administrator -### Parameterized Usage - -**Single environment:** +### Example: single environment ```text -/git-ape-onboarding onboard https://github.com/your-org/your-repo on subscription 00000000-0000-0000-0000-000000000000 with Contributor +/git-ape-onboarding onboard https://github.com/your-org/your-repo on subscription 00000000-... with Contributor ``` -**Multi-environment:** +### Example: multi-environment ```text -/git-ape-onboarding onboard https://github.com/your-org/your-repo with dev on 11111111-1111-1111-1111-111111111111 as Contributor, staging on 22222222-2222-2222-2222-222222222222 as Contributor, prod on 33333333-3333-3333-3333-333333333333 as Contributor+UserAccessAdministrator +/git-ape-onboarding onboard https://github.com/your-org/your-repo with dev on 11111111-... as Contributor, staging on 22222222-... as Contributor, prod on 33333333-... as Contributor+UserAccessAdministrator ``` -Each multi-environment entry creates: -- A GitHub environment `azure-deploy-{name}` with environment-level secrets -- A federated credential scoped to that environment -- An RBAC role assignment on the specified subscription +After the skill finishes, skip to [Verify your setup](#verify-setup). --- -## Manual Setup +## Manual setup -If you prefer to inspect or execute each component manually, follow the steps below. +Follow these steps if you want to run each command yourself or need to understand what the automated flow does. ### Prerequisites -> **Tip:** Run `/prereq-check` in Copilot Chat to automatically validate all tools and auth sessions. - -| Tool | Minimum Version | Purpose | +| Tool | Minimum version | Purpose | |------|-----------------|---------| -| Azure CLI (`az`) | 2.50+ | Azure resource management, RBAC, OIDC | -| GitHub CLI (`gh`) | 2.0+ | Repo secrets, environments, OIDC detection | -| jq | 1.6+ | JSON parsing in scripts and workflows | -| git | any | Version control (usually pre-installed) | +| Azure CLI (`az`) | 2.50+ | Entra ID, RBAC, OIDC | +| GitHub CLI (`gh`) | 2.0+ | Secrets, environments | +| jq | 1.6+ | JSON parsing | -**Install (pick your platform):** +:::tip +Run `/prereq-check` in Copilot Chat to validate tools and auth sessions automatically. +::: -
macOS (Homebrew) +
+Install commands by platform +**macOS:** ```bash brew install azure-cli gh jq ``` -
- -
Ubuntu / Debian +**Ubuntu / Debian:** ```bash -# Azure CLI curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash - -# GitHub CLI -(type -p wget >/dev/null || sudo apt-get install wget -y) \ - && sudo mkdir -p -m 755 /etc/apt/keyrings \ - && out=$(mktemp) && wget -nv -O"$out" https://cli.github.com/packages/githubcli-archive-keyring.gpg \ - && cat "$out" | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \ - && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \ - && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ - && sudo apt-get update && sudo apt-get install gh -y - -# jq +# GitHub CLI — see https://github.com/cli/cli/blob/trunk/docs/install_linux.md sudo apt-get install -y jq ``` -
- -
Windows (PowerShell) +**Windows (PowerShell):** ```powershell winget install Microsoft.AzureCLI winget install GitHub.cli winget install jqlang.jq ``` -> **Note:** Git-Ape commands require a Bash shell. Install [Git for Windows](https://gitforwindows.org/) and use Git Bash.
-You must be logged in to both: +Sign in to both: + ```bash -az login # Azure — needs Owner or User Access Administrator on the subscription(s) -gh auth login # GitHub — needs admin access to the target repository +az login # needs Owner or User Access Administrator on the subscription +gh auth login # needs admin access to the target repository ``` ### Step 1: Create an Entra ID App Registration -This creates the identity that GitHub Actions will use to authenticate with Azure. +This creates the identity that GitHub Actions will use. ```bash -# Choose a name for your app registration SP_NAME="sp-git-ape-your-repo" -# Create the app registration CLIENT_ID=$(az ad app create --display-name "$SP_NAME" --query appId -o tsv) echo "Client ID: $CLIENT_ID" -# Create the service principal az ad sp create --id "$CLIENT_ID" -# Note your tenant ID TENANT_ID=$(az account show --query tenantId -o tsv) echo "Tenant ID: $TENANT_ID" ``` -### Step 2: Configure OIDC Federated Credentials +### Step 2: Add OIDC federated credentials -OIDC eliminates stored secrets by letting GitHub Actions exchange a short-lived token for Azure access at runtime. The number of federated credentials depends on your mode. +These tell Entra ID which GitHub tokens to trust. ```bash -# Get the app object ID (different from client ID) OBJECT_ID=$(az ad app show --id "$CLIENT_ID" --query id -o tsv) - -# Your GitHub repo (org/repo format) REPO="your-org/your-repo" -# Detect whether the GitHub org uses default or customized OIDC subjects -USE_DEFAULT_SUBJECT=$(gh api "orgs/${REPO%%/*}/actions/oidc/customization/sub" --jq '.use_default' 2>/dev/null || echo true) +# Detect customized OIDC subjects (some orgs override the default format) +USE_DEFAULT=$(gh api "orgs/${REPO%%/*}/actions/oidc/customization/sub" --jq '.use_default' 2>/dev/null || echo true) -if [[ "$USE_DEFAULT_SUBJECT" == "false" ]]; then +if [[ "$USE_DEFAULT" == "false" ]]; then REPO_ID=$(gh api "repos/$REPO" --jq '.id') OWNER_ID=$(gh api "repos/$REPO" --jq '.owner.id') OIDC_PREFIX="repository_owner_id:${OWNER_ID}:repository_id:${REPO_ID}" @@ -219,138 +216,85 @@ else fi ``` -Use `$OIDC_PREFIX` for all subjects below. On orgs with a customized subject template, `repo:org/repo:...` will fail with `AADSTS700213`. - -#### 2a. Main Branch (merge-triggered deployments) +Create the credentials. You need **at least four** — main branch, pull requests, deploy environment, and destroy environment: ```bash +# Main branch (merge-triggered deployments) az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ "name": "fc-main-branch", "issuer": "https://token.actions.githubusercontent.com", "subject": "'"$OIDC_PREFIX"':ref:refs/heads/main", - "description": "Main branch deployments", "audiences": ["api://AzureADTokenExchange"] }' -``` -#### 2b. Pull Requests (plan validation) - -```bash +# Pull requests (plan validation) az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ "name": "fc-pull-request", "issuer": "https://token.actions.githubusercontent.com", "subject": "'"$OIDC_PREFIX"':pull_request", - "description": "Pull request validation", "audiences": ["api://AzureADTokenExchange"] }' ``` -#### 2c. Deploy Environment(s) -
-Single environment mode - -Create one federated credential for the `azure-deploy` environment: +Single environment: deploy + destroy credentials ```bash az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ "name": "fc-env-deploy", "issuer": "https://token.actions.githubusercontent.com", "subject": "'"$OIDC_PREFIX"':environment:azure-deploy", - "description": "Deploy environment", "audiences": ["api://AzureADTokenExchange"] }' -``` -
- -
-Multi-environment mode - -Create one federated credential per environment. Each maps to a separate GitHub environment: - -```bash -# Dev environment -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy-dev", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-dev", - "description": "Deploy environment (dev)", - "audiences": ["api://AzureADTokenExchange"] -}' - -# Staging environment az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy-staging", - "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-staging", - "description": "Deploy environment (staging)", - "audiences": ["api://AzureADTokenExchange"] -}' - -# Production environment -az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ - "name": "fc-env-deploy-prod", + "name": "fc-env-destroy", "issuer": "https://token.actions.githubusercontent.com", - "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-prod", - "description": "Deploy environment (prod)", + "subject": "'"$OIDC_PREFIX"':environment:azure-destroy", "audiences": ["api://AzureADTokenExchange"] }' ```
-#### 2d. Destroy Environment (shared across all modes) +
+Multi-environment: per-stage deploy + destroy credentials ```bash +for ENV in dev staging prod; do + az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ + "name": "fc-env-deploy-'"$ENV"'", + "issuer": "https://token.actions.githubusercontent.com", + "subject": "'"$OIDC_PREFIX"':environment:azure-deploy-'"$ENV"'", + "audiences": ["api://AzureADTokenExchange"] + }' +done + az ad app federated-credential create --id "$OBJECT_ID" --parameters '{ "name": "fc-env-destroy", "issuer": "https://token.actions.githubusercontent.com", "subject": "'"$OIDC_PREFIX"':environment:azure-destroy", - "description": "Destroy environment", "audiences": ["api://AzureADTokenExchange"] }' ``` -#### Verify Credentials - -```bash -az ad app federated-credential list --id "$OBJECT_ID" --query "[].{name:name, subject:subject}" -o table -``` +
-**Single environment** — expected 4 credentials: -``` -Name Subject ------------------ ----------------------------------------------- -fc-main-branch :ref:refs/heads/main -fc-pull-request :pull_request -fc-env-deploy :environment:azure-deploy -fc-env-destroy :environment:azure-destroy -``` +Verify: -**Multi-environment (3 envs)** — expected 6 credentials: -``` -Name Subject ----------------------- --------------------------------------------------- -fc-main-branch :ref:refs/heads/main -fc-pull-request :pull_request -fc-env-deploy-dev :environment:azure-deploy-dev -fc-env-deploy-staging :environment:azure-deploy-staging -fc-env-deploy-prod :environment:azure-deploy-prod -fc-env-destroy :environment:azure-destroy +```bash +az ad app federated-credential list --id "$OBJECT_ID" \ + --query "[].{name:name, subject:subject}" -o table ``` -### Step 3: Assign RBAC Roles +### Step 3: Assign RBAC roles -Grant the service principal permissions on your Azure subscription(s). - -#### Single Environment +Grant the service principal permissions on your subscription(s). ```bash SUBSCRIPTION_ID=$(az account show --query id -o tsv) SP_OBJECT_ID=$(az ad sp show --id "$CLIENT_ID" --query id -o tsv) -# Contributor — create, modify, and delete resources az role assignment create \ --assignee-object-id "$SP_OBJECT_ID" \ --assignee-principal-type ServicePrincipal \ @@ -358,20 +302,12 @@ az role assignment create \ --scope "/subscriptions/$SUBSCRIPTION_ID" ``` -If your templates include RBAC role assignments (e.g., managed identity access to storage), also add: - -```bash -# User Access Administrator — manage role assignments -az role assignment create \ - --assignee-object-id "$SP_OBJECT_ID" \ - --assignee-principal-type ServicePrincipal \ - --role "User Access Administrator" \ - --scope "/subscriptions/$SUBSCRIPTION_ID" -``` - -#### Multi-Environment +:::tip[Do I need User Access Administrator?] +Only if your ARM templates include RBAC role assignments — for example, granting a managed identity access to a storage account. If you are unsure, skip it for now. Deployments will tell you if the role is missing. +::: -Assign roles on each target subscription. Each environment can have a different role if needed: +
+Multi-environment: assign roles per subscription ```bash SP_OBJECT_ID=$(az ad sp show --id "$CLIENT_ID" --query id -o tsv) @@ -404,198 +340,139 @@ az role assignment create \ --scope "/subscriptions/$PROD_SUBSCRIPTION_ID" ``` -> **Note:** If multiple environments share the same subscription, you only need one set of role assignments for that subscription. - -#### Verify RBAC - -```bash -az role assignment list --assignee "$SP_OBJECT_ID" --query "[].{role:roleDefinitionName, scope:scope}" -o table -``` +
-### Step 4: Configure GitHub Repository +### Step 4: Configure GitHub repository -#### 4a. Set GitHub Secrets +#### Set secrets -These are **identifiers**, not credentials — OIDC means no actual secrets are stored. +These are identifiers, not actual credentials — OIDC means no secrets are stored.
-Single environment mode - -Set secrets at the **repository level** (shared by all workflows): +Single environment ```bash REPO="your-org/your-repo" - -echo "$CLIENT_ID" | gh secret set AZURE_CLIENT_ID -R "$REPO" -echo "$TENANT_ID" | gh secret set AZURE_TENANT_ID -R "$REPO" +echo "$CLIENT_ID" | gh secret set AZURE_CLIENT_ID -R "$REPO" +echo "$TENANT_ID" | gh secret set AZURE_TENANT_ID -R "$REPO" echo "$SUBSCRIPTION_ID" | gh secret set AZURE_SUBSCRIPTION_ID -R "$REPO" ```
-Multi-environment mode +Multi-environment -Set shared secrets at the **repository level**, then set the subscription per **environment**: +Set shared values at the repo level, then the subscription per environment: ```bash REPO="your-org/your-repo" - -# Repo-level secrets (shared) echo "$CLIENT_ID" | gh secret set AZURE_CLIENT_ID -R "$REPO" echo "$TENANT_ID" | gh secret set AZURE_TENANT_ID -R "$REPO" -# Per-environment secrets -# Dev -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-dev" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-dev" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-dev" --body "$DEV_SUBSCRIPTION_ID" - -# Staging -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-staging" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-staging" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-staging" --body "$STAGING_SUBSCRIPTION_ID" - -# Production -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-prod" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-prod" --body "$TENANT_ID" -gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-prod" --body "$PROD_SUBSCRIPTION_ID" - -# Destroy environment (uses first subscription as default) -gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-destroy" --body "$CLIENT_ID" -gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-destroy" --body "$TENANT_ID" +for ENV in dev staging prod; do + # Use the right subscription variable for each stage + gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-deploy-$ENV" --body "$CLIENT_ID" + gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-deploy-$ENV" --body "$TENANT_ID" + gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-deploy-$ENV" --body "${ENV}_SUBSCRIPTION_ID_VALUE" +done + +# Destroy environment +gh secret set AZURE_CLIENT_ID --repo "$REPO" --env "azure-destroy" --body "$CLIENT_ID" +gh secret set AZURE_TENANT_ID --repo "$REPO" --env "azure-destroy" --body "$TENANT_ID" gh secret set AZURE_SUBSCRIPTION_ID --repo "$REPO" --env "azure-destroy" --body "$DEV_SUBSCRIPTION_ID" ``` -> **Tip:** Environment-level secrets override repo-level secrets. By setting `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` at the environment level, you can later switch to separate app registrations per environment without modifying workflows. -
-#### 4b. Create GitHub Environments +#### Create GitHub environments
-Single environment mode - -**azure-deploy** — for deployment jobs: +Single environment ```bash -# Create environment with branch policy (main only) +REPO="your-org/your-repo" + +# azure-deploy — restricted to main branch gh api -X PUT "repos/$REPO/environments/azure-deploy" --input - <<'EOF' -{ - "deployment_branch_policy": { - "protected_branches": false, - "custom_branch_policies": true - } -} +{"deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}} +EOF +gh api -X POST "repos/$REPO/environments/azure-deploy/deployment-branch-policies" \ + --input - <<'EOF' +{"name":"main","type":"branch"} EOF -# Allow main branch -gh api -X POST "repos/$REPO/environments/azure-deploy/deployment-branch-policies" --input - <<'EOF' -{ - "name": "main", - "type": "branch" -} +# azure-destroy +gh api -X PUT "repos/$REPO/environments/azure-destroy" --input - <<'EOF' +{"deployment_branch_policy":null} EOF ```
-Multi-environment mode - -Create one environment per deployment target: +Multi-environment ```bash -for ENV_NAME in dev staging prod; do - # Create environment with branch policy (main only) - gh api -X PUT "repos/$REPO/environments/azure-deploy-${ENV_NAME}" --input - <<'EOF' -{ - "deployment_branch_policy": { - "protected_branches": false, - "custom_branch_policies": true - } -} -EOF +REPO="your-org/your-repo" - # Allow main branch - gh api -X POST "repos/$REPO/environments/azure-deploy-${ENV_NAME}/deployment-branch-policies" --input - <<'EOF' -{ - "name": "main", - "type": "branch" -} +for ENV in dev staging prod; do + gh api -X PUT "repos/$REPO/environments/azure-deploy-$ENV" --input - <<'EOF' +{"deployment_branch_policy":{"protected_branches":false,"custom_branch_policies":true}} +EOF + gh api -X POST "repos/$REPO/environments/azure-deploy-$ENV/deployment-branch-policies" \ + --input - <<'EOF' +{"name":"main","type":"branch"} EOF done -``` - -
- -**azure-destroy** — for destroy jobs (same for both modes): -```bash gh api -X PUT "repos/$REPO/environments/azure-destroy" --input - <<'EOF' -{ - "deployment_branch_policy": null -} +{"deployment_branch_policy":null} EOF ``` -#### 4c. (Optional) Required Reviewers - -For production deployments, add required reviewers to the deploy environment: - -1. Go to **Settings → Environments → azure-deploy** (or **azure-deploy-prod** in multi-env mode) -2. Check **Required reviewers** -3. Add team members who should approve deployments - -In multi-environment mode, you might want: -- `azure-deploy-dev` — no reviewer required (fast iteration) -- `azure-deploy-staging` — optional reviewer -- `azure-deploy-prod` — required reviewer (gate for production) +
-### Step 5: Copy Git-Ape Workflows +:::tip[Add required reviewers for production] +Go to **Settings → Environments → azure-deploy** (or `azure-deploy-prod` in multi-env mode), check **Required reviewers**, and add your team. This prevents unreviewed deployments from reaching production. +::: -Copy the workflow files to your repository: +### Step 5: Copy Git-Ape workflows ```bash -# Clone the git-ape repo if you haven't -git clone https://github.com/your-org/git-ape.git /tmp/git-ape +# If you haven't already +git clone https://github.com/Azure/git-ape.git /tmp/git-ape -# Copy workflows to your repo cp /tmp/git-ape/.github/workflows/git-ape-*.yml your-repo/.github/workflows/ - -# Commit and push cd your-repo git add .github/workflows/ git commit -m "feat: add Git-Ape deployment workflows" git push ``` -The following workflows will be added: +This adds four workflows: | Workflow | Trigger | Purpose | |----------|---------|---------| -| `git-ape-plan.yml` | PR with template changes | Validate, security scan, what-if, cost estimate | -| `git-ape-deploy.yml` | Merge to main or `/deploy` comment | Execute ARM deployment | -| `git-ape-destroy.yml` | Merge PR with `destroy-requested` status | Delete resource group | -| `git-ape-verify.yml` | Manual dispatch | Verify OIDC, RBAC, and pipeline health | +| `git-ape-plan.yml` | PR with template changes | Validate, what-if, cost estimate | +| `git-ape-deploy.yml` | Merge to main or `/deploy` comment | ARM deployment | +| `git-ape-destroy.yml` | PR merge with `destroy-requested` status | Delete resource group | +| `git-ape-verify.yml` | Manual dispatch | Verify OIDC and RBAC health | -> **Note:** Drift detection and TTL-based cleanup are being replaced by agentic workflows — coming soon. +--- -### Step 6: Verify Setup +## Verify your setup {#verify-setup} -Create a test deployment to verify the pipeline works: +Create a test deployment to confirm the pipeline works end-to-end: ```bash -# Create a minimal test template mkdir -p .azure/deployments/deploy-test cat > .azure/deployments/deploy-test/template.json <<'EOF' { "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#", "contentVersion": "1.0.0.0", - "parameters": { - "location": { "type": "string", "defaultValue": "eastus" } - }, + "parameters": {"location": {"type": "string", "defaultValue": "eastus"}}, "resources": [] } EOF @@ -604,214 +481,60 @@ cat > .azure/deployments/deploy-test/parameters.json <<'EOF' { "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#", "contentVersion": "1.0.0.0", - "parameters": { - "location": { "value": "eastus" } - } + "parameters": {"location": {"value": "eastus"}} } EOF -# Open a PR git checkout -b test/git-ape-onboarding git add .azure/deployments/deploy-test/ git commit -m "test: verify git-ape pipeline" git push -u origin test/git-ape-onboarding -gh pr create --title "Test: Git-Ape onboarding" --body "Verify the OIDC pipeline works end-to-end." +gh pr create --title "Test: Git-Ape onboarding" --body "Verify the OIDC pipeline works." ``` -If the PR triggers the `Git-Ape: Plan` workflow and it succeeds, your setup is complete. - ---- - -## Optional: Slack Notifications - -To get Slack notifications on deploy/destroy/drift events: - -1. Create a Slack Incoming Webhook: [Slack API → Incoming Webhooks](https://api.slack.com/messaging/webhooks) -2. Set the secret: - ```bash - echo "https://hooks.slack.com/services/T.../B.../..." | gh secret set SLACK_WEBHOOK_URL -R "$REPO" - ``` +If the `Git-Ape: Plan` workflow runs and succeeds on the PR, your setup is complete. --- ## Troubleshooting -### "AADSTS700016: Application not found" - -The federated credential subject doesn't match the workflow's token. Verify: -```bash -az ad app federated-credential list --id "$OBJECT_ID" -o table -``` - -Common issues: -- Repository name is case-sensitive in the `subject` field -- `pull_request` subject is needed for PR-triggered workflows -- `environment:azure-deploy` subject is needed for jobs using `environment: azure-deploy` - -### "AuthorizationFailed" during deployment - -The service principal lacks permissions. Check assignments: -```bash -az role assignment list --assignee "$SP_OBJECT_ID" -o table -``` - -Ensure **Contributor** role is assigned at the subscription scope. - -### "Resource group not found" in plan workflow - -The OIDC token exchange succeeded but the subscription doesn't match. Verify: -```bash -# Check which subscription the service principal can access -az account list --query "[?tenantId=='$TENANT_ID']" -o table -``` - -### GitHub environment not created +
+"AADSTS700016: Application not found" -Environment creation requires admin access to the repository. Ask a repo admin to create the `azure-deploy` and `azure-destroy` environments manually via **Settings → Environments**. +The federated credential subject does not match the workflow token. Common causes: +- Repository name is case-sensitive in the subject field. +- Missing `pull_request` subject for PR-triggered workflows. +- Missing `environment:azure-deploy` subject for deploy jobs. ---- +Check: `az ad app federated-credential list --id "$OBJECT_ID" -o table` -## Architecture - -### Single Environment Mode +
-```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -graph TD - subgraph GH["GitHub Repository"] - direction TB - SEC["Repo Secrets
AZURE_CLIENT_ID
AZURE_TENANT_ID
AZURE_SUBSCRIPTION_ID
SLACK_WEBHOOK_URL (optional)"] - ENVD["azure-deploy
main branch only"] - ENVX["azure-destroy
main branch only"] - WF["Workflows
git-ape-plan.yml (PR)
git-ape-deploy.yml (main / azure-deploy)
git-ape-destroy.yml (azure-destroy)
git-ape-verify.yml (dispatch)"] - SEC --- WF - ENVD --- WF - ENVX --- WF - end - - subgraph ENTRA["Microsoft Entra ID"] - APP["App Registration
sp-git-ape-{repo}
client_id + tenant_id"] - FC["Federated Credentials
• repo:org/repo:ref:refs/heads/main
• repo:org/repo:pull_request
• repo:org/repo:environment:azure-deploy
• repo:org/repo:environment:azure-destroy"] - APP --- FC - end - - subgraph AZ["Azure Subscription"] - ROLE["RBAC
Contributor
(+ UAA if templates assign roles)"] - RG1["rg-app-dev"] - RG2["rg-api-prod"] - RG3["rg-data-stg"] - ROLE --- RG1 - ROLE --- RG2 - ROLE --- RG3 - end - - WF -->|"OIDC token exchange"| FC - APP -->|"Service Principal"| ROLE +
+"AuthorizationFailed" during deployment - classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 - classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 - classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d +The service principal lacks permissions. Check: `az role assignment list --assignee "$SP_OBJECT_ID" -o table` - class SEC,ENVD,ENVX,WF gh - class APP,FC entra - class ROLE,RG1,RG2,RG3 azure -``` +Ensure **Contributor** is assigned at the subscription scope. -### Multi-Environment Mode +
-```mermaid -%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%% -graph TD - subgraph GH["GitHub Repository"] - direction TB - REPO["Repo-level Secrets
AZURE_CLIENT_ID
AZURE_TENANT_ID"] - EDEV["azure-deploy-dev
SUBSCRIPTION_ID → Dev"] - ESTG["azure-deploy-staging
SUBSCRIPTION_ID → Staging"] - EPRD["azure-deploy-prod
SUBSCRIPTION_ID → Prod
⚠️ Required reviewers"] - EDST["azure-destroy
SUBSCRIPTION_ID → Default"] - end - - subgraph ENTRA["Microsoft Entra ID"] - APP["App Registration
sp-git-ape-{repo}"] - FC["Federated Credentials
• ref:refs/heads/main
• pull_request
• environment:azure-deploy-dev
• environment:azure-deploy-staging
• environment:azure-deploy-prod
• environment:azure-destroy"] - APP --- FC - end - - DEV["Dev Subscription
Contributor
rg-*-dev"] - STG["Staging Subscription
Contributor
rg-*-stg"] - PRD["Prod Subscription
Contributor + UAA
rg-*-prod"] - - REPO --- EDEV - REPO --- ESTG - REPO --- EPRD - REPO --- EDST - - EDEV -->|"OIDC"| FC - ESTG -->|"OIDC"| FC - EPRD -->|"OIDC"| FC - EDST -->|"OIDC"| FC - - APP -->|"Service Principal"| DEV - APP -->|"Service Principal"| STG - APP -->|"Service Principal"| PRD +
+GitHub environment not created - classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 - classDef ghprod fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 - classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 - classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d - classDef azureprod fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d +Environment creation requires admin access to the repository. Ask a repo admin to create the environments manually via **Settings → Environments**. - class REPO,EDEV,ESTG,EDST gh - class EPRD ghprod - class APP,FC entra - class DEV,STG azure - class PRD azureprod -``` +
--- -## Security Considerations +## Security considerations | Aspect | Implementation | |--------|---------------| | **No stored secrets** | OIDC federated identity — no client secrets or certificates | | **Scoped access** | Federated credentials are scoped per repo + branch/environment | -| **Least privilege** | Only Contributor role by default; add UAA only if needed | -| **Environment gates** | Deploy environments restricted to `main` branch; reviewers optional | -| **Destructive protection** | `azure-destroy` environment can require manual approval | -| **Subscription isolation** | Multi-env mode targets separate subscriptions per stage | +| **Least privilege** | Contributor role by default; add User Access Administrator only when needed | +| **Environment gates** | Deploy environments restricted to `main` branch | +| **Destructive protection** | `azure-destroy` can require manual approval | | **Audit trail** | All deployments logged in `state.json` with actor, timestamp, run URL | - -### Multi-Environment Security Best Practices - -When using multi-environment mode: - -1. **Required reviewers on production** — Always add reviewers to `azure-deploy-prod` -2. **Separate subscriptions** — Use distinct subscriptions for dev, staging, and prod to enforce blast radius isolation -3. **Graduated RBAC** — Use minimal roles in dev (Contributor) and additional roles in prod only when needed -4. **Environment variables for config** — Use GitHub environment variables (not secrets) for non-sensitive environment-specific values like region or resource name prefixes -5. **Deployment promotion** — Deploy to dev first, then staging, then prod — never skip stages - -### Using Environments in Workflows - -With multi-environment mode, update your deploy workflow to select the correct environment: - -```yaml -# In git-ape-deploy.yml, change the environment field to be dynamic: -deploy: - environment: azure-deploy-${{ steps.params.outputs.environment }} - # This resolves to azure-deploy-dev, azure-deploy-staging, or azure-deploy-prod - # based on the "environment" parameter in parameters.json -``` - -The `environment` parameter in your `parameters.json` determines which GitHub environment (and therefore which Azure subscription) is used: - -```json -{ - "parameters": { - "environment": { "value": "prod" }, - "location": { "value": "eastus" }, - "project": { "value": "myapp" } - } -} -``` diff --git a/website/docs/intro.md b/website/docs/intro.md index ef26676..a021866 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -14,7 +14,9 @@ slug: /intro Git-Ape is a **platform engineering framework** built on GitHub Copilot. It provides a structured, multi-agent system for planning, validating, and deploying Azure infrastructure — with security gates, cost analysis, and CI/CD pipeline integration built in. -## What It Does +It is the implementation of the thesis Microsoft published in [Platform Engineering for the Agentic AI Era](https://devblogs.microsoft.com/all-things-azure/platform-engineering-for-the-agentic-ai-era/) — agents and policy replacing module catalogues as the platform team's primary deliverable. See the **[Vision & Manifesto](./vision)** for the full thinking. + +## What it does - **Gather deployment requirements** through guided conversations - **Generate ARM templates** and supporting deployment artifacts @@ -22,6 +24,10 @@ Git-Ape is a **platform engineering framework** built on GitHub Copilot. It prov - **Deploy and validate** with post-deployment health checks - **Manage lifecycle** with drift detection and teardown workflows +## How it works + +Git-Ape enforces compliance at three layers — generation, plan, and runtime — so non-compliant code never reaches your subscription. See [Vision & Manifesto → Three layers of enforcement](./vision#how-it-works--three-layers-of-enforcement). + ## Deployment Flow ```mermaid @@ -79,6 +85,7 @@ copilot plugin install Azure/git-ape ## Next Steps +- [Vision & Manifesto](./vision) — why Git-Ape exists and how it relates to module-first platforms - [Installation & Prerequisites](./getting-started/installation) - [Azure MCP Setup](./getting-started/azure-setup) @@ -92,7 +99,7 @@ copilot plugin install Azure/git-ape ### Popular Use Cases -- [Deploy a Function App](./use-cases/deploy-function-app) +- [Deploy anything](./use-cases/deploy-anything) - [Security Analysis](./use-cases/security-analysis) - [CI/CD Pipeline](./use-cases/cicd-pipeline) - [Headless / Coding Agent Mode](./use-cases/headless-mode) diff --git a/website/docs/personas/for-devops.md b/website/docs/personas/for-devops.mdx similarity index 76% rename from website/docs/personas/for-devops.md rename to website/docs/personas/for-devops.mdx index 3b9ab1b..8e4441f 100644 --- a/website/docs/personas/for-devops.md +++ b/website/docs/personas/for-devops.mdx @@ -10,6 +10,12 @@ keywords: [devops, SRE, CI/CD, OIDC, drift detection, GitHub Actions, deployment > **TL;DR** — Git-Ape provides four GitHub Actions workflows for the full deployment lifecycle: plan-on-PR, deploy-on-merge, destroy-on-request. OIDC auth, no stored secrets, drift detection included. +:::info[Why this matters] +The [Git-Ape manifesto](/docs/vision) frames GitHub as the new control plane: context, instructions, agents, validation, and cloud enforcement layered together. **Drift remediation becomes continuous** — agents detect drift, propose fixes, generate plans, request approval, and apply remediations. + +The gap between observability and action collapses. +::: + @@ -36,6 +42,15 @@ graph LR Manual["Manual dispatch"] --> Verify["git-ape-verify.yml"] Verify --> |"OIDC + RBAC check"| VerifyResult["Setup verified"] + + classDef plan fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef deploy fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef destroy fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d + classDef verify fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + class PR,Plan,Comment,Review plan + class Merge,Deploy,State,SlashDeploy deploy + class DestroyPR,DestroyMerge,Destroy,Cleaned destroy + class Manual,Verify,VerifyResult verify ``` ## OIDC Setup (Zero Stored Secrets) @@ -58,7 +73,7 @@ Subject: repo:{org}/{repo}:ref:refs/heads/main Audience: api://AzureADTokenExchange ``` -:::tip Automated Setup +:::tip[Automated Setup] Use `@git-ape-onboarding` to configure OIDC, RBAC, GitHub environments, and secrets in one guided session. ::: @@ -111,6 +126,17 @@ graph TD RECONCILE --> UPDATE["Update template to match"] RECONCILE --> REVERT["Redeploy to revert"] RECONCILE --> ACCEPT["Accept and update state"] + + classDef start fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef clean fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + classDef cause fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef action fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#78350f + class DETECT,COMPARE,CLASSIFY start + class DRIFT gate + class CLEAN clean + class MANUAL,POLICY,UNKNOWN cause + class RECONCILE,UPDATE,REVERT,ACCEPT action ``` ## GitHub Environment Setup diff --git a/website/docs/personas/for-engineering-leads.md b/website/docs/personas/for-engineering-leads.mdx similarity index 82% rename from website/docs/personas/for-engineering-leads.md rename to website/docs/personas/for-engineering-leads.mdx index 7d1f7b1..9ffa6d4 100644 --- a/website/docs/personas/for-engineering-leads.md +++ b/website/docs/personas/for-engineering-leads.mdx @@ -10,6 +10,12 @@ keywords: [engineering lead, developer productivity, architecture, team enableme > **TL;DR** — Git-Ape automates Azure infrastructure quality so your team ships faster with fewer production incidents. No Azure expertise required from every developer. +:::info[Why this matters] +The [Git-Ape manifesto](/docs/vision) describes how the interaction layer collapses from CLIs, wrappers, and pipeline glue into a single intelligent layer. Your developers describe **what** they want; the agent handles **how** to express it safely. + +Fewer experts needed per repo. Same security baseline whether the deployment is built by a junior dev or a principal engineer. +::: + @@ -64,6 +70,7 @@ The **Principal Architect** agent evaluates every deployment against the Well-Ar ## Integration with Your Workflow ```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','actorBkg':'#dbeafe','actorBorder':'#1f6feb','actorTextColor':'#0b3d91','signalColor':'#475569','signalTextColor':'#0f172a','noteBkgColor':'#fef3c7','noteBorderColor':'#b45309','noteTextColor':'#7c2d12'}}}%% sequenceDiagram participant Dev as Developer participant GA as @git-ape @@ -86,6 +93,6 @@ sequenceDiagram ## Next Steps - [Quick Start for Engineers](/docs/personas/for-engineers) -- [Deploy a Function App](/docs/use-cases/deploy-function-app) +- [Deploy anything](/docs/use-cases/deploy-anything) - [CI/CD Pipeline Setup](/docs/use-cases/cicd-pipeline) - [Agents Overview](/docs/agents/overview) diff --git a/website/docs/personas/for-engineers.md b/website/docs/personas/for-engineers.mdx similarity index 81% rename from website/docs/personas/for-engineers.md rename to website/docs/personas/for-engineers.mdx index 415d483..8054479 100644 --- a/website/docs/personas/for-engineers.md +++ b/website/docs/personas/for-engineers.mdx @@ -10,6 +10,12 @@ keywords: [engineer, developer, quick start, tutorial, cheatsheet, troubleshooti > **TL;DR** — Type `@git-ape deploy a Python function app` in VS Code Copilot Chat. It handles the rest — naming, security, cost, deployment, and testing. +:::info[Why this matters] +The [Git-Ape manifesto](/docs/vision) puts it simply: **interaction shifts from syntax to intent.** You describe what you want; the agent reasons over live Azure API specs and generates compliant code. + +No more memorizing CAF naming conventions, ARM property paths, or RBAC role IDs. +::: + ## 5-Minute Quick Start ### Step 1: Install @@ -53,6 +59,17 @@ graph TD CONFIRM --> DEPLOY["🚀 Deployed"] DEPLOY --> TEST["✅ Integration Tests Passed"] TEST --> STATE["📁 State Committed to Repo"] + + classDef user fill:#e0e7ff,stroke:#4338ca,stroke-width:2px,color:#1e1b4b + classDef agent fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef fix fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d + classDef done fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + class YOU,CONFIRM user + class RG,TG,SA,COST agent + class GATE gate + class FIX fix + class DEPLOY,TEST,STATE done ``` ## Conversation Examples @@ -120,6 +137,6 @@ A resource with that name already exists. Try a different project name or enviro ## Next Steps - [Installation Guide](/docs/getting-started/installation) -- [Deploy a Function App](/docs/use-cases/deploy-function-app) +- [Deploy anything](/docs/use-cases/deploy-anything) - [All Agents](/docs/agents/overview) - [All Skills](/docs/skills/overview) diff --git a/website/docs/personas/for-executives.md b/website/docs/personas/for-executives.mdx similarity index 77% rename from website/docs/personas/for-executives.md rename to website/docs/personas/for-executives.mdx index e35a6ee..743bc8e 100644 --- a/website/docs/personas/for-executives.md +++ b/website/docs/personas/for-executives.mdx @@ -10,6 +10,12 @@ keywords: [executive, CTO, CIO, compliance, governance, cost, risk] > **TL;DR** — Git-Ape gives you automated compliance, cost visibility, and security enforcement for every Azure deployment — without slowing down your engineering teams. +:::info[Why this matters] +In the [Git-Ape manifesto](/docs/vision), compliance shifts from a gate teams pass through to something **inherent in the process**. Every deployment produces a verifiable trail — intent → plan → API calls → validation → evidence — reviewed and approved like any other change. + +This is what "continuous compliance" looks like in practice. +::: + @@ -53,6 +59,17 @@ graph TD GATE -- "PASSED ✅" --> COST["Cost estimate shown"] COST --> DEPLOY["Deployed with integration tests"] DEPLOY --> STATE["State committed to repo"] + + classDef user fill:#e0e7ff,stroke:#4338ca,stroke-width:2px,color:#1e1b4b + classDef process fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef fix fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d + classDef done fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + class DEV user + class REQ,TEMPLATE,COST process + class GATE gate + class FIX fix + class DEPLOY,STATE done ``` ## Key Reports You Get diff --git a/website/docs/personas/for-platform-engineering.md b/website/docs/personas/for-platform-engineering.mdx similarity index 81% rename from website/docs/personas/for-platform-engineering.md rename to website/docs/personas/for-platform-engineering.mdx index bf01734..a244504 100644 --- a/website/docs/personas/for-platform-engineering.md +++ b/website/docs/personas/for-platform-engineering.mdx @@ -10,6 +10,12 @@ keywords: [platform engineering, guardrails, policy, naming, self-service, gover > **TL;DR** — Git-Ape is your self-service deployment platform with built-in guardrails. Developers deploy independently while you maintain security, naming, policy, and cost standards. +:::info[Why this matters] +The [Git-Ape manifesto](/docs/vision) argues that the platform team's deliverable is no longer "here's a module, good luck with the 47 variables." It is **"here's an agent that knows our entire infrastructure context and generates compliant code on demand."** + +Guardrails move into the agent. Modules become knowledge. Drift remediation becomes continuous. +::: + @@ -91,6 +97,13 @@ graph TD DEV --> |"PR + auto-deploy"| STG STG --> |"Approved PR + manual gate"| PROD + + classDef dev fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef stg fill:#fde68a,stroke:#b45309,stroke-width:1px,color:#7c2d12 + classDef prod fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d + class D1,D2,D3 dev + class S1,S2,S3 stg + class P1,P2,P3 prod ``` Each environment gets: @@ -102,6 +115,7 @@ Each environment gets: ## Self-Service Workflow ```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','actorBkg':'#dbeafe','actorBorder':'#1f6feb','actorTextColor':'#0b3d91','signalColor':'#475569','signalTextColor':'#0f172a','noteBkgColor':'#fef3c7','noteBorderColor':'#b45309','noteTextColor':'#7c2d12'}}}%% sequenceDiagram participant Dev as Developer participant GA as Git-Ape diff --git a/website/docs/reference/marketplace.md b/website/docs/reference/marketplace.md index 6f49c29..31e6841 100644 --- a/website/docs/reference/marketplace.md +++ b/website/docs/reference/marketplace.md @@ -1,11 +1,12 @@ - - --- title: "Marketplace Configuration" sidebar_label: "Marketplace" description: "Git-Ape marketplace plugin configuration" --- + + + # Marketplace Configuration The marketplace manifest configures how Git-Ape appears in the Copilot CLI plugin marketplace. diff --git a/website/docs/reference/plugin-json.md b/website/docs/reference/plugin-json.md index 4da1c48..36f591d 100644 --- a/website/docs/reference/plugin-json.md +++ b/website/docs/reference/plugin-json.md @@ -1,11 +1,12 @@ - - --- title: "plugin.json Reference" sidebar_label: "plugin.json" description: "Git-Ape Copilot CLI plugin manifest" --- + + + # plugin.json The plugin manifest defines the Git-Ape Copilot CLI plugin metadata. diff --git a/website/docs/skills/azure-cost-estimator.md b/website/docs/skills/azure-cost-estimator.md index 1056c24..560d29d 100644 --- a/website/docs/skills/azure-cost-estimator.md +++ b/website/docs/skills/azure-cost-estimator.md @@ -1,11 +1,12 @@ - - --- title: "Azure Cost Estimator" sidebar_label: "Azure Cost Estimator" description: "Estimate monthly costs for Azure resources by querying the Azure Retail Prices API. Parses ARM templates to identify resources, SKUs, and regions, then looks up real retail pricing. Produces a per-resource cost breakdown with monthly totals. Use during template generation or when user asks about costs." --- + + + # Azure Cost Estimator > Estimate monthly costs for Azure resources by querying the Azure Retail Prices API. Parses ARM templates to identify resources, SKUs, and regions, then looks up real retail pricing. Produces a per-resource cost breakdown with monthly totals. Use during template generation or when user asks about costs. diff --git a/website/docs/skills/azure-deployment-preflight.md b/website/docs/skills/azure-deployment-preflight.md index b14e2ba..4e9d815 100644 --- a/website/docs/skills/azure-deployment-preflight.md +++ b/website/docs/skills/azure-deployment-preflight.md @@ -1,11 +1,12 @@ - - --- title: "Azure Deployment Preflight" sidebar_label: "Azure Deployment Preflight" description: "Run preflight validation on ARM templates before deployment. Performs what-if analysis, permission checks, and generates a structured report with resource changes (create/modify/delete). Use before any deployment to preview changes and catch issues early." --- + + + # Azure Deployment Preflight > Run preflight validation on ARM templates before deployment. Performs what-if analysis, permission checks, and generates a structured report with resource changes (create/modify/delete). Use before any deployment to preview changes and catch issues early. diff --git a/website/docs/skills/azure-drift-detector.md b/website/docs/skills/azure-drift-detector.md index 616edf8..06340ca 100644 --- a/website/docs/skills/azure-drift-detector.md +++ b/website/docs/skills/azure-drift-detector.md @@ -1,11 +1,12 @@ - - --- title: "Azure Drift Detector" sidebar_label: "Azure Drift Detector" description: "Detect configuration drift between deployed Azure resources and stored deployment state. Compare actual Azure configuration against desired state in .azure/deployments/, identify differences, and guide user through reconciliation options. Use when checking for manual changes, policy remediations, or unauthorized modifications." --- + + + # Azure Drift Detector > Detect configuration drift between deployed Azure resources and stored deployment state. Compare actual Azure configuration against desired state in .azure/deployments/, identify differences, and guide user through reconciliation options. Use when checking for manual changes, policy remediations, or unauthorized modifications. diff --git a/website/docs/skills/azure-integration-tester.md b/website/docs/skills/azure-integration-tester.md index f11a9f6..80360f1 100644 --- a/website/docs/skills/azure-integration-tester.md +++ b/website/docs/skills/azure-integration-tester.md @@ -1,11 +1,12 @@ - - --- title: "Azure Integration Tester" sidebar_label: "Azure Integration Tester" description: "Run post-deployment integration tests for Azure resources. Verify Function Apps, Storage Accounts, Databases, App Services are healthy and accessible. Use after successful Azure deployment." --- + + + # Azure Integration Tester > Run post-deployment integration tests for Azure resources. Verify Function Apps, Storage Accounts, Databases, App Services are healthy and accessible. Use after successful Azure deployment. diff --git a/website/docs/skills/azure-naming-research.md b/website/docs/skills/azure-naming-research.md index da5e348..7420cb5 100644 --- a/website/docs/skills/azure-naming-research.md +++ b/website/docs/skills/azure-naming-research.md @@ -1,11 +1,12 @@ - - --- title: "Azure Naming Research" sidebar_label: "Azure Naming Research" description: "Research Azure naming constraints and CAF abbreviations for a given resource type. Use when you need to look up the official CAF slug, naming rules (length, scope, valid characters), and derive validation/cleaning regex patterns for an Azure resource. Triggers on: CAF abbreviation lookup, Azure naming rules research, resource naming constraints." --- + + + # Azure Naming Research > Research Azure naming constraints and CAF abbreviations for a given resource type. Use when you need to look up the official CAF slug, naming rules (length, scope, valid characters), and derive validation/cleaning regex patterns for an Azure resource. Triggers on: CAF abbreviation lookup, Azure naming rules research, resource naming constraints. diff --git a/website/docs/skills/azure-policy-advisor.md b/website/docs/skills/azure-policy-advisor.md index 0b0bacc..c36f266 100644 --- a/website/docs/skills/azure-policy-advisor.md +++ b/website/docs/skills/azure-policy-advisor.md @@ -1,11 +1,12 @@ - - --- title: "Azure Policy Advisor" sidebar_label: "Azure Policy Advisor" description: "Assess Azure Policy compliance for ARM template resources. Queries existing subscription assignments and unassigned custom/built-in definitions, cross-references with Microsoft Learn recommendations. Produces per-resource policy recommendations with implementation options." --- + + + # Azure Policy Advisor > Assess Azure Policy compliance for ARM template resources. Queries existing subscription assignments and unassigned custom/built-in definitions, cross-references with Microsoft Learn recommendations. Produces per-resource policy recommendations with implementation options. diff --git a/website/docs/skills/azure-resource-availability.md b/website/docs/skills/azure-resource-availability.md index 52c3c3e..d3cfd74 100644 --- a/website/docs/skills/azure-resource-availability.md +++ b/website/docs/skills/azure-resource-availability.md @@ -1,11 +1,12 @@ - - --- title: "Azure Resource Availability" sidebar_label: "Azure Resource Availability" description: "Query live Azure APIs to validate resource availability before template generation or deployment. Checks VM SKU restrictions, Kubernetes/runtime version support, API version compatibility, and subscription quota. Use during requirements gathering and preflight to catch deployment failures early." --- + + + # Azure Resource Availability > Query live Azure APIs to validate resource availability before template generation or deployment. Checks VM SKU restrictions, Kubernetes/runtime version support, API version compatibility, and subscription quota. Use during requirements gathering and preflight to catch deployment failures early. diff --git a/website/docs/skills/azure-resource-visualizer.md b/website/docs/skills/azure-resource-visualizer.md index 41637b6..9e7189a 100644 --- a/website/docs/skills/azure-resource-visualizer.md +++ b/website/docs/skills/azure-resource-visualizer.md @@ -1,11 +1,12 @@ - - --- title: "Azure Resource Visualizer" sidebar_label: "Azure Resource Visualizer" description: "Analyze deployed Azure resource groups and generate detailed Mermaid architecture diagrams showing relationships between resources. Use for post-deployment visualization, understanding existing infrastructure, or documenting live Azure environments." --- + + + # Azure Resource Visualizer > Analyze deployed Azure resource groups and generate detailed Mermaid architecture diagrams showing relationships between resources. Use for post-deployment visualization, understanding existing infrastructure, or documenting live Azure environments. @@ -112,6 +113,19 @@ graph TB FUNC -.->|"instrumentation key"| APPI APP -->|"secrets"| KV FUNC -->|"secrets"| KV + + classDef internet fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b + classDef compute fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef storage fill:#fef3c7,stroke:#92400e,color:#78350f + classDef monitor fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + classDef secret fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + class Internet internet + class APP,FUNC compute + class SQL data + class STORAGE storage + class APPI monitor + class KV secret ``` **Diagram Rules:** diff --git a/website/docs/skills/azure-rest-api-reference.md b/website/docs/skills/azure-rest-api-reference.md index 5214263..3155364 100644 --- a/website/docs/skills/azure-rest-api-reference.md +++ b/website/docs/skills/azure-rest-api-reference.md @@ -1,11 +1,12 @@ - - --- title: "Azure Rest Api Reference" sidebar_label: "Azure Rest Api Reference" description: "Look up Azure REST API and ARM template reference documentation for any resource type. Returns exact property schemas, required fields, valid values, and latest stable API versions. Use BEFORE generating or modifying ARM templates to ensure correctness. No Azure connection required." --- + + + # Azure Rest Api Reference > Look up Azure REST API and ARM template reference documentation for any resource type. Returns exact property schemas, required fields, valid values, and latest stable API versions. Use BEFORE generating or modifying ARM templates to ensure correctness. No Azure connection required. diff --git a/website/docs/skills/azure-role-selector.md b/website/docs/skills/azure-role-selector.md index 7f5a775..2318b0e 100644 --- a/website/docs/skills/azure-role-selector.md +++ b/website/docs/skills/azure-role-selector.md @@ -1,11 +1,12 @@ - - --- title: "Azure Role Selector" sidebar_label: "Azure Role Selector" description: "Recommend least-privilege Azure RBAC roles for deployed resources. Finds minimal built-in roles matching desired permissions or creates custom role definitions. Use during security analysis or when configuring access for service principals and managed identities." --- + + + # Azure Role Selector > Recommend least-privilege Azure RBAC roles for deployed resources. Finds minimal built-in roles matching desired permissions or creates custom role definitions. Use during security analysis or when configuring access for service principals and managed identities. diff --git a/website/docs/skills/azure-security-analyzer.md b/website/docs/skills/azure-security-analyzer.md index 4996642..fe78bcf 100644 --- a/website/docs/skills/azure-security-analyzer.md +++ b/website/docs/skills/azure-security-analyzer.md @@ -1,11 +1,12 @@ - - --- title: "Azure Security Analyzer" sidebar_label: "Azure Security Analyzer" description: "Analyze Azure resource configurations against security best practices using Azure MCP bestpractices service. Produces per-resource security assessment with severity ratings and recommendations. Use during template generation before deployment confirmation." --- + + + # Azure Security Analyzer > Analyze Azure resource configurations against security best practices using Azure MCP bestpractices service. Produces per-resource security assessment with severity ratings and recommendations. Use during template generation before deployment confirmation. diff --git a/website/docs/skills/git-ape-onboarding.md b/website/docs/skills/git-ape-onboarding.md index afa6b8a..82920d5 100644 --- a/website/docs/skills/git-ape-onboarding.md +++ b/website/docs/skills/git-ape-onboarding.md @@ -1,11 +1,12 @@ - - --- title: "Git Ape Onboarding" sidebar_label: "Git Ape Onboarding" description: "Onboard a repository, Azure subscription(s), and user identity for Git-Ape CI/CD using a skill-driven CLI playbook. Use for first-time setup of OIDC, federated credentials, RBAC, GitHub environments, and required secrets." --- + + + # Git Ape Onboarding > Onboard a repository, Azure subscription(s), and user identity for Git-Ape CI/CD using a skill-driven CLI playbook. Use for first-time setup of OIDC, federated credentials, RBAC, GitHub environments, and required secrets. diff --git a/website/docs/skills/overview.md b/website/docs/skills/overview.md index 602a733..ab26a81 100644 --- a/website/docs/skills/overview.md +++ b/website/docs/skills/overview.md @@ -1,5 +1,3 @@ - - --- title: "Skills Overview" sidebar_label: "Overview" @@ -7,6 +5,9 @@ sidebar_position: 1 description: "Overview of all Git-Ape skills organized by deployment phase" --- + + + # Skills Overview Skills are focused capabilities invoked by agents at specific stages of the deployment workflow. Each skill handles one task. @@ -53,4 +54,11 @@ graph LR S3["/azure-drift-detector\n/azure-rest-api-reference\n/git-ape-onboarding"] end Pre --> Post --> Ops + + classDef pre fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef post fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef ops fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + class S1 pre + class S2 post + class S3 ops ``` diff --git a/website/docs/skills/prereq-check.md b/website/docs/skills/prereq-check.md index 9c86994..0e139a6 100644 --- a/website/docs/skills/prereq-check.md +++ b/website/docs/skills/prereq-check.md @@ -1,11 +1,12 @@ - - --- title: "Prereq Check" sidebar_label: "Prereq Check" description: "Check that all required CLI tools are installed, meet minimum versions, and have active auth sessions. Shows platform-specific install commands for anything missing." --- + + + # Prereq Check > Check that all required CLI tools are installed, meet minimum versions, and have active auth sessions. Shows platform-specific install commands for anything missing. diff --git a/website/docs/use-cases/_category_.json b/website/docs/use-cases/_category_.json index bb2ee03..227c4d3 100644 --- a/website/docs/use-cases/_category_.json +++ b/website/docs/use-cases/_category_.json @@ -1,5 +1,5 @@ { - "label": "Use Cases", + "label": "What Git-Ape does", "position": 3, "collapsed": false, "link": null diff --git a/website/docs/use-cases/cicd-pipeline.md b/website/docs/use-cases/cicd-pipeline.md index a4be4c6..99a081b 100644 --- a/website/docs/use-cases/cicd-pipeline.md +++ b/website/docs/use-cases/cicd-pipeline.md @@ -37,6 +37,13 @@ graph TD COMMENT --> APPROVE STATE --> DESTROY_PR + + classDef plan fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef deploy fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef destroy fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d + class COMMIT,PLAN,VALIDATE,WHATIF,COMMENT plan + class APPROVE,DEPLOY_WF,DEPLOY,TEST,STATE deploy + class DESTROY_PR,DESTROY_MERGE,DESTROY_WF,DELETE,UPDATE destroy ``` ## Workflow Details diff --git a/website/docs/use-cases/cost-estimation.md b/website/docs/use-cases/cost-estimation.md index 8842c18..ae144bb 100644 --- a/website/docs/use-cases/cost-estimation.md +++ b/website/docs/use-cases/cost-estimation.md @@ -18,6 +18,15 @@ graph LR PARSE --> API["Azure Retail
Prices API"] API --> CALC["Calculate
monthly cost"] CALC --> REPORT["Per-resource
cost breakdown"] + + classDef input fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef process fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef api fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#78350f + classDef out fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + class TEMPLATE input + class PARSE,CALC process + class API api + class REPORT out ``` The `azure-cost-estimator` skill: @@ -59,5 +68,5 @@ You can also invoke it directly: ## Related - [Skills: Azure Cost Estimator](/docs/skills/azure-cost-estimator) -- [Deploy Function App](/docs/use-cases/deploy-function-app) +- [Deploy anything](/docs/use-cases/deploy-anything) - [For Executives](/docs/personas/for-executives) diff --git a/website/docs/use-cases/deploy-anything.md b/website/docs/use-cases/deploy-anything.md new file mode 100644 index 0000000..4841073 --- /dev/null +++ b/website/docs/use-cases/deploy-anything.md @@ -0,0 +1,183 @@ +--- +title: "Deploy anything" +sidebar_label: "Deploy anything" +sidebar_position: 1 +description: "Git-Ape deploys any Azure workload from natural-language intent — or from a reference architecture you provide" +keywords: [deploy, web app, sql, container apps, reference architecture, intent, ARM] +--- + +# Deploy anything + +> **TL;DR** — Tell `@git-ape` what you want, in plain language. Or hand it a reference architecture link, diagram, or screenshot. Either way, it generates a CAF-compliant ARM template with security, cost, and policy enforced before deployment. + +Git-Ape is **workload-agnostic**. If Azure Resource Manager can deploy it, the agent can generate it — using the live Azure REST API specs at generation time, not last year's module catalogue. + +## Three ways to describe what you want + +```mermaid +flowchart LR + A["Natural-language intent
'Deploy a .NET web app with SQL'"] --> AGENT + B["Reference architecture URL
learn.microsoft.com/architecture/..."] --> AGENT + C["Diagram or screenshot
your hand-drawn whiteboard"] --> AGENT + AGENT["@git-ape
reasons over live Azure API specs
+ your security & naming policy"] --> OUT["ARM template
+ security gate
+ cost estimate
+ deployment trace"] + + classDef input fill:#dbeafe,stroke:#1f6feb,color:#0b3d91 + classDef agent fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + classDef out fill:#fde68a,stroke:#b45309,color:#7c2d12 + class A,B,C input + class AGENT agent + class OUT out +``` + +| Input | Example prompt | +|---|---| +| **Plain intent** | `@git-ape deploy a .NET web app with SQL Database for the customer portal in dev` | +| **Reference architecture** | `@git-ape implement this reference architecture: https://learn.microsoft.com/azure/architecture/reference-architectures/...` | +| **Diagram or picture** | Attach a PNG or markdown with mermaid, then: `@git-ape deploy what's in this diagram for the payments-api project` | + +The agent reads the input, asks clarifying questions only when needed (region, environment, project name), and produces a full deployment plan you can review before approval. + +--- + +## Example 1 — Web app with SQL Database + +A common full-stack pattern: App Service with managed identity to SQL Database, secrets in Key Vault. + +```mermaid +graph TD + subgraph RG["rg-portal-dev-eastus"] + APP["app-portal-dev-eastus
App Service (.NET)"] + ASP["asp-portal-dev-eastus
App Service Plan (B1)"] + SQL["sql-portal-dev-eastus
SQL Server"] + SQLDB["sqldb-portal-dev
SQL Database"] + KV["kv-portal-dev-eus
Key Vault"] + AI["appi-portal-dev-eastus
App Insights"] + end + + APP --> |"Managed identity
AAD-only auth"| SQLDB + SQLDB --> |"Hosted on"| SQL + APP --> |"@Microsoft.KeyVault(...)"| KV + APP --> |"Telemetry"| AI + APP --> |"Hosted on"| ASP + + classDef compute fill:#dbeafe,stroke:#1f6feb,color:#0b3d91 + classDef data fill:#dcfce7,stroke:#15803d,color:#14532d + classDef secret fill:#fde68a,stroke:#b45309,color:#7c2d12 + classDef obs fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class APP,ASP compute + class SQL,SQLDB data + class KV secret + class AI obs +``` + +**Prompt:** + +```text +@git-ape deploy a .NET web app with SQL Database and Key Vault + for the customer-portal project in dev, eastus +``` + +**What you get:** + +| Resource | Key settings enforced automatically | +|---|---| +| App Service | HTTPS-only, TLS 1.2, managed identity, FTP disabled | +| SQL Server | `azureADOnlyAuthentication: true` — no SQL username/password | +| SQL Database | Standard S1, geo-backup enabled | +| Key Vault | RBAC authorization, soft-delete + purge protection | +| RBAC | App Service → `SQL DB Contributor`, App Service → `Key Vault Secrets User` | + +--- + +## Example 2 — Container Apps + +A containerised microservice with auto-scaling, private registry, and centralised logging. + +```mermaid +graph TD + subgraph RG["rg-payments-dev-eastus"] + CA["ca-payments-dev-eastus
Container App"] + CAE["cae-payments-dev-eastus
Container Apps Environment"] + ACR["crpaymentsdev
Container Registry"] + LOG["log-payments-dev-eastus
Log Analytics"] + end + + CA --> |"Pull images
(AcrPull role)"| ACR + CA --> |"Hosted in"| CAE + CAE --> |"App logs"| LOG + + classDef compute fill:#dbeafe,stroke:#1f6feb,color:#0b3d91 + classDef registry fill:#fde68a,stroke:#b45309,color:#7c2d12 + classDef obs fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class CA,CAE compute + class ACR registry + class LOG obs +``` + +**Prompt:** + +```text +@git-ape deploy a Container App with Registry and Log Analytics + for the payments-api project in dev, eastus +``` + +**What you get:** + +| Resource | Key settings enforced automatically | +|---|---| +| Container App | Min replicas: 0, max: 10, scale on HTTP concurrency | +| Container Apps Environment | Connected to Log Analytics workspace | +| Container Registry | Admin user disabled, managed identity pull only | +| RBAC | Container App → `AcrPull` on registry | +| Log Analytics | 30-day retention | + +--- + +## Use a reference architecture as the source of truth + +The Git-Ape [Vision](/docs/vision) describes a future state where governed documents — reference architectures, ADRs, security baselines — become the **ledger** that drives deployments. The agent's job is to compile those documents into compliant infrastructure. + +You can do this today: + +1. **Point the agent at a published Azure reference architecture URL.** The agent fetches it, identifies the resources, and produces an ARM template that matches. +2. **Attach a diagram or screenshot of an internal architecture pattern.** The agent reads the boxes and arrows and proposes a deployment. +3. **Reference an Architecture Decision Record (ADR) in your repo.** The agent treats the ADR as authoritative and validates the generated template against it. + +```text +@git-ape deploy this reference architecture for the order-api project, dev: +https://learn.microsoft.com/azure/architecture/reference-architectures/... +``` + +Whatever you use as input, the agent produces the same artifacts: a CAF-compliant ARM template, a security analysis, a cost estimate, and a deployment trace under [`.azure/deployments/`](/docs/deployment/state) — your auditable evidence of intent → plan → outcome. + +--- + +## What happens after you approve + +```mermaid +flowchart LR + REQ["Requirements
gathered"] --> GEN["Template
generated"] + GEN --> SEC["Security gate
(blocking)"] + SEC --> COST["Cost estimate
shown"] + COST --> APPROVE{"You approve?"} + APPROVE -->|"yes"| DEPLOY["az deployment
sub create"] + APPROVE -->|"no"| EXIT["Iterate or stop"] + DEPLOY --> TEST["Integration
tests"] + TEST --> STATE["state.json
committed"] + + classDef gate fill:#fde68a,stroke:#b45309,color:#7c2d12 + classDef deploy fill:#dcfce7,stroke:#15803d,color:#14532d + class SEC,APPROVE gate + class DEPLOY,TEST,STATE deploy +``` + +See the full lifecycle in [State Management](/docs/deployment/state) and [CI/CD Pipeline](/docs/use-cases/cicd-pipeline). + +--- + +## Related + +- [Vision & Manifesto](/docs/vision) — why agents over modules +- [Security Analysis](/docs/use-cases/security-analysis) — what the security gate checks +- [Cost Estimation](/docs/use-cases/cost-estimation) — how pricing is computed +- [Skills overview](/docs/skills/overview) — every capability the agent invokes diff --git a/website/docs/use-cases/deploy-container-app.md b/website/docs/use-cases/deploy-container-app.md deleted file mode 100644 index 5219108..0000000 --- a/website/docs/use-cases/deploy-container-app.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "Deploy Container Apps" -sidebar_label: "Deploy Container Apps" -sidebar_position: 3 -description: "Deploy Azure Container Apps with Container Registry, Log Analytics, and auto-scaling" -keywords: [container apps, container registry, docker, log analytics, scaling] ---- - -# Deploy Container Apps - -> **TL;DR** — Deploy a containerized application on Azure Container Apps with registry, logging, and auto-scaling configured automatically. - -## Architecture - -```mermaid -graph TD - subgraph RG["rg-containerapp-dev-eastus"] - CA["ca-api-dev-eastus
Container App"] - CAE["cae-api-dev-eastus
Container Apps Environment"] - ACR["crcontappdev
Container Registry"] - LOG["log-api-dev-eastus
Log Analytics"] - end - - CA --> |"Pull images"| ACR - CA --> |"Hosted in"| CAE - CAE --> |"App logs"| LOG - CA --> |"Managed Identity
AcrPull role"| ACR -``` - -## Conversation - -``` -@git-ape deploy a Container App with Registry and Log Analytics - for the payments-api project in dev, eastus -``` - -## Key Configuration - -| Resource | Settings | -|----------|----------| -| Container App | Min replicas: 0, Max: 10, CPU: 0.5, Memory: 1Gi | -| Container Apps Environment | Connected to Log Analytics workspace | -| Container Registry | Basic SKU, admin user disabled, managed identity pull | -| Log Analytics | 30-day retention | - -## Scaling Rules - -Container Apps auto-scales based on HTTP traffic: - -```json -{ - "scale": { - "minReplicas": 0, - "maxReplicas": 10, - "rules": [ - { - "name": "http-scaling", - "http": { "metadata": { "concurrentRequests": "50" } } - } - ] - } -} -``` - -## Related - -- [Deploy Function App](/docs/use-cases/deploy-function-app) -- [CI/CD Pipeline](/docs/use-cases/cicd-pipeline) -- [Cost Estimation](/docs/use-cases/cost-estimation) diff --git a/website/docs/use-cases/deploy-function-app.md b/website/docs/use-cases/deploy-function-app.md deleted file mode 100644 index 1989d01..0000000 --- a/website/docs/use-cases/deploy-function-app.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Deploy a Function App" -sidebar_label: "Deploy Function App" -sidebar_position: 1 -description: "Step-by-step guide to deploying a Python Function App with Storage and App Insights using Git-Ape" -keywords: [function app, serverless, python, storage, app insights, deployment] ---- - -# Deploy a Function App - -> **TL;DR** — Tell `@git-ape` to deploy a Function App. It generates an ARM template with managed identity, storage, App Insights, and deploys with full security analysis. - -## Architecture - -```mermaid -graph TD - subgraph RG["rg-funcapp-dev-eastus"] - FA["func-api-dev-eastus
Function App (Python)"] - ASP["asp-api-dev-eastus
App Service Plan (Consumption)"] - ST["stfuncapidev8k3m
Storage Account"] - AI["appi-api-dev-eastus
Application Insights"] - LOG["log-api-dev-eastus
Log Analytics Workspace"] - end - - FA --> |"Identity-based
AzureWebJobsStorage__accountName"| ST - FA --> |"APPLICATIONINSIGHTS_
CONNECTION_STRING"| AI - AI --> |"Workspace"| LOG - FA --> |"Hosted on"| ASP -``` - -## Conversation Walkthrough - -### Start the Deployment - -``` -@git-ape deploy a Python Function App with Storage and App Insights - for the order-api project in dev, region eastus -``` - -### What Git-Ape Does - -1. **Requirements Gatherer** validates your inputs: - - Project name: `order-api` → valid characters, reasonable length - - Environment: `dev` → recognized tag - - Region: `eastus` → available for all resource types - -2. **Naming Research** generates CAF-compliant names: - - Function App: `func-orderapi-dev-eastus` - - Storage: `storderapidev` + `uniqueString()` - - App Insights: `appi-orderapi-dev-eastus` - -3. **Template Generator** creates the ARM template with: - - Managed identity (`AzureWebJobsStorage__accountName`) - - HTTPS-only, TLS 1.2 - - FTP disabled - - Shared key access disabled on storage - - RBAC: Storage Blob Data Contributor for the Function App's managed identity - -4. **Security Analyzer** runs the blocking gate: - - ``` - 🔒 Security Gate: PASSED ✅ - ├── ✅ Managed identity enabled - ├── ✅ HTTPS-only enforced - ├── ✅ TLS 1.2 minimum - ├── ✅ FTP disabled - ├── ✅ Shared key access disabled - └── ✅ RBAC role assignments included - ``` - -5. **Cost Estimator** shows the breakdown: - - | Resource | SKU | Estimated Cost | - |----------|-----|---------------| - | Function App | Consumption (Y1) | $0.00 (free tier) | - | Storage Account | Standard LRS | $2.40/mo | - | App Insights | Pay-as-you-go | $2.30/mo | - | Log Analytics | Pay-as-you-go | $2.76/mo | - | **Total** | | **$7.46/mo** | - -6. **You approve** → deployment executes → integration tests verify health - -## Key Security Features - -- **No connection strings** — uses `AzureWebJobsStorage__accountName` (identity-based) -- **`allowSharedKeyAccess: false`** — storage only accepts managed identity auth -- **`ftpsState: Disabled`** — no FTP access to the Function App -- **`httpsOnly: true`** — all traffic encrypted -- **`minTlsVersion: '1.2'`** — no legacy TLS - -## Related - -- [Skills: Azure Cost Estimator](/docs/skills/azure-cost-estimator) -- [Skills: Azure Security Analyzer](/docs/skills/azure-security-analyzer) -- [Skills: Azure Naming Research](/docs/skills/azure-naming-research) -- [For Engineers: Quick Start](/docs/personas/for-engineers) diff --git a/website/docs/use-cases/deploy-web-app-sql.md b/website/docs/use-cases/deploy-web-app-sql.md deleted file mode 100644 index 07e923e..0000000 --- a/website/docs/use-cases/deploy-web-app-sql.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Deploy Web App + SQL" -sidebar_label: "Deploy Web App + SQL" -sidebar_position: 2 -description: "Deploy a full-stack web application with SQL Database, Key Vault, and managed identities" -keywords: [web app, SQL, key vault, full-stack, app service, deployment] ---- - -# Deploy Web App + SQL Database - -> **TL;DR** — Deploy a full-stack web application with Azure SQL, Key Vault for secrets, and managed identities for secure resource communication. - -## Architecture - -```mermaid -graph TD - subgraph RG["rg-webapp-dev-eastus"] - APP["app-portal-dev-eastus
App Service (.NET)"] - ASP["asp-portal-dev-eastus
App Service Plan (B1)"] - SQL["sql-portal-dev-eastus
SQL Server"] - SQLDB["sqldb-portal-dev
SQL Database"] - KV["kv-portal-dev-eus
Key Vault"] - AI["appi-portal-dev-eastus
Application Insights"] - end - - APP --> |"Managed Identity
AAD-only auth"| SQLDB - SQLDB --> |"Hosted on"| SQL - APP --> |"@Microsoft.KeyVault(...)"| KV - APP --> |"Telemetry"| AI - APP --> |"Hosted on"| ASP -``` - -## Conversation - -``` -@git-ape deploy a .NET web app with SQL Database and Key Vault - for the customer-portal project in dev, eastus -``` - -## Resource Configuration - -| Resource | Key Settings | -|----------|-------------| -| App Service | HTTPS-only, TLS 1.2, managed identity enabled, FTP disabled | -| SQL Server | AAD-only auth (`azureADOnlyAuthentication: true`), no SQL auth | -| SQL Database | Standard S1, geo-backup enabled | -| Key Vault | RBAC authorization, soft-delete enabled, purge protection | -| App Insights | Connected via instrumentation key in Key Vault | - -## Security Highlights - -- **AAD-only SQL authentication** — no SQL username/password -- **Key Vault references** — app settings use `@Microsoft.KeyVault(SecretUri=...)` syntax -- **Managed identity chain** — App Service → SQL Database, App Service → Key Vault -- **RBAC roles auto-assigned**: - - App Service → `SQL DB Contributor` on SQL Database - - App Service → `Key Vault Secrets User` on Key Vault - -## Related - -- [Security Analysis Walkthrough](/docs/use-cases/security-analysis) -- [Cost Estimation](/docs/use-cases/cost-estimation) -- [For Engineers](/docs/personas/for-engineers) diff --git a/website/docs/use-cases/drift-detection.md b/website/docs/use-cases/drift-detection.md index 74c538e..36bf613 100644 --- a/website/docs/use-cases/drift-detection.md +++ b/website/docs/use-cases/drift-detection.md @@ -13,6 +13,7 @@ keywords: [drift detection, configuration drift, reconciliation, state managemen ## How Drift Detection Works ```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','actorBkg':'#dbeafe','actorBorder':'#1f6feb','actorTextColor':'#0b3d91','signalColor':'#475569','signalTextColor':'#0f172a','noteBkgColor':'#fef3c7','noteBorderColor':'#b45309','noteTextColor':'#7c2d12'}}}%% sequenceDiagram participant User participant GitApe as Git-Ape diff --git a/website/docs/use-cases/headless-mode.md b/website/docs/use-cases/headless-mode.md index 416a1ea..a31c8bc 100644 --- a/website/docs/use-cases/headless-mode.md +++ b/website/docs/use-cases/headless-mode.md @@ -13,6 +13,7 @@ keywords: [headless, coding agent, GitHub Issues, automated, pull request, CI/CD ## End-to-End Flow ```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','actorBkg':'#dbeafe','actorBorder':'#1f6feb','actorTextColor':'#0b3d91','signalColor':'#475569','signalTextColor':'#0f172a','noteBkgColor':'#fef3c7','noteBorderColor':'#b45309','noteTextColor':'#7c2d12'}}}%% sequenceDiagram participant User participant Issue as GitHub Issue diff --git a/website/docs/use-cases/import-existing-infra.md b/website/docs/use-cases/import-existing-infra.md index 15ec6c9..0352a71 100644 --- a/website/docs/use-cases/import-existing-infra.md +++ b/website/docs/use-cases/import-existing-infra.md @@ -20,6 +20,17 @@ graph TD TEMPLATE --> REVIEW["You review
& adjust"] REVIEW --> COMMIT["Commit to
.azure/deployments/"] COMMIT --> MANAGED["Now managed
by Git-Ape"] + + classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef agent fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef artifact fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#78350f + classDef user fill:#e0e7ff,stroke:#4338ca,stroke-width:1px,color:#1e1b4b + classDef done fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + class LIVE azure + class EXPORT,ANALYZE agent + class TEMPLATE,COMMIT artifact + class REVIEW user + class MANAGED done ``` ## Invoke It diff --git a/website/docs/use-cases/multi-environment.md b/website/docs/use-cases/multi-environment.md index dbd0d2f..e0a38fd 100644 --- a/website/docs/use-cases/multi-environment.md +++ b/website/docs/use-cases/multi-environment.md @@ -33,6 +33,13 @@ graph LR DEV --> |"Promote"| STAGING STAGING --> |"Promote"| PROD + + classDef dev fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef stg fill:#fde68a,stroke:#b45309,stroke-width:1px,color:#7c2d12 + classDef prod fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d + class D_RG,D_FUNC dev + class S_RG,S_FUNC stg + class P_RG1,P_FUNC1,P_RG2,P_FUNC2 prod ``` ## File Structure diff --git a/website/docs/use-cases/policy-compliance.md b/website/docs/use-cases/policy-compliance.md index e0babc4..167cc98 100644 --- a/website/docs/use-cases/policy-compliance.md +++ b/website/docs/use-cases/policy-compliance.md @@ -21,6 +21,15 @@ graph TD UNASSIGNED --> PART2["Part 2: Subscription
Policy Assignments"] PART1 --> REPORT["policy-assessment.md"] PART2 --> REPORT + + classDef input fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef scan fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef policy fill:#fef3c7,stroke:#92400e,stroke-width:1px,color:#78350f + classDef out fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + class TEMPLATE input + class SCAN scan + class ASSIGNED,UNASSIGNED,PART1,PART2 policy + class REPORT out ``` ## Invoke It diff --git a/website/docs/use-cases/security-analysis.md b/website/docs/use-cases/security-analysis.md index dbdfc9e..c95a76a 100644 --- a/website/docs/use-cases/security-analysis.md +++ b/website/docs/use-cases/security-analysis.md @@ -25,6 +25,17 @@ graph TD FIX --> ANALYZE MANUAL --> ANALYZE OVERRIDE --> PASSED + + classDef input fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef process fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12 + classDef passed fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d + classDef blocked fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d + class TEMPLATE input + class ANALYZE,OPTIONS,FIX,MANUAL,OVERRIDE process + class RESULT gate + class PASSED passed + class BLOCKED blocked ``` ## What Gets Checked @@ -69,7 +80,7 @@ graph TD When a deployment fails after passing the security gate, Git-Ape follows strict recovery rules: -:::danger Never Weaken Security +:::danger[Never Weaken Security] - Do NOT re-enable shared key access - Do NOT disable firewalls or open NSGs - Do NOT remove authentication requirements diff --git a/website/docs/use-cases/waf-review.md b/website/docs/use-cases/waf-review.md index a460d45..5dcf32a 100644 --- a/website/docs/use-cases/waf-review.md +++ b/website/docs/use-cases/waf-review.md @@ -20,6 +20,19 @@ graph LR WAF --> PERF["⚡ Performance"] WAF --> COST["💰 Cost"] WAF --> OPS["📋 Operations"] + + classDef center fill:#1f6feb,stroke:#0b3d91,stroke-width:2px,color:#ffffff + classDef sec fill:#fecaca,stroke:#b91c1c,color:#7f1d1d + classDef rel fill:#dbeafe,stroke:#1f6feb,color:#0b3d91 + classDef perf fill:#fde68a,stroke:#b45309,color:#7c2d12 + classDef cost fill:#dcfce7,stroke:#15803d,color:#14532d + classDef ops fill:#ede9fe,stroke:#7c3aed,color:#4c1d95 + class WAF center + class SEC sec + class REL rel + class PERF perf + class COST cost + class OPS ops ``` | Pillar | What It Assesses | diff --git a/website/docs/vision.md b/website/docs/vision.md new file mode 100644 index 0000000..cd10e43 --- /dev/null +++ b/website/docs/vision.md @@ -0,0 +1,149 @@ +--- +title: "Vision & Manifesto" +sidebar_label: "Vision & Manifesto" +sidebar_position: 2 +description: "Why Git-Ape exists — platform engineering for the agentic AI era" +slug: /vision +--- + +# Vision & Manifesto + +Git-Ape is the implementation of a thesis Microsoft published in March 2026: **[Platform Engineering for the Agentic AI Era](https://devblogs.microsoft.com/all-things-azure/platform-engineering-for-the-agentic-ai-era/)**. This page summarizes the thesis and shows where each idea is implemented in the codebase. + +## The shift + +For a decade, platform engineering relied on humans translating intent into machine-safe API calls — through CLIs, SDKs, pipelines, wrappers, and UI workflows. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc'}}}%% +flowchart LR + subgraph TRAD["Traditional model"] + H1["Human intent"] --> L1["CLIs / pipelines / wrappers"] + L1 --> L2["IaC abstraction
(ARM, Bicep, Terraform)"] + L2 --> L3["Provider APIs"] + end + + classDef step fill:#e2e8f0,stroke:#475569,color:#0f172a + class H1,L1,L2,L3 step +``` + +AI agents collapse that stack. They ingest natural language, reason over API schemas, generate and validate IaC, and apply changes through provider APIs — all while enforcing guardrails and approvals inline. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc'}}}%% +flowchart LR + H["Human intent"] --> A["Agent
reasoning + policy"] + A --> X["IaC / APIs
(implementation detail)"] + + classDef agent fill:#dbeafe,stroke:#1f6feb,stroke-width:2px,color:#0b3d91 + classDef step fill:#e2e8f0,stroke:#475569,color:#0f172a + class A agent + class H,X step +``` + +> **Agents don't bypass APIs — they bypass humans as API translators.** The interaction layer becomes implicit, dynamically constructed by the agent using API specs, provider schemas, and organizational controls. + +## What Git-Ape is + +Git-Ape is an **agent + policy** platform-engineering framework for Azure, built on GitHub Copilot. It is an alternative to module-first IaC platforms. + +| Module-first platform | Git-Ape (agents + policy) | +|---|---| +| 50+ Terraform/Bicep modules to maintain | One agent, many compiled outputs | +| Last year's API surface | Reads live Azure REST API specs ([azure-rest-api-reference](/docs/skills/azure-rest-api-reference)) | +| Static `README.md` per module | Living docs generated at conversation time | +| "Update 50 modules when standards change" | "Update the agent's context" | +| Compliance enforced at PR review | Compliance enforced at generation, plan, and runtime | + +## How it works — three layers of enforcement + +The manifesto's central claim is that compliance is no longer a gate you pass through — it is **inherent in the process**. Git-Ape implements that with three enforcement layers: + +```mermaid +%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc'}}}%% +flowchart TD + subgraph L1["1. Generation layer"] + G1["Agent applies your patterns
at generation time"] + G2["azure-naming-research
azure-security-analyzer
azure-role-selector"] + end + subgraph L2["2. Plan / static-analysis layer"] + P1["What-if + linters block
non-compliant code before merge"] + P2["Checkov, ARM-TTK, PSRule
git-ape-plan.yml"] + end + subgraph L3["3. Runtime layer"] + R1["Azure Policy denies or audits
at deployment time"] + R2["azure-policy-advisor
CIS / NIST initiatives"] + end + L1 --> L2 --> L3 + + classDef layer fill:#dcfce7,stroke:#15803d,color:#14532d + classDef detail fill:#f1f5f9,stroke:#94a3b8,color:#0f172a + class G1,P1,R1 layer + class G2,P2,R2 detail +``` + +### Generation layer + +Git-Ape skills enforce policy **before** any IaC is written: + +- **[`azure-naming-research`](/docs/skills/azure-naming-research)** — looks up CAF abbreviations and validates names against Azure constraints +- **[`azure-rest-api-reference`](/docs/skills/azure-rest-api-reference)** — reads the live Azure REST API specs so generated templates use correct properties and the latest stable API versions +- **[`azure-security-analyzer`](/docs/skills/azure-security-analyzer)** — blocks Critical and High security findings before deployment +- **[`azure-role-selector`](/docs/skills/azure-role-selector)** — recommends least-privilege roles instead of broad Contributor grants + +### Plan / static-analysis layer + +When a PR is opened, **[`git-ape-plan.yml`](/docs/workflows/git-ape-plan)** runs Checkov, ARM-TTK, PSRule, Template Analyzer, plus `az deployment what-if`. Non-compliant code is blocked before merge. See [Security Analysis](/docs/use-cases/security-analysis). + +### Runtime layer + +Even after merge, **[`azure-policy-advisor`](/docs/skills/azure-policy-advisor)** assesses your templates against Azure Policy initiatives (CIS Azure Foundations v3.0, NIST SP 800-53 Rev 5) and Azure Policy denies or audits non-compliant deployments at the control plane. + +## What does not change + +The fundamentals remain: + +- **Provider APIs** are still the ultimate source of truth. +- **Human accountability** remains essential. Git-Ape never deploys without explicit user confirmation, and CI/CD deploys require PR approval. +- **IaC** is still the deterministic, versioned, reviewable execution format. It is not eliminated — it becomes a **compiled artifact** generated from higher-order inputs. + +What changes is your **system of record**. Architecture artifacts (ADRs, reference patterns, security baselines, naming conventions) become the governing ledger. The agent's execution trace — saved in [`.azure/deployments/`](/docs/deployment/state) — is the binding evidence between intent and outcome. + +## The new artifacts the platform team produces + +Quoting the manifesto: + +> The module registry isn't dead — but it's no longer the centre of gravity. **The new artifact is the agent.** Policies, context documents, and examples become inputs the agent consumes. The agent itself is what the platform team produces — versioned, tested, and deployed like any other software. + +In Git-Ape this maps to: + +| Concept | Where it lives in the repo | +|---|---| +| Repo-level instructions | `.github/copilot-instructions.md` | +| Reusable skills | [`.github/skills/`](/docs/skills/overview) | +| Custom agents | [`.github/agents/`](/docs/agents/overview) | +| CI/CD enforcement | [`.github/workflows/`](/docs/workflows/overview) | +| Execution trace | [`.azure/deployments/`](/docs/deployment/state) | + +## Who this changes things for + +The manifesto identifies four shifts that map directly to the audiences Git-Ape serves: + +| Shift | Audience | Where to read more | +|---|---|---| +| Interaction shifts from syntax to intent | **[Engineers](/docs/personas/for-engineers)** describe what they need in natural language | [Deploy anything](/docs/use-cases/deploy-anything) | +| Guardrails move into the agent | **[Platform engineers](/docs/personas/for-platform-engineering)** ship agents and skills, not module catalogues | [Skills overview](/docs/skills/overview) | +| Compliance is inherent in the process | **[Executives](/docs/personas/for-executives)** get continuous compliance evidence, not point-in-time audits | [Security Analysis](/docs/use-cases/security-analysis) | +| Drift remediation becomes continuous | **[DevOps & SRE](/docs/personas/for-devops)** detect drift, propose fixes, request approval, apply remediations | [Drift Detection](/docs/deployment/drift-detection) | + +## What's next + +This implementation covers Azure ARM today, with an explicit roadmap toward Bicep and Terraform compatibility, code-to-cloud security with Defender for Cloud, and day-2 operations through Azure SRE Agent. + +Read the original article: **[Platform Engineering for the Agentic AI Era](https://devblogs.microsoft.com/all-things-azure/platform-engineering-for-the-agentic-ai-era/)** by Arnaud Lheureux and David Wright. + +Then jump into the project: + +- [Installation](/docs/getting-started/installation) — get Git-Ape running in 5 minutes +- [Onboarding](/docs/getting-started/onboarding) — wire up OIDC and CI/CD +- [Agents](/docs/agents/overview) and [Skills](/docs/skills/overview) — see what's already implemented diff --git a/website/docs/workflows/git-ape-deploy.md b/website/docs/workflows/git-ape-deploy.md index cd5e102..6e23309 100644 --- a/website/docs/workflows/git-ape-deploy.md +++ b/website/docs/workflows/git-ape-deploy.md @@ -1,14 +1,15 @@ - - --- title: "Git-Ape: Deploy" sidebar_label: "Deploy" description: "GitHub Actions workflow: Git-Ape: Deploy" --- + + + # Git-Ape: Deploy -**Workflow file:** `.github/workflows/git-ape-deploy.yml` +**Workflow file:** `.github/workflows/git-ape-deploy.exampleyml` ## Triggers diff --git a/website/docs/workflows/git-ape-destroy.md b/website/docs/workflows/git-ape-destroy.md index dbd7b92..ee249dd 100644 --- a/website/docs/workflows/git-ape-destroy.md +++ b/website/docs/workflows/git-ape-destroy.md @@ -1,14 +1,15 @@ - - --- title: "Git-Ape: Destroy" sidebar_label: "Destroy" description: "GitHub Actions workflow: Git-Ape: Destroy" --- + + + # Git-Ape: Destroy -**Workflow file:** `.github/workflows/git-ape-destroy.yml` +**Workflow file:** `.github/workflows/git-ape-destroy.exampleyml` ## Triggers diff --git a/website/docs/workflows/git-ape-docs-check.md b/website/docs/workflows/git-ape-docs-check.md index 2e8f341..ff5c102 100644 --- a/website/docs/workflows/git-ape-docs-check.md +++ b/website/docs/workflows/git-ape-docs-check.md @@ -1,11 +1,12 @@ - - --- title: "Git-Ape: Docs Check" sidebar_label: "Docs Check" description: "GitHub Actions workflow: Git-Ape: Docs Check" --- + + + # Git-Ape: Docs Check **Workflow file:** `.github/workflows/git-ape-docs-check.yml` diff --git a/website/docs/workflows/git-ape-docs.md b/website/docs/workflows/git-ape-docs.md index 1d3f050..0092aa9 100644 --- a/website/docs/workflows/git-ape-docs.md +++ b/website/docs/workflows/git-ape-docs.md @@ -1,11 +1,12 @@ - - --- title: "Git-Ape: Docs Deploy" sidebar_label: "Docs Deploy" description: "GitHub Actions workflow: Git-Ape: Docs Deploy" --- + + + # Git-Ape: Docs Deploy **Workflow file:** `.github/workflows/git-ape-docs.yml` diff --git a/website/docs/workflows/git-ape-plan.md b/website/docs/workflows/git-ape-plan.md index d957962..6423382 100644 --- a/website/docs/workflows/git-ape-plan.md +++ b/website/docs/workflows/git-ape-plan.md @@ -1,14 +1,15 @@ - - --- title: "Git-Ape: Plan" sidebar_label: "Plan" description: "GitHub Actions workflow: Git-Ape: Plan" --- + + + # Git-Ape: Plan -**Workflow file:** `.github/workflows/git-ape-plan.yml` +**Workflow file:** `.github/workflows/git-ape-plan.exampleyml` ## Triggers diff --git a/website/docs/workflows/git-ape-verify.md b/website/docs/workflows/git-ape-verify.md index 5c787bf..d4a9e89 100644 --- a/website/docs/workflows/git-ape-verify.md +++ b/website/docs/workflows/git-ape-verify.md @@ -1,14 +1,15 @@ - - --- title: "Git-Ape: Verify Setup" sidebar_label: "Verify Setup" description: "GitHub Actions workflow: Git-Ape: Verify Setup" --- + + + # Git-Ape: Verify Setup -**Workflow file:** `.github/workflows/git-ape-verify.yml` +**Workflow file:** `.github/workflows/git-ape-verify.exampleyml` ## Triggers diff --git a/website/docs/workflows/overview.md b/website/docs/workflows/overview.md index 2204329..9c4c069 100644 --- a/website/docs/workflows/overview.md +++ b/website/docs/workflows/overview.md @@ -1,5 +1,3 @@ - - --- title: "CI/CD Workflows Overview" sidebar_label: "Overview" @@ -7,6 +5,9 @@ sidebar_position: 1 description: "Overview of Git-Ape GitHub Actions workflows" --- + + + # CI/CD Workflows Overview Git-Ape provides GitHub Actions workflows for automated deployment lifecycle management. @@ -15,8 +16,12 @@ Git-Ape provides GitHub Actions workflows for automated deployment lifecycle man | Workflow | File | Triggers | Jobs | |----------|------|----------|------| +| [Git-Ape: Deploy](./git-ape-deploy) | `git-ape-deploy.exampleyml` | push, issue_comment | check-comment-trigger, detect-deployments, deploy | +| [Git-Ape: Destroy](./git-ape-destroy) | `git-ape-destroy.exampleyml` | push, workflow_dispatch | detect-destroys, destroy | | [Git-Ape: Docs Check](./git-ape-docs-check) | `git-ape-docs-check.yml` | pull_request | check-docs | | [Git-Ape: Docs Deploy](./git-ape-docs) | `git-ape-docs.yml` | push | build, deploy | +| [Git-Ape: Plan](./git-ape-plan) | `git-ape-plan.exampleyml` | pull_request | detect-deployments, plan-local, plan-azure, plan-comment | +| [Git-Ape: Verify Setup](./git-ape-verify) | `git-ape-verify.exampleyml` | workflow_dispatch | verify | ## Pipeline Architecture @@ -34,4 +39,15 @@ graph LR DestroyMerge --> DestroyWF["git-ape-destroy.yml
Delete Resources"] Manual["Manual Dispatch"] --> Verify["git-ape-verify.yml
Verify Setup"] + + classDef plan fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91 + classDef review fill:#fde68a,stroke:#b45309,stroke-width:1px,color:#7c2d12 + classDef deploy fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d + classDef destroy fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d + classDef verify fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95 + class PR,Plan plan + class Review,Merge,Comment review + class Deploy,Test deploy + class Destroy,DestroyMerge,DestroyWF destroy + class Manual,Verify verify ``` diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index cefba61..60b2750 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -22,15 +22,19 @@ const config: Config = { projectName: 'git-ape', trailingSlash: false, - onBrokenLinks: 'warn', - onBrokenMarkdownLinks: 'warn', + onBrokenLinks: 'throw', markdown: { mermaid: true, - format: 'md', + format: 'detect', + hooks: { + onBrokenMarkdownLinks: 'throw', + }, }, themes: ['@docusaurus/theme-mermaid'], + clientModules: [require.resolve('./src/clientModules/mermaidZoom.ts')], + stylesheets: [ 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css', 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap', @@ -65,7 +69,7 @@ const config: Config = { ], themeConfig: { - image: 'img/git-ape-social-card.png', + image: 'img/docusaurus-social-card.jpg', colorMode: { defaultMode: 'dark', respectPrefersColorScheme: true, @@ -96,8 +100,8 @@ const config: Config = { position: 'left', }, { - to: '/docs/use-cases/deploy-function-app', - label: 'Use Cases', + to: '/docs/use-cases/deploy-anything', + label: 'What it does', position: 'left', }, { @@ -128,6 +132,8 @@ const config: Config = { title: 'Resources', items: [ { label: 'GitHub Repository', href: 'https://github.com/Azure/git-ape' }, + { label: 'microsoft/hve-core', href: 'https://github.com/microsoft/hve-core' }, + { label: 'microsoft/azure-skills', href: 'https://github.com/microsoft/azure-skills' }, { label: 'Azure Cloud Adoption Framework', href: 'https://learn.microsoft.com/azure/cloud-adoption-framework/' }, { label: 'License (MIT)', href: 'https://github.com/Azure/git-ape/blob/main/LICENSE' }, ], diff --git a/website/sidebars.ts b/website/sidebars.ts index a89f087..5dffaa2 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -3,6 +3,7 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; const sidebars: SidebarsConfig = { docsSidebar: [ 'intro', + 'vision', { type: 'category', label: 'Getting Started', @@ -28,12 +29,10 @@ const sidebars: SidebarsConfig = { }, { type: 'category', - label: 'Use Cases', + label: 'What Git-Ape does', collapsed: false, items: [ - 'use-cases/deploy-function-app', - 'use-cases/deploy-web-app-sql', - 'use-cases/deploy-container-app', + 'use-cases/deploy-anything', 'use-cases/cost-estimation', 'use-cases/security-analysis', 'use-cases/waf-review', @@ -50,7 +49,6 @@ const sidebars: SidebarsConfig = { label: 'Agents', collapsed: false, items: [ - 'agents/overview', {type: 'autogenerated', dirName: 'agents'}, ], }, @@ -59,7 +57,6 @@ const sidebars: SidebarsConfig = { label: 'Skills', collapsed: false, items: [ - 'skills/overview', {type: 'autogenerated', dirName: 'skills'}, ], }, @@ -67,7 +64,6 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'CI/CD Workflows', items: [ - 'workflows/overview', {type: 'autogenerated', dirName: 'workflows'}, ], }, diff --git a/website/src/clientModules/mermaidZoom.ts b/website/src/clientModules/mermaidZoom.ts new file mode 100644 index 0000000..0f46de6 --- /dev/null +++ b/website/src/clientModules/mermaidZoom.ts @@ -0,0 +1,124 @@ +/** + * Mermaid zoom client module — adds click-to-fullscreen to every rendered Mermaid + * diagram. Inspired by GitHub's Mermaid lightbox. + * + * - Browser-only (guarded by ExecutionEnvironment.canUseDOM). + * - Uses MutationObserver because Mermaid SVGs are injected asynchronously. + * - Modal closes on Escape, backdrop click, or close button. + * - Re-runs after Docusaurus client-side route transitions. + */ + +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; + +if (ExecutionEnvironment.canUseDOM) { + const CONTAINER_SELECTOR = 'div.docusaurus-mermaid-container'; + const ENHANCED_ATTR = 'data-zoom-enhanced'; + const MODAL_ID = 'mermaid-zoom-modal'; + + const ensureModal = (): HTMLDivElement => { + let modal = document.getElementById(MODAL_ID) as HTMLDivElement | null; + if (modal) return modal; + + modal = document.createElement('div'); + modal.id = MODAL_ID; + modal.setAttribute('role', 'dialog'); + modal.setAttribute('aria-modal', 'true'); + modal.setAttribute('aria-label', 'Diagram zoom view'); + modal.hidden = true; + modal.innerHTML = ` +
+
+ +
+
+ `; + document.body.appendChild(modal); + + const close = () => { + modal!.hidden = true; + document.body.style.overflow = ''; + const content = modal!.querySelector('.mermaid-zoom-content'); + if (content) content.innerHTML = ''; + }; + + modal.querySelector('.mermaid-zoom-close')?.addEventListener('click', close); + modal.querySelector('.mermaid-zoom-backdrop')?.addEventListener('click', close); + + document.addEventListener('keydown', (e) => { + if (!modal!.hidden && e.key === 'Escape') close(); + }); + + return modal; + }; + + const openZoom = (sourceSvg: SVGSVGElement) => { + const modal = ensureModal(); + const content = modal.querySelector('.mermaid-zoom-content') as HTMLDivElement; + + const clone = sourceSvg.cloneNode(true) as SVGSVGElement; + clone.removeAttribute('width'); + clone.removeAttribute('height'); + clone.style.width = '100%'; + clone.style.height = '100%'; + clone.style.maxWidth = 'none'; + clone.style.maxHeight = 'none'; + if (!clone.getAttribute('preserveAspectRatio')) { + clone.setAttribute('preserveAspectRatio', 'xMidYMid meet'); + } + + content.innerHTML = ''; + content.appendChild(clone); + modal.hidden = false; + document.body.style.overflow = 'hidden'; + }; + + const enhance = (container: HTMLDivElement) => { + if (container.getAttribute(ENHANCED_ATTR) === 'true') return; + const svg = container.querySelector('svg'); + if (!svg) return; + + container.setAttribute(ENHANCED_ATTR, 'true'); + container.setAttribute('role', 'button'); + container.setAttribute('tabindex', '0'); + container.setAttribute('aria-label', 'Click to zoom diagram'); + container.title = 'Click to zoom'; + + // Visual hint button (pure CSS via class — see custom.css) + const hint = document.createElement('span'); + hint.className = 'mermaid-zoom-hint'; + hint.setAttribute('aria-hidden', 'true'); + hint.innerHTML = '⤢'; + container.appendChild(hint); + + container.addEventListener('click', (e) => { + // Avoid hijacking text selection or link clicks within the SVG + const target = e.target as Element; + if (target?.closest('a')) return; + openZoom(svg as SVGSVGElement); + }); + container.addEventListener('keydown', (e) => { + if (e.key === 'Enter' || e.key === ' ') { + e.preventDefault(); + openZoom(svg as SVGSVGElement); + } + }); + }; + + const scan = () => { + document + .querySelectorAll(CONTAINER_SELECTOR) + .forEach((c) => enhance(c)); + }; + + // Initial scan + on DOM changes (Mermaid renders asynchronously and + // Docusaurus swaps content on client-side navigation). + const observer = new MutationObserver(() => scan()); + observer.observe(document.body, { childList: true, subtree: true }); + + // Run an initial scan when DOM is ready. + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', scan); + } else { + scan(); + } +} diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 47ea47c..367e9d4 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -562,6 +562,134 @@ blockquote::before { border-color: rgba(139, 157, 240, 0.08); } +/* --- Mermaid: ensure arrows, lines, and labels are visible in BOTH themes --- */ + +/* Light mode: edges + arrowheads use slate so they read against light fills */ +.docusaurus-mermaid-container svg .edgePath path, +.docusaurus-mermaid-container svg .flowchart-link, +.docusaurus-mermaid-container svg path.flowchart-link, +.docusaurus-mermaid-container svg .messageLine0, +.docusaurus-mermaid-container svg .messageLine1, +.docusaurus-mermaid-container svg .actor-line { + stroke: #475569 !important; + stroke-width: 1.5px !important; +} + +.docusaurus-mermaid-container svg marker path, +.docusaurus-mermaid-container svg defs marker * { + fill: #475569 !important; + stroke: #475569 !important; +} + +/* Edge labels (text on arrows) — opaque background so they read over lines */ +.docusaurus-mermaid-container svg .edgeLabel, +.docusaurus-mermaid-container svg .edgeLabel rect, +.docusaurus-mermaid-container svg .edgeLabel foreignObject div { + background-color: #ffffff !important; + color: #1e293b !important; + font-weight: 500 !important; +} +.docusaurus-mermaid-container svg .edgeLabel span, +.docusaurus-mermaid-container svg .edgeLabel p { + color: #1e293b !important; + background-color: transparent !important; +} + +/* Subgraph (cluster) — visible border + readable title */ +.docusaurus-mermaid-container svg .cluster rect { + stroke: #94a3b8 !important; + stroke-width: 1.5px !important; + fill: rgba(148, 163, 184, 0.08) !important; +} +.docusaurus-mermaid-container svg .cluster .nodeLabel, +.docusaurus-mermaid-container svg .cluster text, +.docusaurus-mermaid-container svg .cluster-label text { + fill: #1e293b !important; + color: #1e293b !important; + font-weight: 600 !important; +} + +/* Sequence diagram: actor boxes, notes, dividers */ +.docusaurus-mermaid-container svg .actor { + stroke: #1f6feb !important; + fill: #dbeafe !important; +} +.docusaurus-mermaid-container svg text.actor > tspan { + fill: #0b3d91 !important; + font-weight: 600 !important; +} +.docusaurus-mermaid-container svg .note { + stroke: #b45309 !important; + fill: #fef3c7 !important; +} +.docusaurus-mermaid-container svg .noteText, +.docusaurus-mermaid-container svg .noteText tspan { + fill: #7c2d12 !important; +} +.docusaurus-mermaid-container svg .messageText { + fill: #1e293b !important; + font-weight: 500 !important; +} +.docusaurus-mermaid-container svg .loopText, +.docusaurus-mermaid-container svg .loopText tspan, +.docusaurus-mermaid-container svg .labelText, +.docusaurus-mermaid-container svg .labelText tspan { + fill: #1e293b !important; +} + +/* State diagram bits */ +.docusaurus-mermaid-container svg .transition { + stroke: #475569 !important; + fill: none !important; +} + +/* Dark mode overrides — keep colored node fills (set by classDef) but + make connecting lines, arrowheads, edge labels and cluster borders pop. */ +[data-theme='dark'] .docusaurus-mermaid-container svg .edgePath path, +[data-theme='dark'] .docusaurus-mermaid-container svg .flowchart-link, +[data-theme='dark'] .docusaurus-mermaid-container svg path.flowchart-link, +[data-theme='dark'] .docusaurus-mermaid-container svg .messageLine0, +[data-theme='dark'] .docusaurus-mermaid-container svg .messageLine1, +[data-theme='dark'] .docusaurus-mermaid-container svg .actor-line { + stroke: #cbd5e1 !important; + stroke-width: 1.75px !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg marker path, +[data-theme='dark'] .docusaurus-mermaid-container svg defs marker * { + fill: #cbd5e1 !important; + stroke: #cbd5e1 !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg .edgeLabel, +[data-theme='dark'] .docusaurus-mermaid-container svg .edgeLabel rect, +[data-theme='dark'] .docusaurus-mermaid-container svg .edgeLabel foreignObject div { + background-color: #1e293b !important; + color: #e2e8f0 !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg .edgeLabel span, +[data-theme='dark'] .docusaurus-mermaid-container svg .edgeLabel p { + color: #e2e8f0 !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg .cluster rect { + stroke: #64748b !important; + fill: rgba(100, 116, 139, 0.12) !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg .cluster .nodeLabel, +[data-theme='dark'] .docusaurus-mermaid-container svg .cluster text, +[data-theme='dark'] .docusaurus-mermaid-container svg .cluster-label text { + fill: #e2e8f0 !important; + color: #e2e8f0 !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg .messageText, +[data-theme='dark'] .docusaurus-mermaid-container svg .loopText, +[data-theme='dark'] .docusaurus-mermaid-container svg .loopText tspan, +[data-theme='dark'] .docusaurus-mermaid-container svg .labelText, +[data-theme='dark'] .docusaurus-mermaid-container svg .labelText tspan { + fill: #e2e8f0 !important; +} +[data-theme='dark'] .docusaurus-mermaid-container svg .transition { + stroke: #cbd5e1 !important; +} + /* ========================================================================== BREADCRUMBS ========================================================================== */ @@ -697,3 +825,164 @@ div[class*='announcementBar'] a { .ga-fade-in { animation: fadeInUp 0.6s ease-out both; } + +/* ========================================================================== + MERMAID ZOOM (click-to-fullscreen) + ========================================================================== */ + +.docusaurus-mermaid-container[data-zoom-enhanced='true'] { + position: relative; + cursor: zoom-in; + transition: transform 0.15s ease, box-shadow 0.15s ease; +} + +.docusaurus-mermaid-container[data-zoom-enhanced='true']:hover { + box-shadow: var(--ga-shadow-md); +} + +.docusaurus-mermaid-container[data-zoom-enhanced='true']:focus-visible { + outline: 2px solid var(--ifm-color-primary); + outline-offset: 2px; +} + +.mermaid-zoom-hint { + position: absolute; + top: 0.5rem; + right: 0.5rem; + width: 28px; + height: 28px; + border-radius: 6px; + background: rgba(15, 20, 25, 0.6); + color: #ffffff; + display: inline-flex; + align-items: center; + justify-content: center; + font-size: 14px; + line-height: 1; + pointer-events: none; + opacity: 0; + transition: opacity 0.15s ease; +} + +.docusaurus-mermaid-container[data-zoom-enhanced='true']:hover .mermaid-zoom-hint, +.docusaurus-mermaid-container[data-zoom-enhanced='true']:focus-visible .mermaid-zoom-hint { + opacity: 1; +} + +#mermaid-zoom-modal { + position: fixed; + inset: 0; + z-index: 9999; + display: flex; + align-items: center; + justify-content: center; + padding: 2rem; +} + +#mermaid-zoom-modal[hidden] { + display: none; +} + +.mermaid-zoom-backdrop { + position: absolute; + inset: 0; + background: rgba(15, 20, 25, 0.85); + backdrop-filter: blur(4px); + cursor: zoom-out; +} + +.mermaid-zoom-stage { + position: relative; + width: 100%; + height: 100%; + max-width: 1600px; + background: #ffffff; + border-radius: var(--ga-radius); + box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5); + padding: 3rem 2rem 2rem; + overflow: hidden; + display: flex; +} + +[data-theme='dark'] .mermaid-zoom-stage { + background: #1a2332; +} + +.mermaid-zoom-content { + flex: 1; + display: flex; + align-items: center; + justify-content: center; + overflow: auto; + /* Subtle hint that scrolling is possible on small viewports */ + scroll-behavior: smooth; + -webkit-overflow-scrolling: touch; +} + +.mermaid-zoom-content svg { + /* Default: scale to fit viewport, but don't shrink below natural width. + This means wide diagrams stay readable and scroll horizontally on phones, + instead of being shrunk to an unreadable thumbnail. */ + width: auto !important; + height: auto !important; + max-width: 100%; + max-height: 100%; + min-width: min(100%, 800px); +} + +/* On small viewports (phones in either orientation), prefer letting the SVG + keep a readable size and scroll, rather than shrink to fit the short axis. */ +@media (max-width: 768px) { + .mermaid-zoom-stage { + padding: 2.5rem 0.75rem 0.75rem; + border-radius: 8px; + } + .mermaid-zoom-content svg { + /* Allow growing past the viewport so the user can scroll & read */ + max-height: none; + min-width: 600px; + } + .mermaid-zoom-close { + top: 0.25rem; + right: 0.25rem; + width: 32px; + height: 32px; + font-size: 20px; + } +} + +/* Landscape phones — ultra-short viewport, recover even more space */ +@media (max-height: 480px) { + .mermaid-zoom-stage { + padding: 2rem 0.5rem 0.5rem; + } +} + +.mermaid-zoom-close { + position: absolute; + top: 0.5rem; + right: 0.5rem; + width: 36px; + height: 36px; + border: none; + background: rgba(15, 20, 25, 0.08); + color: var(--ifm-color-content); + font-size: 24px; + line-height: 1; + cursor: pointer; + border-radius: 8px; + transition: background 0.15s ease; + z-index: 1; +} + +.mermaid-zoom-close:hover { + background: rgba(15, 20, 25, 0.15); +} + +[data-theme='dark'] .mermaid-zoom-close { + background: rgba(255, 255, 255, 0.08); +} + +[data-theme='dark'] .mermaid-zoom-close:hover { + background: rgba(255, 255, 255, 0.15); +} diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx index f3c534c..52d5b39 100644 --- a/website/src/pages/index.tsx +++ b/website/src/pages/index.tsx @@ -20,20 +20,22 @@ function HeroSection() { Deploy with GitHub Copilot - Deploy Cloud with{' '} - Git-Ape + Platform engineering for the{' '} + agentic AI era

- The intelligent multi-agent system for GitHub Copilot that handles - cloud deployments end-to-end — from requirements to production, - with security gates at every step. + Agents over modules. Intent over syntax. Evidence over audits. +

+ Git-Ape is the implementation of platform engineering for the + agentic AI era — natural-language intent in, compliant cloud + deployments out, policy enforced end-to-end.

Get Started - - Explore Agents + + Read the Manifesto
@@ -41,17 +43,51 @@ function HeroSection() { ); } +/* ========================================================================== + SECTION 1B: VIDEO INTRO + ========================================================================== */ + +function VideoSection() { + return ( +
+
+
+ + Watch the manifesto in 10 minutes + +

+ From Platform Engineering for the Agentic AI Era +

+
+