Skip to content

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.

On this page

📋 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
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:

🚀 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. That checklist owns the version checks and the saif doctor fix --self then saif doctor fix update sequence; Updating the 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.

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:
saif agent init

Expected result: The host can use Forge's MCP tools and migration skill. Follow plugin setup and scope for configuration choices, then verify the 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:
  2. Click the Copilot icon in the sidebar

  3. Switch to the Agent Chat tab (not inline chat)

  4. Select the agent model:

  5. Choose Claude Opus or Claude Sonnet for best results

  6. Opus has stronger reasoning for complex migrations; Sonnet is faster

  7. Ask the agent to run the migration workflow:

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
  • Creates a local copy in docs/migration/forge-v2-to-v3.md for progress tracking
  • Establishes a todo list from the migration task list (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:
git status
git diff
  1. Build the project:
dotnet clean
dotnet restore
dotnet build
  1. Run tests:
dotnet test
  1. Start the AppHost locally:
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
  2. Source: .azdo/azure-pipelines-auth-pr.yml

  3. Trigger: Pull requests affecting infra/auth/**

  4. {project-id}-auth — Production deployment for auth infrastructure

  5. Source: .azdo/azure-pipelines-auth.yml
  6. 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:
# All .csproj files should target net10.0
Select-String -Path "**/*.csproj" -Pattern "<TargetFramework>net10.0</TargetFramework>"
  1. Verify Aspire SDK:
# AppHost project should use Aspire.AppHost.Sdk/13.1.0
Get-Content "src/*AppHost/*.csproj" | Select-String "Aspire.AppHost.Sdk"

  1. Check folder structure:

  2. ✅ infra/api/ exists (renamed from infra/app/)

  3. ✅ infra/auth/corp/ exists (new for Entra ID)

  4. ✅ infra/auth/ext/ contains Okta configuration

  5. Confirm pipeline updates:

  6. ✅ .azdo/azure-pipelines-api.yml references azure-dotnet-api-v3.yml@templates

  7. ✅ Pipeline templates reference refs/heads/releases/v3
  8. ✅ 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.
  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:
  2. User scope (default): check the configuration files in the plugin scope table, then follow plugin verification.
  3. Project scope (--local): check <repo>/.github/copilot/settings.json.
  4. Restart VS Code to pick up the updated plugin settings
  5. In Agent Chat, ask explicitly for the migration workflow, for example: "Use the migrate-to-v3 skill to migrate this repository to Forge v3."
  6. If the agent still does not pick it up, confirm the forge plugin package is installed and review the package manifest for shipped skill names.
  7. 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
  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:

# 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 to identify missing steps.

📝 Example

Complete Example: Migrating IT-API-EXP-EXAMPLE

This example shows the complete workflow for migrating an experience API.

# 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

🚀 Next Steps

After completing the migration:

Task Guide
Configure Entra ID app roles and scopes Security Configuration
Update TypeSpec definitions for auth Security Configuration
Test authentication in local environment Create JWT for Testing APIs
Deploy to development environment Run your updated pipelines in Azure DevOps
Review breaking changes Forge 3.0 Release Notes

🤖 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.