This article goes into the details of how current users of the Stoplight Next product can migrate to the new Stoplight Studio platform, and what considerations should be made prior to migrating.
Before continuing, please review the product differences between Next and Studio to ensure functionality critical to your use of Stoplight is available in the latest version. If you have any questions at all, don't hesitate to reach out to email@example.com.
What should I know prior to migrating?
There are a few considerations to be aware of prior to migrating from Stoplight Next:
- Ensure that any functionality critical to your use case is available in the latest version of Stoplight. Please review the article here for a matrix of supported functionality between the versions.
- In Stoplight Next, project storage was provided by Stoplight itself. In the latest version of Stoplight, this is no longer the case. Storage is now provided by an integration between Stoplight and your source-control provider (Github, GitLab, Bitbucket, etc). This will require both network connectivity and OAuth permissions between the connected source-control provider and Stoplight.
- In Stoplight Next, user, group, and organization permissions were managed within Stoplight directly. In the latest version of Stoplight, these permissions are now mostly managed within your connected source-control provider (Github, GitLab, etc), and are enforced within Stoplight via OAuth with the connected user account. This means that any users who will need to edit APIs or other API-related artifacts will also need to have access to your source-control provider.
- The architecture of the latest Stoplight version has been simplified dramatically from Stoplight Next. If you are running on-premise, please review the installation guide here for an overview of what has changed with regards to installing, configuring, and maintaining Stoplight.
What can't be migrated?
Note that the following features in Stoplight Next do not currently have a migration path:
- Discussions - The "Discussions" functionality in Stoplight Next currently cannot be migrated from Stoplight Next. Moving forward, it is recommended to use the built-in commenting and issue tracking functionality of the connected source-control provider.
- Published Hubs - The "Hub" format used in Stoplight Next is no longer available in Studio. While Studio does provide documentation functionality, some features around documentation hosting and integrations do not have direct parity to Studio's documentation capabilities.
- Scenarios - The Scenario format is no longer available in Studio. While this may change in the future, we recommend users leverage other tools in the meantime for any testing needs (Postman, Insomnia, etc). Please review the article here for more information on how such a workflow might be used to accomplish the same effect as Scenarios.
- Mock Servers - The Prism instance/server configurations (used for powering mock servers) are no longer supported in Studio. Studio does offer hosted and local mocking capabilities, however the configuration format used in Next is no longer used and the ability to connect Scenarios with Mock servers is no longer supported.
If there is an important integration or feature preventing you from migrating, let us know.
What does the migration look like?
Since project data is now stored within the connected source-control provider directly, all projects in Stoplight Next must be moved to that provider. Stoplight Next leveraged GitLab CE for storage of project data, so all Next projects are already Git repositories which natively support mirroring. Note that you can also export APIs manually, however mirroring the Git repositories is the most straightforward option and provides the most safety for your data.
If you have a large number of projects to migrate, please reach out to firstname.lastname@example.org for assistance. We may have tooling and other capabilities that may help aid in the transition.
Migrating data from Next to your own provider
To migrate data between platforms, you will simply need to mirror the Git repositories from the Next GitLab CE installation to your own source-control provider (Github, GitLab, etc).
If using the Git CLI, this can be done using the follow commands:
# clone the NEXT project locally
git clone --bare https://git.stoplight.io/example-organization/next-project.git
# push the NEXT project to your own source-control repo
git push --mirror https://git.example.com/new-organization/new-repository.git
For more information on how to connect to Git repositories in Stoplight Next, please see here.
Once the NEXT data has been successfully pushed to your own repository, you can then import the Git repository from your own source control provider using the automatic import feature as shown below:
Once imported, a webhook will automatically be configured to ensure that content stored in Stoplight is always up-to-date with your Git repository.