From a2357831b703c4a3e975abe7520166236678af07 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 19 May 2026 00:23:16 +0000
Subject: [PATCH] docs: document GCP Workload Identity Federation migration

---
 cloud-accounts/connecting-a-cloud-account.mdx | 29 +++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/cloud-accounts/connecting-a-cloud-account.mdx b/cloud-accounts/connecting-a-cloud-account.mdx
index f791a47..e1d85eb 100644
--- a/cloud-accounts/connecting-a-cloud-account.mdx
+++ b/cloud-accounts/connecting-a-cloud-account.mdx
@@ -147,6 +147,35 @@ Before Porter can create a cluster, you need to grant it access to your cloud ac
 
     Porter verifies the credentials and automatically provisions all required permissions and APIs. This takes about a minute.
 
+    ## Migrating to Workload Identity Federation
+
+    If your project has Workload Identity Federation (WIF) enabled, you can migrate an existing service-account JSON connection to WIF without redeploying your clusters. WIF replaces long-lived service-account keys with short-lived federated tokens.
+
+    <Info>
+    Workload Identity Federation for GCP is currently rolled out per project. If you don't see the **Migrate to Workload Identity Federation** button described below, reach out through the support widget to have it enabled.
+    </Info>
+
+    To migrate:
+
+    <Steps>
+      <Step title="Open the cloud account">
+        In Porter, navigate to **Integrations** → **GCP** and open the cloud account you want to migrate.
+      </Step>
+      <Step title="Start the migration">
+        Click **Migrate to Workload Identity Federation**. Porter generates a one-time setup command and a Cloud Shell deeplink.
+      </Step>
+      <Step title="Run the bootstrap in Cloud Shell">
+        Click the Cloud Shell link, paste the setup command, and run it. The command provisions the Workload Identity Pool, provider, and service account binding in your GCP project via Terraform.
+
+        Your existing service-account JSON credential keeps authenticating your clusters throughout this step — there is no downtime during migration.
+      </Step>
+      <Step title="Wait for verification">
+        Porter waits for the bootstrap callback and then cuts the cloud account over to the federated identity. The dialog closes automatically once verification succeeds.
+      </Step>
+    </Steps>
+
+    After migration, you can safely delete the original service-account key from your GCP project.
+
     ## Revoking Access
 
     To revoke Porter's access: