self-host →

Uninstall Guide

Learn how to uninstall RunsOn.

How you uninstall RunsOn depends on how the stack was deployed.

CloudFormation#

  1. Go to the CloudFormation console ↗.
  2. Select the stack (name should be runs-on unless you overrode the default value).
  3. Click on the Delete button.
  4. Confirm the deletion by clicking on the Delete stack button.

The only retained resources should be the two S3 buckets — one for the cache (which also holds runner configuration under the runners/ prefix) and one for S3 access logs — which you can then delete manually.

If you enabled EFS (EnableEfs) or the ephemeral ECR registry (EnableEphemeralRegistry), the EFS file system and/or ECR repository are also retained on stack deletion and must be deleted manually. Both are disabled by default.

Terraform / OpenTofu#

If you deployed RunsOn with the Terraform / OpenTofu guide, remove it from the same root module and state that created it.

  1. From the Terraform/OpenTofu root module that contains RunsOn, run terraform plan -destroy or tofu plan -destroy and review the resources that will be removed.
  2. Run terraform destroy or tofu destroy.
  3. If your configuration intentionally keeps shared resources outside the RunsOn module, such as an existing VPC, subnets, or externally managed IAM policies, delete only the RunsOn-owned resources.
  4. Delete any retained RunsOn S3 buckets manually if they were kept for configuration, logs, or cache data.

terraform destroy will fail on non-empty cache buckets unless force_destroy_buckets = true. If prevent_destroy_optional_resources = true, the EFS file system has a prevent_destroy lifecycle that blocks destroy — remove that protection or delete EFS manually first. ECR ephemeral images are force-deleted by default.

Do not delete Terraform-managed resources manually in the AWS console unless you also clean up the Terraform/OpenTofu state. Keep the state as the source of truth.

Delete the GitHub private app#

After the AWS resources are removed, delete the GitHub App that was registered for that RunsOn stack:

  1. Go to the GitHub settings for your organization.
  2. Click on GitHub Apps.
  3. Click on the RunsOn app.
  4. Click on the Uninstall button.
  5. Confirm the deletion by clicking on the Delete button.