Upgrade Guide

Whenever a new version of RunsOn is available, you will need to update your current stack with the latest version of the CloudFormation template.

This guide is also valid if you simply want to update one of the stack parameters, for instance to update the LicenseKey parameter once you have purchased a license.

Tip

If you want to get alerted of new releases, please star and watch the repository ↗, and subscribe to the mailing list ↗.

Update the CloudFormation stack

Direct update

1. Go to CloudFormation > Stacks, then click on your RunsOn stack.

2. Now click on the Update button.

3. Make sure to select Replace current template, and enter the following URL:

https://runs-on.s3.eu-west-1.amazonaws.com/cloudformation/template-v2.8.8.yaml

4. Then click Next.

5. On the next screen, ensure all required parameters are given, then click Next until you get to the recap screen. At this point, click Submit after checking the permission boxes.

Using changesets to preview the changes

Tip

When updating your CloudFormation stack, you can use changesets to preview the changes that will be made before applying them. This is especially useful for understanding what resources will be modified, created, or deleted during the upgrade.

To use change sets:

1. Instead of clicking Update directly, click Create change set for current stack
2. Select Replace current template and enter the template URL
3. Review and submit the change set
4. Once created, review the changes in the change set details
5. If the changes look correct, execute the change set to apply the updates

This approach gives you a safety net to review changes before they’re applied to your production environment.

Verifying the installation

You can verify the status of your installation by opening the RunsOn AppRunner endpoint. If everything went well, you should see the following output:

Tip

Upgrades for minor and patch releases do not incur downtimes (e.g. from v1.2.x to v1.3.x). Major version upgrades may incur downtime (e.g. from v1.2.x to v2.1.x).

Rolling back

If for any reason you need to roll back to a previous version, you can do so by directly referencing the previous version of the CloudFormation template.

1. Go to CloudFormation > Stacks, then click on your RunsOn stack.
2. Click Update.
3. Select Replace current template, and enter the following URL:

https://runs-on.s3.eu-west-1.amazonaws.com/cloudformation/template-VERSION.yaml

You will find the version-specific CloudFormation template URL in the Changelog.

Blue-green deployment

If you want to test a large upgrade without upgrading your current stack, you can use a blue-green deployment strategy.

1. Create a new stack with the new version of the CloudFormation template (follow the installation guide, using the same license key).
2. Register the GitHub App, assign the necessary repositories, and verify that you get the success screen on your new RunsOn entrypoint URL.
3. Once the new stack is operational, pause the current production AppRuner service (go to your CloudFormation stack resources, click on the AppRuner service, and click on the Actions button, then Pause).

4. Trigger a few jobs, verify that they start and end up on the new stack version (you can use the “Runner details” logs in the GitHub job output to check for the correct version).
5. Once you are satisfied with the new version, you can then permanently delete the old stack, as well as the corresponding GitHub App.
6. If the new version is not working as expected, you can simply pause the new stack, unpause the old stack, and jobs will then start running on the old stack again. You can then delete the new stack or investigate the issue.