Skip to main content

Pre-move and post-move guide

Last updated on

Moving a project from one organization to another requires careful planning to maintain service continuity and prevent broken dependencies. This checklist helps you identify what might break during the move so you can plan accordingly.

What will you learn in this topic?​

By the end of this topic, you will be able to:

  • Identify organization-level dependencies that will break during a project move.
  • Validate pipelines, connectors, secrets, and access controls before the move.
  • Understand important considerations and limitations for project moves.

Before you begin​

Before you move a project between organizations, make sure you have:

  • Account Admin or Organization Admin permissions: You need these permissions to move projects and set up access controls. Go to RBAC in Harness to review roles.
  • Access to both organizations: You need permissions in both the source and destination organizations to check what resources exist and recreate them where needed.
  • Inventory of organization-level resources: Make a list of all connectors, secrets, templates, policies, and access controls your project uses at the organization level.
  • No running pipelines: Make sure all pipelines in the project have finished running before you start the move.

Check dependencies before moving a project​

Before you move a project, review these items for organization-level dependencies that will break after the move.

This list covers the most common issues. Your project might have additional organization-level dependencies not listed here.

CategoryDependencyImpact After Move
PipelinesOrganization-level connectorsPipelines that use connectors from the organization level will break after the move.
Organization-level secretsIf your pipelines use secrets scoped at the organization level, those secrets will no longer be accessible in the new organization.
Organization-level templatesTemplates used to build pipelines might be scoped at the organization level. Make sure these templates exist in the destination organization, or your pipelines will fail to render or execute.
Hardcoded organization identifiersYAML files might include hardcoded references such as orgIdentifier. These will still point to the old organization, but this will not affect pipeline execution.
Pipeline chainingIf you use pipeline chaining, moving the child pipeline will break the chain. Go to Pipeline chaining for details.
Running pipelinesAny pipelines currently running will fail when the move starts. Finish all pipeline runs before you begin the move.
NotificationsOrganization-level channelsNotification rules that use channels from the organization level will break after the move.
User group notificationsEmail notifications that use organization-level user groups will stop working.
Git ExperienceGit file pathsGit file paths will become outdated after the move because they still point to the old organization in URLs and navigation links.
ServicesManifest and artifact sourcesServices that use manifest sources and artifact sources with organization-level connectors will break.
EnvironmentsConfiguration filesEnvironment configurations, application settings, manifest sources, and connection strings that reference organization-level resources will become unavailable.
Service overrides and infrastructureService overrides, infrastructure definitions, and GitOps clusters that reference organization-level resources will break.
Monitored servicesOrganization-level resourcesServices or environments that reference organization-level resources will become inaccessible after the move.
WebhooksConnectors and secretsGit connectors, generic webhooks, and Slack webhooks that use organization-level connectors or secrets will break.
Custom webhook triggersCustom webhook triggers will stop working.
Access controlOrganization-level RBAC componentsUser groups and service accounts inherited from the organization level do not move with the project. You will need to recreate them in the destination organization if your project still needs them. Roles reused from the organization level also stay behind. Go to Create groups by inheritance and Hierarchical support for service accounts for details.
Temporary access restrictionsProject-level access controls (users, service accounts, user groups, role bindings, resource groups, and roles) move with the project, but this happens in the background. Users might temporarily lose access during the move.
Audit logsHistorical logsAudit logs from before the move stay in the source organization. They do not transfer with the project.
Broken linksLinks in old audit logs that point to the project will break because they still reference the old organization.
New logsAfter the move, new audit logs for the project will appear in the destination organization.
Policy managementProject-level policiesProject-level policies and policy sets move with the project to the destination organization.
Organization-level policiesOrganization-level policies referenced by the project will no longer be accessible. You might need to recreate these policies in the destination organization or update your policy sets to use policies that exist there.
Policy set referencesPolicy sets that reference organization-level policies will break and need to be updated to use policies from the destination organization.
TerraformState file inconsistenciesTerraform state and configuration files that reference the project might become inconsistent after the move.
Provider identifiersResources created with the Harness Terraform Provider include organization and project identifiers. After the move, these identifiers will not match the new organization.
note
  • Broken links - Links that reference the source organization (in pipelines, webhooks, audit logs, bookmarks, or URLs) will stop working after the move. Harness does not redirect these links.
  • Duplicate project identifiers - You cannot move a project if another project with the same identifier already exists in the destination organization. For example, if you are moving Project P from organization O1 to O2, and O2 already has a project named P, the move will fail.
  • Manual Terraform updates - Harness does not automatically update Terraform configuration or state files after a move. You need to manually update your Terraform resources and state files.

After moving a project from one organization to another, you need to fix broken references and recreate organization-level resources in the destination organization. This guide walks you through the remediation steps.

What will you learn in this topic?​

By the end of this topic, you will be able to:

Before you begin​

Before you start fixing issues after a project move, make sure:

  • The project move completed successfully: Verify the project appears in the destination organization.
  • You have appropriate permissions: You need permissions in the destination organization to create connectors, secrets, templates, and configure access controls. Go to RBAC in Harness to review roles.
  • You have the pre-move inventory: Reference the list of organization-level resources you documented before the move. Go to Pre-move validation checklist for details.

Fix issues after moving a project​

After the move completes, review the following resources and make any necessary updates. This list covers common issues, but you might need to take additional steps depending on your project setup.

Pipelines​

  • Test pipelines: Run all pipelines to find broken references.
  • Update references: Point pipeline references to connectors and secrets in the destination organization.
  • Recreate templates: Recreate any organization-level templates in the destination organization.
  • Update identifiers: Update YAML files that have hardcoded orgIdentifier values to match the new organization.
  • Fix pipeline chaining: Update pipeline chaining references if you also moved the child pipelines.
Pipelines using Terraform might fail

If a pipeline that uses Terraform fails after the move, re-run it. Failures can happen if the pipeline was running when the move started and it cannot access files from the Terraform Plan step. These files include the inherited plan, exported JSON plan, and exported human-readable plan. Go to Review Terraform Plan and Apply steps, Export JSON representation of Terraform Plan, and Export human-readable representation of Terraform Plan for details.

The same issue affects Terragrunt pipelines, except Terragrunt does not use the exported JSON or human-readable plans.

Connectors and secrets​

Recreate organization-level connectors and secrets in the destination organization if your project needs them.

Services and environments​

  • Update service resources: Update service manifest sources and artifact sources that reference connectors from the old organization.
  • Update environment configuration: Update environment configuration files and connection strings as needed.
  • Recreate overrides and infrastructure: Recreate service overrides and infrastructure definitions that referenced organization-level resources.

Notifications and webhooks​

  • Update notification rules: Update notification rules that reference channels from the old organization.
  • Recreate webhook configurations: Recreate webhook configurations using connectors and secrets from the destination organization.
  • Test custom triggers: Test and update custom webhook triggers.

Access control​

Create organization-level RBAC components and assign role bindings to make sure users and service accounts still have the access they need.

Monitored services​

Update monitored services that still reference resources from the old organization.

Policy management​

  • Review policy sets: Check all policy sets in the moved project for references to organization-level policies.
  • Recreate policies: Recreate organization-level policies in the destination organization if your policy sets need them.
  • Update references: Update policy sets to reference policies from the destination organization.
  • Verify policy evaluations: Test that all policy evaluations still work correctly.

Update bookmarks and URLs​

Update any bookmarks, saved URLs, and runbooks that reference the old organization path.