Post History

Building Codidact: Inside our Atlassian stack

A while ago, we [mentioned](https://meta.codidact.com/posts/280939) that Codidact has been improving its own infrastructure. However, the post only mentioned infrastructure in very broad terms and did not really go into details about planned tool improvements. In the interests of community transparency, we are now sharing some more information about these changes and doing a “deep dive” into how we use these tools, so that other open source organizations may benefit from our experiences.

With this post, we are focussing on improvements made possible by [Atlassian](https://www.atlassian.com), who gave us an open source cloud instance. 

## Discovering the offer
Codidact previously used a [Trello board](https://trello.com/b/BK4uxLoP/codidact-todo) for long term project planning and to show a roadmap - said board is now no longer receiving updates. Trello is owned by Atlassian and began requiring its users to link to an Atlassian account to log in, so it was natural to explore what other offerings Atlassian had.

One of our contributors investigated Atlassian’s offers, and discovered that they offered free cloud licenses to open source projects.

## How did we set this up?

We requested licenses from Atlassian via their [request form](https://www.atlassian.com/software/views/open-source-license-request). It took a while for us to get licenses in some cases because our request was initially submitted from a non-Codidact email address - it would have been better if we used a project email address to avoid those delays.

If our request were to be rejected, we would have used [Atlassian’s free plan](https://www.atlassian.com/software/free) instead to the extent possible.

## How do we use the Atlassian stack?
We use the Jira Software (internal ticketing), Jira Service Management (support ticketing), Confluence (internal wiki) and StatusPage services. 

Because these systems hold private information which should remain confidential (e.g. software security issues) and part of this relates solely to our site at codidact.com, we have not made our site public apart from a [support portal](https://codidact.atlassian.net/servicedesk/customer/portal/1) and a [public status page](https://status.codidact.com). Depending on a project’s needs and Atlassian requirements, other projects may adopt a different approach than what we have here. 

So, how do we use Atlassian products?

### Jira (the platform)
In the majority of use cases, Issue tracking is handled by Jira in an Atlassian stack. While everything runs off the same common platform, Jira operates under various names, such as Jira Software (handling project tracking for software teams) or Jira Service Management (which effectively functions as a support portal).

At Codidact, we differentiate between 2 types of issues: Code issues (that relate to our open source platform code) and internal issues (which involve the Codidact run deployment of that open source platform, or issues that need to remain confidential, such as security reports). 

We use the Jira platform to facilitate internal issue tracking (per our definition above) and we use GitHub and our own Meta community to track issues related to platform code (this generally means Jira is only used for user support for codidact.com, other issues specific to codidact.com or security issues relating to platform code). While using Jira for all issue tracking is a valid use case, we have not adopted this approach.

The specific Jira platform products we use are the Jira Software and Jira Service Management products at Codidact. 


#### Jira Software (the internal ticketing system)
Jira Software is used with Jira’s default settings, in line with our open by default principle, so all instance members with Jira access can see all projects and perform all non-admin ticket actions.

We have one kanban board type project tracking issues of interest to the Community Team and those tasks they are working on. Issues may also be used as a way to formally solicit team opinions on an issue before taking action.

For example, we may file an issue to track the design process for images that are uploaded to our social media platforms (e.g. profile picture or banner) in our Community Team project.


#### Jira Service Management (the support portal)

All external-facing support is handled by a single Jira Service Management project, which accepts both web and emailed requests. 

While a lot of organizations do not accept emailed support requests, we have opted to enable this support channel to allow all users who need support to receive it. In our experience, adequate spam filtering at email host level is required to prevent spam tickets appearing in Jira.

We do not typically accept requests from project staff via the Jira Service Management tool, as staff generally have the necessary permissions in our apps to implement changes themselves. In the rare case a staff ticket needs to go to support (e.g. a request for discussion), the requests are filed in the Community Team software project and transferred to the service desk. This ensures that we are not responding to requests that are impersonating a project staffer.

The single project is created with Jira defaults, modified to allow anyone to access the help center from the web and create tickets via email. 

We also use a variety of automation to assist with our help desk. For example, we have automation that will close spam tickets and flag them for later deletion. We also have automation which act as a “canned response” feature for tickets. To prevent any issues with automation on tickets, automation workflows must be manually triggered by a Codidact team member.

### Confluence
Confluence is Atlassian’s wiki product.

Primarily, we use Confluence as an internal knowledge base, much like a company or larger site may use similar functionality in Zendesk or ServiceNow. For example, we keep information on services we use (such as how to access them, what kind of process one follows to get access etc.) inside this system. We also may use this to store internal notes when required about community management, security issues, and other matters that should remain confidential. We have therefore not opted to make this system public at this time, owing to the work that would be required before we could safely do so.

We keep two main spaces available - a Community Team space and Operations space, both of which store information associated with their team (broadly speaking). Unless a specific need exists, we do not apply restrictions on access to content (Confluence allows for both view and edit restrictions). Contributors with access may have a personal space (which they largely control), which may be used by them as a note taking mechanism or for any other Codidact related purpose. 

### StatusPage
StatusPage is Atlassian’s product for showing system and site status. At Codidact, we use this as a public status page at https://status.codidact.com. This is also embedded on our site, so that a site status popup may appear on all pages in the event an incident or scheduled maintenance is declared.

A custom script ([codidact/uptime](https://github.com/codidact/uptime)) monitors our site’s uptime status, running off our staging systems. If a change is detected in uptime status, the script sends an email to a Statuspage provided email, which then automatically changes the site status shown on the status page. We retain the capability to override the uptime determinations if necessary. 

Incidents, which provide progress updates on site issues, must be manually declared by a Codidact team member. We can also declare scheduled maintenance in the event that was necessary. Anything we declare manually will automatically be pushed to a popup which appears on all Codidact pages. This allows for users currently browsing Codidact sites to receive messaging related to site status, which can explain issues they may be having.

Our @CodidactQA Twitter account is integrated with the StatusPage tool. At the discretion of a team member publishing an update, the update may be tweeted on that account directly from StatusPage.