Document organization deletion feature (#9475)

yaningo · rosieyohannan · web-flow · commit 1e062cca70ca · 2025-08-19T00:36:41.000+02:00
* Adding new page with instructions to delete organizations and projects

* Adding navigation item pointing to new page

* Adjusting layout

* Removing project deletion content and linking to new location

* Small fixes

* Turning sentence into caution block

* Changing header alignment

* Rewording

* Adding warning

* Modifying some text

* Adding note and link to 'Stop building' page

* Adding notes for BB Data Center

* Adding actions and roles to permission matrix

* Implementing review suggestions

---------

Co-authored-by: Rosie Yohannan &lt;rosie@circleci.com&gt;
diff --git a/docs/guides/modules/ROOT/nav.adoc b/docs/guides/modules/ROOT/nav.adoc
@@ -248,6 +248,7 @@
 *** xref:security:rotate-project-ssh-keys.adoc[Rotate project SSH keys]
 *** xref:security:stop-building-a-project-on-circleci.adoc[Stop building a project on CircleCI]
 *** xref:security:rename-organizations-and-repositories.adoc[Rename organizations and repositories]
+*** xref:security:delete-organizations-and-projects.adoc[Delete organizations and projects]
 
 * Manage config policies
 ** xref:config-policies:config-policy-management-overview.adoc[Config policy management overview]
diff --git a/docs/guides/modules/permissions-authentication/pages/roles-and-permissions-overview.adoc b/docs/guides/modules/permissions-authentication/pages/roles-and-permissions-overview.adoc
@@ -20,7 +20,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Organization*
 ^| *Admin*
@@ -101,12 +101,22 @@ The table below shows the permissions associated with each CircleCI organization
 ^| [.circle-green]#**Yes**#
 ^| [.circle-red]#**No**#
 ^| [.circle-red]#**No**#
+
+| Rename org
+^| [.circle-green]#**Yes**#
+^| [.circle-red]#**No**#
+^| [.circle-red]#**No**#
+
+| Delete org
+^| [.circle-green]#**Yes**#
+^| [.circle-red]#**No**#
+^| [.circle-red]#**No**#
 |===
 
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Insights*
 ^| *Admin*
@@ -122,7 +132,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Runner*
 ^| *Admin*
@@ -143,7 +153,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Projects*
 ^| *Admin*
@@ -169,7 +179,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Contexts*
 ^| *Admin*
@@ -200,7 +210,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Orbs*
 ^| *Admin*
@@ -231,7 +241,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Webhooks*
 ^| *Admin*
@@ -262,7 +272,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 | *Schedule*
 ^| *Admin*
@@ -283,7 +293,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 |*Triggers*
 ^| *Admin*
@@ -309,7 +319,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 |*Pipelines*
 ^| *Admin*
@@ -330,7 +340,7 @@ The table below shows the permissions associated with each CircleCI organization
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| ORGANIZATION ROLES
+3+^| ORGANIZATION ROLES
 
 |*Releases*
 ^| *Admin*
@@ -387,7 +397,7 @@ The table below shows the permissions associated with each CircleCI project role
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Projects*
 ^| *Admin*
@@ -413,12 +423,17 @@ The table below shows the permissions associated with each CircleCI project role
 ^| [.circle-green]#**Yes**#
 ^| [.circle-red]#**No**#
 ^| [.circle-red]#**No**#
+
+| Delete project
+^| [.circle-green]#**Yes**#
+^| [.circle-red]#**No**#
+^| [.circle-red]#**No**#
 |===
 
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Webhooks*
 ^| *Admin*
@@ -439,7 +454,7 @@ The table below shows the permissions associated with each CircleCI project role
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Schedule*
 ^| *Admin*
@@ -460,7 +475,7 @@ The table below shows the permissions associated with each CircleCI project role
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Triggers*
 ^| *Admin*
@@ -486,7 +501,7 @@ The table below shows the permissions associated with each CircleCI project role
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Contexts*
 ^| *Admin*
@@ -518,7 +533,7 @@ The table below shows the permissions associated with each CircleCI project role
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Pipelines*
 ^| *Admin*
@@ -539,7 +554,7 @@ The table below shows the permissions associated with each CircleCI project role
 [cols=4*, options="header"]
 |===
 | ACTIONS
-3+| PROJECT ROLES
+3+^| PROJECT ROLES
 
 | *Releases*
 ^| *Admin*
diff --git a/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc b/docs/guides/modules/security/pages/delete-organizations-and-projects.adoc
@@ -0,0 +1,119 @@
+= Delete organizations and projects
+:page-platform: Cloud
+:page-description: Learn how to delete organizations and projects in CircleCI.
+:experimental:
+
+This page details everything you need to know about deleting organizations and projects connected to CircleCI.
+
+If you only want to stop builds for a project and keep the complete build history, see the xref:security:stop-building-a-project-on-circleci.adoc[Stop building a project on CircleCI] page.
+
+[cols="1,^1,^1,2", options="header"]
+|===
+| VCS integration | Delete organization | Delete project | Notes
+
+| GitHub App
+| [.circle-green]#Yes#
+| [.circle-green]#Yes#
+| The organization will remain visible for several hours before disappearing.
+
+| GitLab
+| [.circle-green]#Yes#
+| [.circle-green]#Yes#
+| The organization will remain visible for several hours before disappearing.
+
+| Bitbucket Data Center
+| [.circle-green]#Yes#
+| [.circle-green]#Yes#
+| The organization will remain visible for several hours before disappearing.
+
+| GitHub OAuth app
+| [.circle-green]#Yes#
+| [.circle-green]#Yes#
+| Deleting the organization removes all content from the organization. The organization will remain visible but without data underneath.
+
+| Bitbucket Cloud
+| [.circle-green]#Yes#
+| [.circle-green]#Yes#
+| Deleting the organization removes all content from the organization. The organization will remain visible but without data underneath.
+
+|===
+
+
+[#delete-an-organization]
+== Delete an organization
+
+[NOTE]
+====
+You can only delete an organization when both the below conditions are met:
+
+- The organization is on a Free Plan.
+- The user performing the action has an admin role in the organization.
+====
+You can delete your organization from the CircleCI web app or via the CircleCI API:
+
+CAUTION: This action will permanently delete the organization for you and all organization members.
+
+[tabs]
+====
+CircleCI web app::
++
+--
+. In the link:https://app.circleci.com[CircleCI web app], select your org from the org cards on your user homepage.
+. Select **Organization Settings** in the sidebar.
+. Scroll to the bottom of the Overview page and select btn:[Delete Organization].
+. Confirm your choice by typing the organization name and selecting btn:[Permanently Delete Organization] in the popup.
+--
+API::
++
+--
+. Set up your API authentication. Steps are available in the xref:toolkit:api-developers-guide.adoc#add-an-api-token[API developers guide].
+. You can use the link:https://circleci.com/docs/api/v2/#tag/Organization/operation/deleteOrganization[Delete an organization] endpoint with either your organization ID or your organization slug. You can retrieve both from the CircleCI web app under menu:Organization Settings[Overview].
++
+[,shell]
+----
+curl --request DELETE \
+  --url https://circleci.com/api/v2/organization/<org-slug-or-id> \
+  --header "Circle-Token: ${CIRCLE_TOKEN}"
+----
+--
+====
+
+[#delete-a-project]
+== Delete a project
+
+NOTE: Only organization admins and project admins can delete projects.
+
+If you want to remove a project from your CircleCI account, follow the steps below.
+
+CAUTION: Deleting a project will remove the complete build history. 
+
+[tabs]
+====
+CircleCI web app::
++
+--
+include::guides:ROOT:partial$app-navigation/steps-to-project-settings.adoc[]
+
+[start=4]
+. Scroll to the bottom of the Overview page, select **Delete Project**.
+. Confirm your choice by typing the project name and selecting btn:[Permanently Delete Project] in the popup.
+--
+API::
++
+--
+. Set up your API authentication. Steps are available in the xref:toolkit:api-developers-guide.adoc#add-an-api-token[API developers guide].
+. You need the project slug to use the link:https://circleci.com/docs/api/v2/#tag/Project/operation/deleteProjectBySlug[Delete a project] endpoint. You can retrieve the project slug from the CircleCI web app under menu:Project Settings[Overview].
++
+[,shell]
+----
+curl --request DELETE \
+  --url https://circleci.com/api/v2/project/<project-slug> \
+  --header "Circle-Token: ${CIRCLE_TOKEN}"
+----
+--
+====
+
+If you encounter an error, open a new link:https://support.circleci.com/hc/en-us/requests/new[support request] with details of the project that you wish to remove. Choose the "Build Failure/Configuration Help/Service Issue" option when opening the request.
+
+For more information on submitting support requests, see https://support.circleci.com/hc/en-us/articles/27162205043995-How-to-submit-a-support-ticket[How to submit a support ticket
+].
diff --git a/docs/guides/modules/security/pages/stop-building-a-project-on-circleci.adoc b/docs/guides/modules/security/pages/stop-building-a-project-on-circleci.adoc
@@ -5,12 +5,12 @@
 
 [#introduction]
 == Introduction
-This page outlines how to stop builds for a project on CircleCI, and how to delete a project when required.
+This page outlines how to stop builds for a project on CircleCI.
 
 [#stop-building-a-project]
 == Stop building a project
 
-CAUTION: The **Stop Building** option will not automatically remove all project data from the CircleCI databases. To remove all project data from CircleCI you need to contact CircleCI support, as detailed in the <<remove-a-project-from-circleci>> section.
+CAUTION: The **Stop Building** option does not automatically remove all project data from the CircleCI databases. To remove all project data from CircleCI, see the xref:security:delete-organizations-and-projects.adoc#delete-a-project[Delete a project] documentation.
 
 include::ROOT:partial$notes/standalone-unsupported.adoc[This feature is not supported for GitLab, GitHub App or Bitbucket Data Center]
 
@@ -20,16 +20,3 @@ If you are using the GitHub OAuth App or Bitbucket Cloud, to stop building one o
 . Scroll to the bottom of the Overview page and select **Stop Building**. You will need to reconfirm your choice in the popup.
 
 NOTE: If you want to start building this project again, just go to the **Projects** page in the web app and select **Set Up Project** and follow the set up steps.
-
-[#remove-a-project-from-circleci]
-== Delete a project from CircleCI
-
-If you want to remove a project from your CircleCI account, follow the steps below. Deleting a project will remove the complete build history. Only organization admins and project admins can delete projects.
-
-. In the link:https://app.circleci.com/home/[CircleCI web app], select the organization associated with the project you want to remove.
-. Select the project you want to remove from the project cards. If you do not see your project, select **Projects** in the sidebar and find it in the list.
-. Select **Project Settings** (or the ellipsis next to your project image:guides:ROOT:icons/more.svg[more icon, role="no-border"] and then select **Project Settings**).
-. Scroll to the bottom of the Overview page and select **Delete Project** and reconfirm your choice in the popup.
-
-
-If you encounter an error, open a new link:https://support.circleci.com/hc/en-us/requests/new[support request] with details of the project that you wish to remove. Choose the "Build Failure/Configuration Help/Service Issue" option when opening the request. For more information on submitting support requests, see this https://support.circleci.com/hc/en-us/articles/27162205043995-How-to-submit-a-support-ticket[support article].
