diff --git a/docs/platform/organizations-and-projects/create-an-organization.md b/docs/platform/organizations-and-projects/create-an-organization.md index b0ddeb16908..fb2e583be28 100644 --- a/docs/platform/organizations-and-projects/create-an-organization.md +++ b/docs/platform/organizations-and-projects/create-an-organization.md @@ -1,7 +1,7 @@ --- -title: Create organizations and projects +title: Create Organizations and Projects description: Harness Organizations (Orgs) allow you to group projects that share the same goal. For example, all projects for a business unit or division. A Harness Project is a group of Harness modules and their… -sidebar_position: 20 +sidebar_position: 2 helpdocs_topic_id: 36fw2u92i4 helpdocs_category_id: 3trbf8xckk helpdocs_is_private: false diff --git a/docs/platform/organizations-and-projects/move-projects/_category_.json b/docs/platform/organizations-and-projects/move-projects/_category_.json new file mode 100644 index 00000000000..1317e15fa01 --- /dev/null +++ b/docs/platform/organizations-and-projects/move-projects/_category_.json @@ -0,0 +1,14 @@ +{ + "label": "Move a project", + "position": "3", + "collapsible": "true", + "collapsed": "true", + "className": "red", + "link": { + "type": "generated-index", + "title": "Move a project" + }, + "customProps": { + "helpdocs_category_id": "3trbf8xckk" + } +} \ No newline at end of file diff --git a/docs/platform/organizations-and-projects/move-projects/move-projects-across-organization.md b/docs/platform/organizations-and-projects/move-projects/move-projects-across-organization.md new file mode 100644 index 00000000000..c924d1b44e6 --- /dev/null +++ b/docs/platform/organizations-and-projects/move-projects/move-projects-across-organization.md @@ -0,0 +1,60 @@ +--- +title: Move a project across organizations +description: Step-by-step guide to move a project across organizations. +sidebar_label: Steps to move a project +sidebar_position: 3 +tags: + - organizations + - projects + - project-movement + - step-by-step + - tutorial + - admin +keywords: + - move project +--- + +:::note Feature availability +This feature requires the `PL_PROJECT_MOVEMENT_ENABLED` feature flag. Contact [Harness support](mailto:support@harness.io) to enable it. +::: + +This document provides a step-by-step guide to migrate projects from one organization to another, including prerequisites, permissions, and detailed migration procedures. + +## Prerequisites + +- Move Project permission on the source project +- Create Project permission in the destination organization + +## Steps to move a project + +### Step 1: Navigate and access the move option + +From the **Projects listing**: +1. Navigate to **Projects** at account or organization level +2. Click the **⋮** menu next to your project +3. Select **Move Project** + +From the **Project overview page**: +1. Open your project +2. Click the **⋮** menu in the top right +3. Select **Move Project** + +### Step 2: Select destination organization + +1. In the Move Project modal, review the warning about potential configuration impacts +2. Choose your destination organization from the dropdown (only organizations where you have Create Project permission appear) + + + +3. Click **Move Project** to start the move process + +### Step 3: Confirm Move + +1. Review the confirmation dialog showing potential impacts +2. Type the **Project name** to confirm + + + +3. Click **Confirm Move** + +Once the move completes, you'll be redirected to the project in its new organization. Verify that pipelines and deployments function as expected. diff --git a/docs/platform/organizations-and-projects/move-projects/overview.md b/docs/platform/organizations-and-projects/move-projects/overview.md new file mode 100644 index 00000000000..564a581fca1 --- /dev/null +++ b/docs/platform/organizations-and-projects/move-projects/overview.md @@ -0,0 +1,59 @@ +--- + title: Move a project + description: Overview of moving a project between organizations, including prerequisites, Supported modules and how to request or perform a move. + sidebar_label: Overview + sidebar_position: 1 + tags: + - organizations + - projects + - move project + keywords: + - move projects + - move project between organizations + - transfer project + - organization restructure +--- + +:::note Feature availability +This feature requires the `PL_PROJECT_MOVEMENT_ENABLED` feature flag. Contact [Harness support](mailto:support@harness.io) to enable it. +::: + +This feature allows you to transfer a project from one organization to another within your Harness account. It can be used when a project needs to be moved to a different organization, such as during ownership transfers. + +## What happens when you move a project + +1. **Entities are moved**: [Supported entities](#supported-modules), such as pipelines, services, environments, and monitored services, are carried over with the project to the destination organization. + +2. **Organization-scoped resources need reconfiguration**: Resources scoped at the source organization level become inaccessible after the move. You must recreate connectors, secrets, templates, webhooks, and notifications in the destination organization, then update any project references to point to these new resources. References to account-level or project-level entities remain intact. + +3. **Access control requires reconfiguration**: Organization-level RBAC policies, governance rules, and security policies do not transfer and must be recreated in the destination organization. All Project-level access control components including role bindings, resource groups, and roles are migrated asynchronously. While the move is in progress, users may experience temporary access restrictions during the move process. + +4. **Audit logs**: Existing audit logs remain in the source organization and are not moved with the project. Any links in these logs pointing to the moved project or older organization will become inaccessible. + +For detailed pre-move validation and post-move remediation steps, see the [Move a Project guide](./pre-move-and-post-move-guide.md). + +## Prerequisites + +To move a project across organizations, you need the following permissions: + +- Move permission for the project that you want to move. +- Create project permission in the destination organization. + +## Supported modules + +* [Platform](/docs/platform/platform-whats-supported) +* [Continuous Delivery and GitOps](/docs/continuous-delivery/cd-integrations) +* [Continuous Integration](/docs/continuous-integration/use-ci/set-up-build-infrastructure/which-build-infrastructure-is-right-for-me/#feature-compatibility-matrix) +* [Internal Developer Portal](/docs/internal-developer-portal/whats-supported) +* [Security Test Orchestration](/docs/security-testing-orchestration/whats-supported/sto-deployments) +* [Supply Chain Security](/docs/software-supply-chain-assurance/ssca-supported) +* [Code Repository](/docs/code-repository/code-supported) +* [Database DevOps](/docs/database-devops/dbdevops-supported-platforms.md) + +:::note Unsupported [Entities](/docs/platform/references/harness-entity-reference) + In the Continuous Delivery and GitOps module, the following entities are not supported: + - [Policy as Code (OPA)](/docs/category/policy-as-code) + - [GitOps](/docs/category/get-started-with-gitops) + - [Continuous Verification](/docs/continuous-delivery/verify/verify-deployments-with-the-verify-step) +::: + diff --git a/docs/platform/organizations-and-projects/move-projects/pre-move-and-post-move-guide.md b/docs/platform/organizations-and-projects/move-projects/pre-move-and-post-move-guide.md new file mode 100644 index 00000000000..f166ba0a900 --- /dev/null +++ b/docs/platform/organizations-and-projects/move-projects/pre-move-and-post-move-guide.md @@ -0,0 +1,78 @@ +--- +title: Pre-move and post-move guide +description: Pre-move and post-move guide ensures successful project movement across organizations. +sidebar_label: Pre-move and post-move guide +sidebar_position: 2 +tags: + - project-movement + - checklist + - validation +keywords: + - project move checklist + - pre-move validation + - post-move Remediation +--- + +This guide highlights key pointers to be aware of before moving a project and what may be required afterward. + +## Pre-move validation + +Before moving a project, check the following items for organization-level dependencies that may break after the move: + +:::note +This list covers common issues but is not exhaustive. Additional organization-level dependencies may exist in your project. +::: + +1. Pipelines: + - Pipelines that refer organization-level connectors will break after the move. + - Secrets used in pipelines may be scoped at the organization level. After moving to a destination organization, these secrets might become unavailable. + - Templates used to build pipelines may be scoped at the organization level. Review and make these templates available in the destination organization; otherwise, pipelines may fail to render or execute. + - YAML entities may use fully qualified identifiers, such as `orgIdentifier`, that reference the source organization. These identifiers will not be updated with destination organization identifier. + - [Pipeline chaining](/docs/platform/pipelines/pipeline-chaining) will fail if the child pipeline’s project is moved. + - Any pipelines running in the project will fail when the move operation begins. Ensure all pipeline executions are completed before initiating the project movement. + +2. Notifications: + - If a notification rule uses a channel from the source organization, the reference will break. + - Email notification channels using organization-level user groups will stop working. + +3. Services: + - Project-level services like manifest sources and artifact sources referencing organization-level connectors will break. + +4. Environments: + - Environment configuration files, application settings, manifest sources, or connection strings referencing organization-level resources will become unavailable. + - Service overrides, infrastructure definitions, or GitOps clusters referencing organization-level resources will break. + +5. Monitored Services: + - Services or environments referencing organization-level resources will become inaccessible. + +6. Webhooks: + - Git connectors, generic webhooks, or Slack webhooks using connectors or secrets referencing organization-level resources will break. + - Custom webhook triggers will be no longer functional. + +7. Access control: + - Organization-level RBAC policies do not transfer when a project is moved and and must be recreated in the destination organization to maintain proper access controls. + - When a project move is initiated, all project-level access control components including role bindings, resource groups, and roles are migrated asynchronously. While the move is in progress, users may experience temporary access restrictions during the move process. + - Account-level resource groups with resource scope that includes the specificed project are moved across organizations, it will be automatically updated to reflect the new organization scope. + +8. Audit logs: + - Existing audit logs remain in the source organization and are not moved with the project. Any links in these logs pointing to the moved project or older organization will become inaccessible. + + +:::note Important note +- Links referencing the source organization—such as those in pipelines, webhooks, or audit logs—may stop working after a project is moved. Bookmarks or URLs with account, organization, or project identifiers are not redirected and will become outdated. +- The project movement will not be allowed if a project with the same identifier already exists in the destination organization. + + For example, if Project P is being moved from organization O1 to O2, and organization B already has a project with the same identifier (i.e., Project P), the project movement will not be allowed. +::: + +## Post-move remediation + +After a project is moved, the following tips can help you identify and fix broken references. Note that this list is not exhaustive and additional actions might be needed depending on your project setup. + +- Review pipeline failures for clear, actionable errors to resolve issues. +- Recreate organization-level connectors and secrets in the destination organization, if required. +- Update notification channels to use destination organization resources. +- Verify and update RBAC policies. + + + diff --git a/docs/platform/organizations-and-projects/projects-and-organizations.md b/docs/platform/organizations-and-projects/projects-and-organizations.md index 7d27a48f6e4..a583ae034e0 100644 --- a/docs/platform/organizations-and-projects/projects-and-organizations.md +++ b/docs/platform/organizations-and-projects/projects-and-organizations.md @@ -1,7 +1,8 @@ --- title: Organizations and projects overview description: This topic explains Organizations and Projects in Harness. In this topic -- Before you begin. Visual Summary. What is an Organization?. What is a Project?. What is a Product Module?. Resources Across S… -sidebar_position: 10 +sidebar_position: 1 +sidebar_label: Overview helpdocs_topic_id: 7fibxie636 helpdocs_category_id: sy6sod35zi helpdocs_is_private: false diff --git a/docs/platform/organizations-and-projects/static/confirm-project-move.png b/docs/platform/organizations-and-projects/static/confirm-project-move.png new file mode 100644 index 00000000000..eeb2d4eec58 Binary files /dev/null and b/docs/platform/organizations-and-projects/static/confirm-project-move.png differ diff --git a/docs/platform/organizations-and-projects/static/move-project-modal.png b/docs/platform/organizations-and-projects/static/move-project-modal.png new file mode 100644 index 00000000000..eb2efdb97ef Binary files /dev/null and b/docs/platform/organizations-and-projects/static/move-project-modal.png differ