Jess Thompson
1 November 2022
Guardrails: optimise Jira instance stability for enterprise
This guide looks at how to quickly and easily adhere to Atlassian's Guardrail recommendations for maintaining enterprise Jira instances using ScriptRunner.
There are many ways that an enterprise Jira instance can get out of hand over time. A lot of comments can affect user experience; enormous attachments can make things slow. You can end up with searches which take forever to complete, running out of memory; the list goes on. If thousands of colleagues depend on access to this information for their work, keeping things running quickly and reliably is one of the easier ways to ensure that the number of complaints in your inbox remains as low as possible.
Atlassian has recently provided a set of guidelines, called Guardrails, to assist in the challenge of cleanup and maintenance of Jira Data Center and Server.
"Guardrails are data type recommendations designed to help you identify potential risks and aid you [in] making decisions about next steps in your instance optimization journey."
Atlassian, Jira Software guardrails [accessed 31/10/2022]
Accelerate and automate your Jira housekeeping
To help you turn best practice into action in just a few quick clicks, we’ve released five new built-in scripts within ScriptRunner for Jira in line with Atlassian’s Guardrails for comments, project archiving, change history, attachments and issue links.
Administrators can now implement Atlassian’s recommendations using easily-configurable ScriptRunner power. Keep reading to find out how–plus some helpful hints for handling Atlassian’s Guardrail for epics using ScriptRunner!
The new ScriptRunner for Jira Guardrails built-in scripts are:
- Maximum Change History Records Per Issue
- Maximum Number of Issue Links Per Issue
- Maximum Attachment Size
- Maximum Number of Unarchived Projects
- Maximum Comments Per Issue
Each can be used for reporting and monitoring against Guardrail recommendations, and also for actioning any cleanup required.
Maximum Change History Records Per Issue
Atlassian recommends limiting the number of change items or change groups to prevent memory errors when viewing issue history, plus slow reindexing and issue interactions.
To help you manage this challenge without deleting all change history, we’ve created a built-in script which provides you with a list of issues with change items (including change groups) higher than the maximum limit that you specify.
Once you have the list of offending issues, you are presented with the ability to delete the oldest change items to speed things up again.
Maximum Number of Issue Links Per Issue
When it comes to issue links, Atlassian’s Guardrail gives a suggested cap of 1000 to keep issues loading quickly and to prevent stuck threads from jamming up your entire Jira instance.
This built-in script generates a list of issues with more issue links than you would like to permit on your instance. This defaults to 1000, as per Atlassian’s recommendation, but you can set this to be even lower if you wish.
From here, you can archive or delete the oldest issue links, or target specific types of issue link for cleanup.
Maximum Attachment Size
Instances and issues with too many (or too many large) attachments can be sluggish, and shared filesystems end up operating under unnecessarily heavy load. Atlassian’s Guardrail for this involves limiting both the number of attachments per issue (3000) and the size of said attachments (10MB per attachment).
The built-in script that we’ve created here helps you to find attachments which exceed a size that you specify, set to 10MB by default. If you’d like to be more specific with this search, you can use the Attachment filter to identify only attachments which fit the scripted criteria, such as image types, or added by certain users. We provide example snippets for these filters to help you.
Once you’ve got your offending attachments identified, you can delete them right away from the same screen.
Maximum Number of Unarchived Projects
Too many unarchived projects can cause slow reindexing, permissions and new project creation, even causing project creation to show timeout errors in some circumstances. To prevent these issues, Atlassian’s Guardrail recommends no more than 7000 projects unarchived at any one time.
The new ScriptRunner built-in script will help you to find projects which have not been updated within a specific window of time: the last six months, one year, two years, or a custom time length.
You’ll see a count of how many unarchived projects you have in total in the instance, plus a list of those which meet the criteria for archiving that you have set. You can also apply additional filters to target certain projects, for instance. This can be used alone for reporting and monitoring, or you can complete the next step, which is actually archiving the projects on the output list, using the button provided.
Maximum Comments Per Issue
Similar to issue links, Atlassian’s Guardrail for comments gives a proposed best practice limit of 1000. Proactively managing the build-up of comments can prevent slow issue loading and reindexing, and memory errors.
The built-in script we’ve created for you to manage this Guardrail generates a list of issues with more comments than your instance has set as the allowable limit. Search against all projects on your instance, or define specific projects to look at using the dropdown menu.
Should the built-in script find issues which exceed your recommended number of comments, you then have the option to delete old comments. By default, this will delete the oldest comments, but you can get more specific to target comments from application bots, for instance, to ensure that the least relevant comments are chosen for cleanup first.
View the full range of guardrails built-in scripts
Additional Guardrail assistance: epics
Another of Atlassian's Guardrails that ScriptRunner can also help you to adhere to relates to epics. The recommendation is to keep the number of epics below 100,000.
To get a list of epics which have not been updated within the last year, the following is a simple JQL search that you can conduct:
Find Epics not updated in the last year
1issuetype = Epic and updated < -52wUsing ScriptRunner's advanced JQL, however, we can make this search even more specific:
Epics which have no stories
1type = Epic and issueFunction not in epicsOf('')Epics where all stories are closed
1issueFunction in epicsOf('resolution is not empty') and not issueFunction in epicsOf('resolution is empty')You can read more about our best practice for Guardrails in our documentation.
More automated Jira cleanup
These Guardrails and built-in scripts are a great start for maintenance to help prevent slowness and instability, but did you know you can take your housekeeping to the next level with regularly-scheduled automation and event-based automation using ScriptRunner?
For example, you could auto-delete any archived projects two years after they were archived, or auto-archive any issues which have not been updated in the last 12 months.
Jobs will run automatically, as often as you dictate, taking care of actions for you. Listeners will trigger actions based on events within your Jira instance, taking some of the pressure off administrators to stay across everything.
The ability to get hyper-specific with automation rules using Groovy is what makes ScriptRunner a must-have for those administrating large Jira instances. You can make the rules truly fit your organisation’s processes and best practices, rather than having to make broad-brush decisions about cleanup and management that you might later regret or which don’t quite work within the context of your industry.
Not using ScriptRunner for Jira Data Center yet?
The must-have all-in-one automation and customisation toolbox for managing Jira at scale.