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, .NET 10 SDK, SAIF CLI 3.0+, Aspire 13.1+
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
  • ✅ .NET 10 SDK — Download from dotnet.microsoft.com/download/dotnet/10.0
  • ✅ SAIF CLI 3.0+ — Verify with saif --version
  • ✅ Aspire 13.1+ — Verify with aspire --version
  • ✅ Repository access — Clone permissions for your application repository
  • ✅ Azure DevOps access — Permissions to create/delete pipelines

💡 Tip: If your SAIF CLI or Aspire versions are outdated, run saif doctor fix --self to update the CLI, then saif doctor fix to update Aspire and other tools, with a 20-second pause between runs to ensure all updates complete.

🚀 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

Before starting the migration, ensure all tools are up to date.

# Verify current versions
dotnet --version  # Should be 10.0.x
saif --version    # Should be 3.0.x
aspire --version  # Should be 13.1.x

# If outdated, update SAIF CLI and Aspire
saif doctor fix --self
Start-Sleep -Seconds 20
saif doctor fix
Start-Sleep -Seconds 20

# Verify updates
saif --version
aspire --version

Expected result: All version checks pass with minimum required versions.

⚠️ Important: Close all open terminals and VS Code instances after updating to ensure the new Aspire CLI path is loaded.

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 to pick up the updated Aspire path
  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: By default this registers Forge Agent Plugins in your user profile (machine-wide) — no files are written into your repository. Pass saif agent init --local instead if you specifically want repo-scoped plugin settings written into .github/copilot/settings.json (shared with collaborators if committed).

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 with 10 migration tasks
  • 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 all 10 migration tasks, 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:

# Update SAIF CLI
saif doctor fix --self
Start-Sleep -Seconds 20
saif doctor fix

# Reinitialize MCP
saif agent init

# 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 ~/.copilot/settings.json (used by GitHub Copilot CLI and the GitHub Copilot app), and if you're verifying VS Code marketplace discovery check the user profile settings.json path in the scope targets table. You can also re-run saif agent init and confirm it reports "already up to date".
  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 Agent Skills inventory for the shipped skill names and summaries
  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
dotnet --version   # 10.0.101
saif --version     # 3.0.5
aspire --version   # 13.1.0

# 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 outputs:
# ✅ Task 0: Baseline Build complete
# ✅ Task 1: .NET 10 SDK verified
# ✅ Task 2: SAIF Tools updated
# ✅ Task 3: dotnet-outdated-tool installed
# ✅ Task 4: .NET 10 Upgrade complete
# ✅ Task 5: Package Updates complete
# ✅ Task 6: AppHost Changes complete
# ✅ Task 7: Infrastructure Restructuring complete
# ✅ Task 8: Terraform Variable Casing complete
# ✅ Task 9: Entra ID Migration complete
# ✅ Task 10: Pipeline Updates 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 full shipped skill inventory, see Agent Skills.