Cloud migration guide

Assess current landscape

When auditing your current tech stack, take note of what products you have (both Atlassian products, as well as other tools you may want to integrate with).

• Are they all self-managed, or do you already have some cloud products?
• How many employees are using each product, and for what purpose?
• How often are they being used?
• Are there any instances you weren’t previously aware of? If so, do you plan on keeping them alongside your Cloud site, or archiving them?
• What version of Atlassian products are you running?
• Have you built customizations into Atlassian products? How often do you or your team maintain workflows and custom fields in your instances?

Understanding your current environment and what your teams actually need (versus what has naturally expanded or been adopted over time) will help you better define your path forward. Cleaning up and standardizing your workflows, tools, and teams prior to migrating will both make the process smoother, and benefit your teams once you transition to Cloud.

Assess apps and integrations

Similar to the previous step, take stock of the current apps (also referred to as plugins) you’ve installed or built on your own. Questions to ask yourself during the audit might be:

• How is each app being used? Are they all being used for their intended purpose?
• How many people are taking advantage of the apps?
• Are multiple apps serving the same purpose?
• Is the same app functionality available natively in the Cloud product?
• What’s the cost difference between Server and Cloud apps?
• Have any app licenses expired?

The main things to focus on when auditing your apps is whether they are available in Cloud, and if the data can be migrated or not.

Assess your apps with the Cloud Migration Assistants

If you haven’t already, download our Cloud Migration Assistants for Jira and Confluence and navigate to Assess your apps. The app assessment feature shows all the apps you currently have installed on your instance, if there is a version of that app in Cloud and if it offers the same functionality, as well as whether a migration pathway exists. 

Use our step-by-step instructions on how to use our Cloud Migration Assistants for app assessment or watch a quick video tutorial here. 

Cloud app availability and ability to migrate

Once you have your list of current apps and their usage, take this opportunity to do some spring cleaning. Talk to your internal teams to understand which apps are essential to day-to-day work, and are must-haves in Cloud, and which apps are no longer mission-critical or even being used. In some cases the apps you’re using in Server are native features in Cloud.

For apps that are essential, make sure there is a Cloud equivalent available. This can be done via the Cloud Migration Assistants, or you can also search for them in the Atlassian Marketplace.

If there isn’t an equivalent available, reach out directly to the vendor to see if one is in the works, see if a similar alternative exists in the Marketplace, or re-evaluate if the app is essential for your team at this time. Note that apps in Server may function differently in Cloud. We recommend contacting the vendor directly to check whether the Cloud app has functional parity.

To find out if your Server app has an available migration pathway to Cloud, review the list of migration-eligible apps and instructions in our Server to Cloud app migration documentation.

App security

Unlike the apps you’re using for your self-managed licenses, Cloud apps aren't installed behind your own firewall. Instead, most are hosted by the Marketplace or SaaS Partner who developed the app. While our vendors are accountable for their app security, we’ve also implemented strict requirements for every listing in the Atlassian Marketplace. Third-party apps are required to comply with:

• Industry aligned security self-assessment
• GDPR and European regulations on data and privacy

Some app partners have also chosen to participate in our public bug bounty program, where apps are tested by a pool of security researchers. You’ll see a “Cloud Security Participant” badge on their app listing.

We’ve also launched our Cloud Fortified Apps program, which makes it easier to find Atlassian Marketplace Cloud apps with advanced security, reliability, and support. To get a Cloud Fortified badge, Marketplace apps must meet Atlassian’s cloud security requirements and participate in additional opt-in cloud security programs, undergo regular performance checks and monitoring to maximize reliability, and maintain a strict support SLA.

To support extensibility and customization of our Cloud products, our app development platform, Forge, enables Marketplace Partners and customers to build apps with baked-in security features that comply with the core Atlassian Platform.

Assemble your team

Like we’ve said before, migration is a team sport — so it’s time to build your dream team to help your organization make the move. In most migrations, the roles outlined below are involved for end-to-end success, however, for smaller teams the same person may wear multiple hats. Remember, you can lean on Atlassian for support.

• Project manager: A dedicated person who puts together and presents the business case, manages the migration, tracks status and individual tasks, and acts as the main point of contact.
• Systems admins: Configured your systems in Server and knows the permissions and workflows that need to migrate. They may also perform the migration. If they don’t have Cloud experience, they may also want to engage a Solution Partner to perform the actual migration. 
• Executive sponsor: Handles budget approval, approves the business case, and may be the company’s Atlassian champion.
• Technical team and testers: Dedicated team that performs the migration. Before the migration, you’ll want to run a series of tests to make sure teams can complete important tasks. Testers should come from a variety of teams who’ll be using your systems in different ways and should test for their most important tasks.
• Security, legal and compliance: Someone from security and legal involved early in the project to make sure the migration plan meets all security and compliance standards (and keeps these requirements from being a blocker later in the process).
• Product champions: Migration will change the way teams work, which means teams will need training, troubleshooting, and possibly workflow brainstorming help. This may be taken on by a point person or may be a group effort.  

Get set up in Cloud

Using your Cloud migration trial, or if you aren't eligible, by purchasing a new Cloud site, there are two steps that need to be done right off the bat if you're thinking about using Atlassian Access for additional security across your site — setting up your organization and verifying your domain. Note that these are not required, but are a prerequisite for implementing Atlassian Access.

Decide if you need Atlassian Access

If you need centralized, enterprise-grade security and administration across your Atlassian Cloud products, then this is a good time to consider whether you need Atlassian Access. If you also need a cloud identity provider, sign up for a free Okta account directly within Atlassian Access. If you're not yet sure about Atlassian Access, you can also add this at a later time.

Set up your organization

As a refresher, an organization lets you view all of the Atlassian Cloud users at your company (across multiple Atlassian sites and products) in one place, manage your users' accounts, and set up security features like SAML SSO. An organization is automatically created for every site, or you can transfer a site into an existing organization. To access your organization, go to admin.atlassian.com and follow these steps on how to set up, rename, and add products and sites to your organization.

Verifying your domain

Verifying your domain will secure ownership of your company’s domain and claim all users' accounts (also referred to as managed accounts) with that same domain. Choose a method and follow the steps on how to verify a domain for your organization. This can take up to 72 hours, so you’ll want to do this early on.

Choose your migration method

When it comes to the actual migration methods, there are a few options to choose from. Consider the migration strategy you chose above, and review the migration methods outlined here to decide on the best approach. Factors that will impact your method include:

• which products you’re migrating
• what version of Server or Data Center you are on
• how much data needs to moved

App migration pathways

Part of migration planning includes determining your app migration pathways or how you’ll migrate Server apps and app data to Cloud.

Today, app data is not automatically migrated from Server to Cloud using the Cloud Migration Assistants. However, we’re working on adding this functionality to the Confluence and Jira Cloud Migration Assistants by the end of this year.

In the meantime, many Marketplace apps have documented manual migration paths available, or have committed to building automated migration paths. After you’ve assessed your apps and determined which ones you’ll need in Cloud, reference these pages for Jira and Confluence apps to determine what migration paths are available today. If you have questions on app migrations beyond what’s available in the documentation, we recommend reaching out to the app vendor directly.

User migration strategy

Your user migration strategy depends on which migration tools you use, and whether you have an external identity provider. Before deciding to migrate your users, be sure you’ve reviewed how users, groups and permissions are migrated for each product.

If you’re using a self-managed LDAP or Active Directory as your user authentication method, you must use Atlassian Access, which acts as the bridge between your identity provider and Atlassian Cloud products. If you don’t have a supported cloud identity provider, Atlassian offers a partnership with Okta for a free account.

To understand how to move forward based on your current user management setup, see our Access and Cloud migrations documentation.

Document your migration project plan, including planned activities, estimated timings, owners, and dependencies for each task.

Prep your team and site

With your plan and estimated timelines in place, start socializing the details of your migration with stakeholders, and the teams who will be impacted so your users can get started smoothly with minimal disruption to their work. For some companies, this step may happen sooner depending on the criticality of the products being migrated. It’s also best to establish a communications cadence for when, and how often, you’ll be communicating updates so teams are informed and prepared for the change.

Ensure you’re on a supported Server version

Depending on the migration method you’ve chosen, you may need to be on a certain version of your Server or Data Center instance to execute your migration. Check the supported versions below:

• Supported versions for the Jira Cloud Migration Assistant
• Supported version for Jira Site Import
• Supported versions for the Confluence Cloud Migration Assistant

Clean up your Server instance

The more data you migrate, the longer and more complex your migration is likely to be, and could affect Cloud performance later on. Use your migration as an opportunity to clean up your Server instance before running your test migration.

Some things to look out for might be inactive apps or users, old product data such as projects, customizations, or workflows that can be simplified or left behind, and any duplicate data. Refer to our documentation for best practices on cleanup.

Complete the pre-migration checklist

Before running your test migration, review our detailed pre-migration checklist to make sure your data and environment is ready to go.

• Jira pre-migration checklist
• Confluence pre-migration checklist

Install cloud apps

As part of testing, you may want to install and test the full functionality and migration of any apps that you plan on using in Cloud. Make sure both you and your stakeholders have tested the Cloud functionality and that it suits your teams' needs. Learn more about migrating your apps.

Build your runbook and timeline

Put together a runbook or step-by-step checklist of what needs to happen when, supporting instructions, who the owner is for each task, and how long each step will take. Document which steps are dependent on each other and will prevent you from moving forward if not completed. At the end of your runbook, include a mitigation plan with owners just in case you need to roll anything back.

To get started, download our runbook template and modify any tasks as needed. You can watch our short video on how to use the template.

In the next phase, you’ll use your runbook to run your test migration, and make adjustments as needed.

Test migration

Regardless of company size or migration complexity, we recommend all customers run through a test migration before executing a production migration. Make sure you’ve completed everything in the pre-migration checklist from the Prep phase before using our testing guide to walk through your test migration.

Backup your data

Regardless of which migration strategy and method you’ve chosen, we recommend backing up your self-managed instance prior to migrating it. If there is data in your Cloud site already, ensure this is backed up as well. See our documentation for guidance:

• Backing up data for Jira
• Backing up data for Confluence

User Acceptance Testing

Part of the test migration is conducting User Acceptance Testing (UAT) so your end users can replicate common day-to-day tasks, and make sure they work as expected. Through this process you can uncover any issues that will impact your end users and help your teams prepare to work in Cloud. Review step 6 of the testing guide for details on conducting UAT. 

After you’ve run your test migration and have an idea of how much time your migration will take, choose the date for production migration. If possible, schedule your migration at night, over a weekend, or another time when your team is less likely to need access to your self-managed instance or Cloud site to reduce the risk of disruption and data discrepancies. Don’t forget to factor in some extra time for troubleshooting!

If you’re migrating over 1,000 users, please contact us 2 months before your intended migration date.

Prepare training materials

A move to Cloud comes with some changes and benefits for your end users. Make sure you’ve understood and prepared for all the major changes such as how users will log in, new URLs, changes to apps, and user interface differences. Your UAT from above should give a sense for what questions users will have and the training that might benefit them. In addition to putting together material, here are some extra resources that may be helpful:

• Atlassian University – offers both free and paid courses to help admins and end users learn how to best leverage our products. Check out some of our change boarding tutorials here
• Jira product guide – gives you everything you need to know about using and customizing Jira, getting started, and best practices
• Confluence product guide – provides tutorials and demos on getting up and running with Confluence
• Bitbucket product guide – gives you everything you need to know about buying, using, and growing with Bitbucket Cloud
• Getting started in Cloud after migrating – this page can be helpful to include in an email to your users or as an extra resource they can access

To successfully transition your team, think about creating a clear process for collecting feedback and answering end user questions about the move to Cloud, such as office hours or a chat room.

Communicate your plan

With final timelines and owners in place, communicate the official plan to your organization. Things to include in your communications are:

• When will the migration occur?
• What downtime can users expect?
• Ask end users to avoid changing anything during the transition.
• What will happen to the old site after migrating? Will it still be accessible or readable?
• What will the new URL(s) be?
• How will they sign in?
• Who do they reach out to if they run into any issues or have trouble logging in?
• What onboarding material can they review to get acclimated to Cloud?

Keep in mind that there may be issues that occur during the migration that you may need to troubleshoot, so call out an adjustment period to your end users to get your site cleaned up and working as planned.

Set your Server to read-only

Depending on the migration strategy you chose, your users may no longer need access to your self-managed instance. To avoid any confusion and help with the switchover, put your sites into read-only mode prior to migrating. For Confluence Server, work through each space and remove all permissions for anything other than read. There is no explicit "read-only" mode in Jira Server, but you can do it manually by creating a permission scheme that only allows "browse" permission and applying it to all projects. Update your site-wide banners for Jira and Confluence stating that your site is now read-only during the migration.

If you have users continuing to work in the Server products after the migration, be sure to remove this setting after your migration is complete.

Run the production migration

It’s time to bring out the runbook you created and follow the steps and timing you put together to move your data over to Cloud. Refer to our documentation on how to use the Cloud Migration Assistants to run your migration if you’re using this method.

• Using Jira Cloud Migration Assistant to migrate
• Using Confluence Cloud Migration Assistant to migrate

If you’re a Bitbucket customer, refer to our Bitbucket migration documentation to carry out your migration.

Migrate any apps

With the app migration pathways you’ve identified, install and migrate the apps you deemed critical for use in Cloud.

QA migrated data

Check to see that your data migrated as expected, and that everything is working properly and in order. Refer step 6 in our testing guide for tips on what to look out for when reviewing your data.

If you run into blockers or need guidance throughout the migration phase, contact our migrations support team for help.