Upgrades

For Flex, upgrading means updating your current stack with the latest version of the CloudFormation template.

This procedure 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.

Update the CloudFormation stack

Direct update

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

2. Now click on the Update button, and select Replace current template.

3. Enter the following URL:

https://runs-on.s3.eu-west-1.amazonaws.com/cloudformation/template-v3.1.0.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

Verifying the installation

You can verify the status of your installation by opening the RunsOn entrypoint URL from the CloudFormation stack outputs. If everything went well, you should see the following output:

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, put the old stack into maintenance mode by updating MaintenanceMode to true.
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, under Set up job, 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, put the new stack into maintenance mode, set the old stack’s MaintenanceMode back to false, and investigate before trying again.

Fleet upgrades are Terraform changes. Keep job labels stable while you upgrade the module, runtime image, and catalog.

Upgrade the module version

Update the module version in Terraform:

module "runs_on_fleet" {
  source  = "runs-on/runs-on/aws//modules/fleet"
  version = "v3.1.0"

  # ...
}

Run terraform plan and review changes to:

• the ECS/Fargate Fleet worker service
• the rendered config secret
• IAM roles and policies
• launch templates
• cache and log resources

Preserve runner fleet contracts

Repository workflows depend on:

runs-on: runs-on/fleet=<fleet-name>/env=<environment>

Changing a fleet key or environment changes that workflow contract. Prefer adding a new runner fleet, migrating repositories, and then removing the old runner fleet.

Upgrade runner images

Image changes are part of the catalog:

runners = {
  linux-build = {
    cpu    = 4
    ram    = 8
    family = ["c7"]
    image  = "ubuntu24-full-x64"
  }
}

If you maintain custom AMIs, update the images lookup pattern or owner only after the new AMI is published in every AWS region where Fleet runs.

Operational rollout

For production, use a staged rollout:

1. Apply the new module version to a non-production Fleet stack.
2. Run a workflow against each runner fleet.
3. Confirm GitHub scale sets, runner groups, CloudWatch logs, and EC2 launches.
4. Apply to production.
5. Watch assigned-job demand, launches, and runner registration after the change.

Fleet is complementary to Flex during migrations. Keep specialized Flex workflows on Flex until their runner needs become stable runner fleets.