--- title: Agent-Assisted Migration to Forge v3 description: Use Forge's migration skill and MCP tools to guide a v2 to v3 upgrade. moved_from: - guides/migration/mcp-assisted-migration.md --- # Agent-Assisted Migration to Forge v3 Forge v3 includes an AI-powered migration workflow driven by the `migrate-to-v3` Agent Skill that automates the migration process from Forge v2 to v3. The SAIF MCP (Model Context Protocol) server runs alongside it, giving Copilot access to migration docs, template metadata, and CLI help. **The challenge:** Manual migration involves dozens of file edits across .NET projects, Terraform modules, and pipeline configurationsβ€”time-consuming and error-prone. **The solution:** The `migrate-to-v3` Agent Skill gives Copilot migration knowledge, automated file discovery, and step-by-step execution guidance, reducing migration time from hours to minutes. [TOC] --- ## πŸ“‹ Overview | Aspect | Details | | ----------------- | ---------------------------------------------------------------------------------------------- | | **Goal** | Migrate a Forge v2 application to v3 using AI-assisted automation via the `migrate-to-v3` skill | | **Prerequisites** | VS Code with Copilot plus the [migration prerequisites](forge-v2-to-v3.md#prerequisites) | | **Time estimate** | ~30-45 minutes (vs 2-4 hours manual) | | **Difficulty** | Intermediate (requires understanding of git, pipelines, and basic troubleshooting) | --- ## πŸ”§ Prerequisites Before starting, ensure you have: - βœ… **VS Code installed** with the [GitHub Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - βœ… **Migration prerequisites**: the .NET SDK, SAIF CLI, and Aspire CLI checks in the [Forge v2 to v3 prerequisites](forge-v2-to-v3.md#prerequisites), with minimum versions in [Version Compatibility](../../reference/version-compatibility.md) - βœ… **Repository access**: clone permissions for your application repository - βœ… **Azure DevOps access**: permissions to create and delete pipelines --- ## πŸš€ Instructions > **Signposting:** This guide walks through (1) updating prerequisites, (2) initializing the MCP server, (3) running the AI-assisted migration, and (4) cleaning up old pipelines. ### Step 1: Update Prerequisites Complete the [Forge v2 to v3 prerequisites](forge-v2-to-v3.md#prerequisites). That checklist owns the version checks and the `saif doctor fix --self` then `saif doctor fix` update sequence; [Updating the SAIF CLI](../install-saif-cli.md#updating-saif-cli) explains why the pause and new terminal matter. **Expected result:** `dotnet --version`, `saif --version`, and `aspire --version` meet the minimums in [Version Compatibility](../../reference/version-compatibility.md). --- ### Step 2: Initialize MCP Server The MCP server connects GitHub Copilot to the Forge platform documentation and migration tools. 1. **Close all VS Code windows and terminals** so a new session picks up any `PATH` change from the Aspire CLI update 2. **Open VS Code** in your application repository root 3. **Open a new terminal** in VS Code (`Ctrl+` `) 4. **Initialize MCP configuration:** ```powershell saif agent init ``` **Expected result:** The host can use Forge's MCP tools and migration skill. Follow [plugin setup and scope](../forge-plugin.md#scope-targets) for configuration choices, then [verify the installation](../forge-plugin.md#verify-installation) before continuing. --- ### Step 3: Run AI-Assisted Migration Now you'll use Copilot's agent chat to execute the migration. 1. **Open Copilot Agent Chat** in VS Code: - Click the Copilot icon in the sidebar - Switch to the **Agent Chat** tab (not inline chat) 2. **Select the agent model:** - Choose **Claude Opus** or **Claude Sonnet** for best results - Opus has stronger reasoning for complex migrations; Sonnet is faster 3. **Ask the agent to run the migration workflow:** ```text Migrate this repository to Forge v3 using the standard migrate-to-v3 workflow. ``` You can also mention the skill by name if needed, for example: "Use the `migrate-to-v3` skill to migrate this repository to Forge v3." Once the `forge` plugin package is installed via `saif agent init`, Copilot can pick up that skill automatically from the task description and context. **What happens next:** - Copilot retrieves the [Forge v2 to v3 Migration Guide](forge-v2-to-v3.md) - Creates a local copy in `docs/migration/forge-v2-to-v3.md` for progress tracking - Establishes a todo list from the [migration task list](forge-v2-to-v3.md#using-an-ai-agent-for-migration) (Tasks 0 to 10) - Systematically executes each task: - Discovers files that need updates - Applies changes using multi-file edit operations - Runs `dotnet build` after each section - Updates progress checkboxes in the local migration doc - Marks todos complete before moving to the next task > πŸ’‘ **Tip:** The agent will use `#runSubagent` to parallelize file discovery tasks, significantly speeding up the migration. **Expected result:** Copilot progressively completes every migration task, providing status updates after each section. --- ### Step 4: Review and Test Migration After Copilot completes the migration, verify the changes. 1. **Review the changes** in git: ```powershell git status git diff ``` 2. **Build the project:** ```powershell dotnet clean dotnet restore dotnet build ``` 3. **Run tests:** ```powershell dotnet test ``` 4. **Start the AppHost locally:** ```powershell cd src/{YourApp}.AppHost aspire run ``` **Expected result:** All builds succeed, tests pass, and the Aspire dashboard loads successfully. --- ### Step 5: Update Azure DevOps Pipelines The final step is cleaning up old Okta-specific pipelines and creating the new unified auth pipelines. > ⚠️ **Important:** Complete these steps in the Azure DevOps portalβ€”they cannot be automated via the MCP server. #### Delete Legacy Pipelines Navigate to **Pipelines** in your Azure DevOps project and delete these pipelines: - `{project-id}-okta-appauth-pr` - `{project-id}-okta-appauth` - `{project-id}-okta-userauth-pr` - `{project-id}-okta-userauth` **How to delete:** 1. Go to the pipeline in Azure DevOps 2. Click the **β‹―** (More actions) menu 3. Select **Delete** 4. Confirm deletion #### Create New Auth Pipelines Create two new pipelines using the updated YAML files: 1. **`{project-id}-auth-pr`** β€” PR validation for auth infrastructure - Source: `.azdo/azure-pipelines-auth-pr.yml` - Trigger: Pull requests affecting `infra/auth/**` 2. **`{project-id}-auth`** β€” Production deployment for auth infrastructure - Source: `.azdo/azure-pipelines-auth.yml` - Trigger: Manual (same as existing pipelines) **How to create:** 1. In Azure DevOps, go to **Pipelines** β†’ **New pipeline** 2. Select **Azure Repos Git** 3. Choose your repository 4. Select **Existing Azure Pipelines YAML file** 5. Browse to the YAML file path 6. Click **Continue** β†’ **Save** (not Run) 7. Rename the pipeline to match the naming convention **Expected result:** Four legacy Okta pipelines deleted, two new unified auth pipelines created. --- ## βœ… Verify It Worked After completing all steps, verify the migration: 1. **Check version compatibility:** ```powershell # All .csproj files should target net10.0 Select-String -Path "**/*.csproj" -Pattern "net10.0" ``` 2. **Verify Aspire SDK:** ```powershell # AppHost project should use Aspire.AppHost.Sdk/13.1.0 Get-Content "src/*AppHost/*.csproj" | Select-String "Aspire.AppHost.Sdk" ``` 3. **Check folder structure:** - βœ… `infra/api/` exists (renamed from `infra/app/`) - βœ… `infra/auth/corp/` exists (new for Entra ID) - βœ… `infra/auth/ext/` contains Okta configuration 4. **Confirm pipeline updates:** - βœ… `.azdo/azure-pipelines-api.yml` references `azure-dotnet-api-v3.yml@templates` - βœ… Pipeline templates reference `refs/heads/releases/v3` - βœ… New auth pipelines exist in Azure DevOps **Success indicator:** ``` Build succeeded. 0 Warning(s) 0 Error(s) ``` --- ## 🎯 Key Takeaways After completing this guide, you will have: - βœ… Upgraded your application to .NET 10, Aspire 13, and Forge 3.0 packages - βœ… Restructured infrastructure to support dual authentication (Entra ID + Okta) - βœ… Updated pipelines to use v3 templates with `refs/heads/releases/v3` - βœ… Cleaned up legacy Okta-specific pipelines - βœ… Experienced AI-assisted migration with the SAIF MCP server --- ## πŸ” Troubleshooting ### Problem: MCP server not found **Cause:** SAIF CLI is outdated or MCP configuration wasn't initialized. **Solution:** 1. Update the SAIF CLI and its tools with the sequence in [Updating the SAIF CLI](../install-saif-cli.md#updating-saif-cli). 2. Reinitialize MCP with `saif agent init`. 3. Restart VS Code. --- ### Problem: Copilot doesn't pick up the `migrate-to-v3` skill **Cause:** The Forge plugin package is not registered, VS Code has stale plugin settings loaded, or the request did not clearly describe the migration task. **Solution:** 1. Verify the Forge Agent Plugins are registered: - **User scope (default):** check the configuration files in the [plugin scope table](../forge-plugin.md#scope-targets), then follow [plugin verification](../forge-plugin.md#verify-installation). - **Project scope (`--local`):** check `/.github/copilot/settings.json`. 2. Restart VS Code to pick up the updated plugin settings 3. In Agent Chat, ask explicitly for the migration workflow, for example: "Use the `migrate-to-v3` skill to migrate this repository to Forge v3." 4. If the agent still does not pick it up, confirm the `forge` plugin package is installed and review the [package manifest](https://github.com/saif-corp/forge/blob/main/.github/plugins/skill-packages.json) for shipped skill names. 5. If plugin registration still looks wrong, run `saif agent mcp` manually and check for errors --- ### Problem: Migration stops partway through **Cause:** Copilot encountered an unexpected file structure or build error. **Solution:** 1. Check the Copilot chat for error messages 2. Review the last completed todo item 3. Manually complete the failed step using the [manual migration guide](forge-v2-to-v3.md) 4. Ask Copilot to resume from the next task: "Continue with the next migration task" --- ### Problem: Build fails after migration **Cause:** Package restore issue or stale build artifacts. **Solution:** ```powershell # Clear NuGet cache and rebuild dotnet nuget locals all --clear dotnet clean dotnet restore dotnet build ``` If errors persist, compare your changes to the [manual migration guide](forge-v2-to-v3.md) to identify missing steps. --- ## πŸ“ Example ### Complete Example: Migrating IT-API-EXP-EXAMPLE This example shows the complete workflow for migrating an experience API. ```powershell # 1. Verify prerequisites against Version Compatibility dotnet --version saif --version aspire --version # 2. Close all terminals and VS Code windows # 3. Reopen VS Code in repository root cd C:\repos\it-api-exp-example code . # 4. Initialize MCP in VS Code terminal saif agent init # 5. Open Copilot Agent Chat # - Click Copilot icon β†’ Agent Chat tab # - Select Claude Opus model # - Ask: "Migrate this repository to Forge v3 using the standard migrate-to-v3 workflow." # 6. Monitor progress # Copilot reports each task in the migration task list as it completes, # for example: βœ… Task 0: Baseline Build complete # 7. Review changes git status git diff # 8. Test locally dotnet build dotnet test cd src/Example.AppHost aspire run # 9. Update Azure DevOps pipelines # - Delete: it-api-exp-example-okta-appauth, it-api-exp-example-okta-appauth-pr # - Delete: it-api-exp-example-okta-userauth, it-api-exp-example-okta-userauth-pr # - Create: it-api-exp-example-auth-pr (from .azdo/azure-pipelines-auth-pr.yml) # - Create: it-api-exp-example-auth (from .azdo/azure-pipelines-auth.yml) # 10. Commit and create PR git checkout -b migrate-to-forge-v3 git add . git commit -m "Migrate to Forge v3.0" git push origin migrate-to-forge-v3 ``` **Result:** - Migration completed in ~35 minutes - All tests passing - PR ready for review with automated changes --- ## πŸ“š Related Documentation - [Forge v2 to v3 Migration Guide](forge-v2-to-v3.md) - Full manual migration steps - [Version Compatibility Matrix](../../reference/version-compatibility.md) - Supported versions for Forge 3.0 - [SAIF CLI Reference](../../reference/dotnet/SAIF.Platform.CLI/commands.md) - MCP commands and capabilities --- ## πŸš€ Next Steps After completing the migration: | Task | Guide | | ---------------------------------------- | --------------------------------------------------------------------------------- | | Configure Entra ID app roles and scopes | [Security Configuration](../../build/identity/index.md) | | Update TypeSpec definitions for auth | [Security Configuration](../../build/identity/index.md) | | Test authentication in local environment | [Create JWT for Testing APIs](../../build/identity/testing/create-jwt-for-testing-apis.md) | | Deploy to development environment | Run your updated pipelines in Azure DevOps | | Review breaking changes | [Forge 3.0 Release Notes](../../release-notes/3.0.0.md) | --- ## πŸ€– About the SAIF MCP Server The SAIF MCP (Model Context Protocol) server is a built-in feature of the SAIF CLI that provides AI assistants like GitHub Copilot with direct access to: - **Forge documentation** β€” Migration guides, how-tos, and reference material - **Template information** β€” Complete template metadata and parameter descriptions - **CLI commands** β€” Searchable command help and examples Agent Skills are a separate, related piece: they ship in the `forge` and `forge-planning` Agent Plugins packages (not the MCP server itself) and provide the shipped workflows and domain guidance the model can invoke from task context. **How it works:** 1. `saif agent init` registers the shared Forge MCP server plus the Forge Agent Plugins packages (skills) β€” by default machine-wide via `~/.copilot/settings.json`; pass `--local` to also write repo-scoped plugin settings into `.github/copilot/settings.json` 2. The MCP server runs locally and connects to GitHub Copilot via VS Code 3. Copilot can use the shipped Forge MCP tools directly, and can invoke Agent Skills installed by the same `saif agent init` call 4. The server retrieves documentation from the live Forge docs site and caches it locally **Agent Skills used in this guide:** - `migrate-to-v3` β€” Standard Forge v2 to v3 migration workflow orchestration - `saif-cli` β€” SAIF CLI and Forge MCP guidance for `saif agent init`, command discovery, and migration-doc lookup - `troubleshoot` β€” Diagnostic guidance if the migration hits version drift, build issues, or other Forge-specific blockers For the shipped skill inventory, see the [package manifest](https://github.com/saif-corp/forge/blob/main/.github/plugins/skill-packages.json).