Case Study: Automating Jira Team Cleanup After a Cloud Migration

After migrating from Jira Data Center to Jira Cloud, the organisation discovered a significant structural issue within Jira teams. The migration resulted in hundreds of duplicated teams that no longer adhered to the organisation’s naming conventions. Due to the number of teams and their integration with boards, workflows, alerts, and permissions, manual cleanup was impractical. Attempting to remove and recreate teams manually would introduce risks, inconsistencies, and a lack of auditability.

The Problem

The organisation needed to eliminate hundreds of obsolete Jira teams and recreate them using a strict naming convention. This process had to be repeatable, safe for production, and fully auditable. Importantly, teams could not be deleted in bulk. Many were referenced across Jira configurations, requiring deliberate and controlled changes to avoid disrupting operational workflows.

Constraints & Challenges

The project faced a few practical hurdles along the way. With so many teams working across various projects, a manual approach just wasn’t going to cut it. There was also a fair amount of risk involved; since many teams were tied to boards, workflows, and alerts, a wrong deletion could throw a wrench into live operations. On the security front, we had to be quite cautious with API permissions and scopes to ensure we didn’t give out too much access. Consistency was another key issue, if we went the manual route, we’d likely end up with naming mismatches or duplicates. Lastly, the organization needed to maintain full auditability, ensuring we could trace back every team that was deleted and recreated without a hitch.

Solution Overview

To tackle these challenges, a custom Jira API application was developed by myself to automate the lifecycle of Jira teams post-migration. The goal was to not only resolve the immediate issue but also to establish a reliable and reusable approach for future migrations or restructures. The application followed a controlled, multi-phase workflow prioritising safety and traceability. It began with discovery and validation to identify teams eligible for removal, followed by programmatic deletion and recreation based on a predefined source of truth. Each stage was logged to ensure full visibility into actions taken.

The solution integrated a lightweight custom application with Jira Cloud REST APIs and a simple configuration-driven approach. Team definitions were supplied via a CSV file, serving as the authoritative source for naming conventions and descriptions. Audit logging was incorporated from the outset, enabling end-to-end traceability of every deletion and recreation event.

Key APIs used:

• Jira Teams API

  
  

Execution

We had to ensure we followed clear steps to ensure the execution was safe, tested and validated.

Safe Team Deletion

Before making any production changes, the process was validated through a dry run in a test environment. Teams marked for removal were deleted via API in controlled batches, minimising risk and allowing safe handling of failures. Any errors encountered during execution were logged and retried automatically.

Automated Team Recreation

Once obsolete teams were removed, new teams were recreated automatically using the predefined CSV and JSON configuration. This ensured each team had a consistent name and description, eliminating the inconsistencies often introduced through manual recreation.

Verification & Reporting

After execution, the application conducted validation checks to confirm team counts, membership accuracy, and API response integrity. Detailed audit logs were generated, providing clear evidence of changes made and supporting compliance requirements.

Results

In total, the solution processed over 600 teams, reducing manual effort by approximately 99%. Configuration errors were eliminated entirely, and what would previously have taken days of manual work was completed in a matter of minutes. Throughout the process, full audit traceability was maintained, ensuring the organisation remained audit-ready at every stage.

Benefits

The solution provided immediate operational benefits by significantly reducing manual effort and eliminating configuration errors. It also established a scalable and repeatable approach to managing Jira teams, enabling future migrations or restructures to be conducted confidently. From a governance perspective, the inclusion of full audit logging ensured that every change could be reviewed and justified, meeting both internal and external compliance requirements.

Lessons Learned

This work highlighted that Jira migrations often leave behind structural artefacts that require programmatic resolution. Jira teams are closely linked to the wider system, and their removal must be approached with care. Most importantly, maintaining a declarative source of truth for team definitions greatly reduced risk and simplified the processes of testing, execution, and auditing.