Hello fellow Jira admins,
I wonder what's the best practice to document/track project configurations for all of your projects (which includes workflow setup, automation, scripts used etc.). As there are more and more projects to manage, it would be great to have a place to document all the configuration changes and why certain project was set up this way.
Any inputs are greatly appreciated.
Solved! Go to Solution.
Nice list @Alvin Rodis! There is actually a 3rd-party app called Smart Jira Configuration that documents a lot of this with just a couple of clicks. It doesn't provide graphics, org charts, policy, etc. but it could document the project configuration part nicely and in great detail.
We share the generic configuration and when there is a specific need of particular project for exceptional we create a coppy of generic configuration and name it by that project and to description we add information regarding the config change and the reason
and also we have a separate jira project to track requirements for specific jira configuration - so it can be found there, who, why , what and when :)
Hi @Allen Chen ,
Gil from Salto here.
We have a lot of great experience with customers (typically of highly complex Jira cloud setups) automatically documenting their configs and changes to it in code in Git (and most of them would also tie these config changes to issues in a separate jira project to track jira requirements like @Radka Svobodova suggested).
Many of these customers moved from a manually created documentation scheme (as suggested by @Alvin Rodis ) to using us, as it ensures that the documentation is always up to date (as it gets auto generated from the actual jira sites).
Typically, this would be tied to a proper change management process done with Salto (e.g. all jira config changes first done in a sandbox, and then after review and proper gates are promoted to production), but some just use us for the documentation and visibility aspects.
If it sounds interesting, feel free to reach out.
Re: "automatically documenting their configs and changes to it in code in Git (and most of them would also tie these config changes to issues in a separate jira project to track jira requirements"
@Shah, Piyush , yes it is supported with Atlassian Cloud and is blessed by Atlassian (and is on the marketplace).
There are quite a few demos at https://www.youtube.com/playlist?list=PLw8aI-Qt_EsZiK4aOeiL76wqntbnmoBI8 and pretty decent explanations at https://www.salto.io/solution/jira .
There's also a free trial (and a free tier), so you can just hook it up to your site (can also be a sandbox / dev instance) to get a feel for it.
@Allen Chen - For what it's worth, I'm a customer of Salto and vouch it works fantastic for this purpose.
I think the free version will basically satisfy your requirements, and the paid version definitely will.
It's worth investigating (IMO).
Can confirm. I'm still working with my organization to get the budget allocated for the purchase, but based on what it offers for free and my time with the trial I am definitely a convert. I don't know how any decent-sized organization that cares about the health of their project data pipeline lives without the capabilities that Salto offers.
A minor point, but consistent naming of workflows and automation will go a long way to figuring out which things go together.
Tagging automations has also been hugely helpful - especially when combined. Tag all change management rules, add additional tags for automations that deal with a specific type of change, or that call web endpoints, etc.
Chiming in to agree here -- we ridiculously "overname" everything, all the way to "(division's) research project issue screen scheme" as we found it made things clearer when trying to set up new projects.
Our lives have also been made somewhat simply by our use of Deep Clone add on and starting to limit ourselves to a smaller number of template projects. It was too hard to support the Wild West of many utterly unique projects.
You're telling me "Copy of Copy of Unified ABC Workflow scheme w/Added Status no Bugs 2.0" isn't clear? ;)
I follow what may be worded as "Optimal" documentation characterized by:
These are very good guidelines.
As for the "I wish ..." bullet, @Shah, Piyush , this is exactly what we do at Salto... Feel free to DM me if you're curious (or just browse our web-site and/or youtube channel)
@Gil Hoffer : I benefit a lot from Atlassian Community to actually find solutions to many challenges with Atlassian and I do NOT write endorsements like this very often.
I must say that, Salto is a life savior. We are doing a trial and I want to publicly state that Salto is doing two most desired things:
Seriously, the only regret I have is why did I wait 4 months to do the trial.
Lastly, Salto may NOT be perfect just like almost everything else but it has enough power and benefits that we can't live without. And in the most ideal case, Atlassian should have this functionality built-in.
Option 1. Use a Confluence Page for Each Project
Option 2. Create a Jira Project for Change Requests
Combine Confluence Page and the Jira Project
On the main Confluence page for each project, add a section that links to relevant change requests in the “Jira Configuration” project. This can be done by embedding a Jira filter macro that pulls in all issues tagged with that project.
Automate administrative task in workflow of the tracking project
In addition to tracking change requests in a Jira project, you can also use automation and scripting tools (like ScriptRunner, Automation for Jira, or Power Scripts) to streamline the workflow by automating certain administrative tasks after a change request is approved. This can save time and reduce the potential for errors in repetitive administrative work.
Example: Set up a workflow for change requests that includes distinct stages such as:
Open → In Review → Approved → In Progress → Completed
When a change request reaches the Approved stage, an automated action can be triggered to implement certain types of changes directly and move to completed state automatically, or notify the appropriate administrator to take action.
But I am not sure that automation may work in Jira Cloud due to strict permission concepts for scripts.
We usually define a process around workflow setup, automation, scripts used etc. Then educate the "project leads" for individual projects within Jira.. And then let them manage it strictly. The process may vary from company to company depending the size and complexity of the projects. In a nutshell, since Jira is highly customizable, its always best to keep it as simple as possible for everyone to understand, follow, adapt the changes.
Recommended Learning For You
Level up your skills with Atlassian learning
Learning Path
Become an effective Jira admin
Manage global settings and shared configurations called schemes to achieve goals more quickly.
Streamline Jira administration with effective governance
Improve how you administer and maintain Jira and minimize clutter for users and administrators.
Learning Path
Become an effective Jira software project admin
Set up software projects and configure tools and agile boards to meet your team's needs.