Skip to main content

Component: github-runners

This component is responsible for provisioning EC2 instances for GitHub runners.

We also have a similar component based on



Stack Level: Regional

Here's an example snippet for how to use this component.

cpu_utilization_high_threshold_percent: 5
cpu_utilization_low_threshold_percent: 1
default_cooldown: 300
github_scope: company
instance_type: "t3.small"
max_size: 10
min_size: 1
runner_group: default
scale_down_cooldown_seconds: 2700
wait_for_capacity_timeout: 10m
on_demand_allocation_strategy: "prioritized"
on_demand_base_capacity: 1
on_demand_percentage_above_base_capacity: 0
spot_allocation_strategy: "capacity-optimized"
spot_instance_pools: null
spot_max_price: null
- instance_type: "t4g.large"
weighted_capacity: null
- instance_type: "m5.large"
weighted_capacity: null
- instance_type: "m5a.large"
weighted_capacity: null
- instance_type: "m5n.large"
weighted_capacity: null
- instance_type: "m5zn.large"
weighted_capacity: null
- instance_type: "m4.large"
weighted_capacity: null
- instance_type: "c5.large"
weighted_capacity: null
- instance_type: "c5a.large"
weighted_capacity: null
- instance_type: "c5n.large"
weighted_capacity: null
- instance_type: "c4.large"
weighted_capacity: null


API Token

Prior to deployment, the API Token must exist in SSM.

To generate the token, please follow these instructions. Once generated, write the API token to the SSM key store at the following location within the same AWS account and region where the GitHub Actions runner pool will reside.

assume-role <automation-admin role>
chamber write github/runners/<github-org> registration-token ghp_secretstring



Github Actions Self-Hosted runners can be scoped to the Github Organization, a Single Repository, or a group of Repositories (Github Enterprise-Only). Upon startup, each runner uses a REGISTRATION_TOKEN to call the Github API to register itself with the Organization, Repository, or Runner Group (Github Enterprise).

Running Workflows

Once a Self-Hosted runner is registered, you will have to update your workflow with the runs-on attribute specify it should run on a self-hosted runner:

name: Test Self Hosted Runners
branches: [main]
runs-on: [self-hosted]

Workflow Github Permissions (GITHUB_TOKEN)

Each run of the Github Actions Workflow is assigned a GITHUB_TOKEN, which allows your workflow to perform actions against Github itself such as cloning a repo, updating the checks API status, etc., and expires at the end of the workflow run. The GITHUB_TOKEN has two permission "modes" it can operate in Read and write permissions ("Permissive" or "Full Access") and Read repository contents permission ("Restricted" or "Read-Only"). By default, the GITHUB_TOKEN is granted Full Access permissions, but you can change this via the Organization or Repo settings. If you opt for the Read-Only permissions, you can optionally grant or revoke access to specific APIs via the workflow yaml file and a full list of APIs that can be accessed can be found in the documentation and is shown below in the table. It should be noted that the downside to this permissions model is that any user with write access to the repository can escalate permissions for the workflow by updating the yaml file, however, the APIs available via this token are limited. Most notably the GITHUB_TOKEN does not have access to the users, repos, apps, billing, or collaborators APIs, so the tokens do not have access to modify sensitive settings or add/remove users from the Organization/Repository.

Example of using escalated permissions for the entire workflow

name: Pull request labeler
on: [ pull_request_target ]
contents: read
pull-requests: write
runs-on: ubuntu-latest
- uses: actions/labeler@v2
repo-token: ${{ secrets.GITHUB_TOKEN }}

Example of using escalated permissions for a job

name: Create issue on commit
on: [ push ]
runs-on: ubuntu-latest
issues: write
- name: Create issue using REST API
run: |
curl --request POST \
--url${{ github.repository }}/issues \
--header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
--header 'content-type: application/json' \
--data '{
"title": "Automated issue for commit: ${{ github.sha }}",
"body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
}' \

Pre-Requisites for Using This Component

In order to use this component, you will have to obtain the REGISTRATION_TOKEN mentioned above from your Github Organization or Repository and store it in SSM Parameter store. In addition, it is recommended that you set the permissions “mode” for Self-hosted runners to Read-Only. The instructions for doing both are below.

Workflow Permissions

  1. Browse to{Org}/settings/actions (Organization) or{Org}/{Repo}/settings/actions (Repository)

  2. Set the default permissions for the GITHUB_TOKEN to Read Only

Creating Registration Token

We highly recommend using a GitHub Application with the github-action-token-rotator module to generate the

Registration Token. This will ensure that the token is rotated and that the token is stored in SSM Parameter Store encrypted with KMS.

GitHub Application

Follow the quickstart with the upstream module, cloudposse/terraform-aws-github-action-token-rotator, or follow the steps below.

  1. Create a new GitHub App
  2. Add the following permission:
# Required Permissions for Repository Runners:
## Repository Permissions
+ Actions (read)
+ Administration (read / write)
+ Metadata (read)

# Required Permissions for Organization Runners:
## Repository Permissions
+ Actions (read)
+ Metadata (read)

## Organization Permissions
+ Self-hosted runners (read / write)
  1. Generate a Private Key

If you are working with Cloud Posse, upload this Private Key, GitHub App ID, and Github App Installation ID to 1Password and skip the rest. Otherwise, complete the private key setup in core-<default-region>-auto.

  1. Convert the private key to a PEM file using the following command: openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in {DOWNLOADED_FILE_NAME}.pem -out private-key-pkcs8.key
  2. Upload PEM file key to the specified ssm path: /github/runners/acme/private-key in core-<default-region>-auto
  3. Create another sensitive SSM parameter /github/runners/acme/registration-token in core-<default-region>-auto with any basic value, such as "foo". This will be overwritten by the rotator.
  4. Update the GitHub App ID and Installation ID in the github-action-token-rotator catalog.

If you change the Private Key saved in SSM, redeploy github-action-token-rotator

(ClickOps) Obtain the Runner Registration Token

  1. Browse to{Org}/settings/actions/runners (Organization) or{Org}/{Repo}/settings/actions/runners (Repository)

  2. Click the New Runner button (Organization) or New Self Hosted Runner button (Repository)

  3. Copy the Github Runner token from the next screen. Note that this is the only time you will see this token. Note that if you exit the New {Self Hosted} Runner screen and then later return by clicking the New {Self Hosted} Runner button again, the registration token will be invalidated and a new token will be generated.

  1. Add the REGISTRATION_TOKEN to the /github/token SSM parameter in the account where Github runners are hosted (usually automation), encrypted with KMS.
chamber write github token <value>


The GitHub Registration Token is not updated in SSM

The github-action-token-rotator runs an AWS Lambda function every 30 minutes. This lambda will attempt to use a private key in its environment configuration to generate a GitHub Registration Token, and then store that token to AWS SSM Parameter Store.

If the GitHub Registration Token parameter, /github/runners/acme/registration-token, is not updated, read through the following tips:

  1. The private key is stored at the given parameter path: parameter_store_private_key_path: /github/runners/acme/private-key
  2. The private key is Base 64 encoded. If you pull the key from SSM and decode it, it should begin with -----BEGIN PRIVATE KEY-----
  3. If the private key has changed, you must redeploy github-action-token-rotator. Run a plan against the component to make sure there are not changes required.

The GitHub Registration Token is valid, but the Runners are not registering with GitHub

If you first deployed the github-action-token-rotator component initally with an invalid configuration and then deployed the github-runners component, the instance runners will have failed to register with GitHub.

After you correct github-action-token-rotator and have a valid GitHub Registration Token in SSM, destroy and recreate the github-runners component.

If you cannot see the runners registered in GitHub, check the system logs on one of EC2 Instances in AWS in core-<default-region>-auto.

I cannot assume the role from GitHub Actions after deploying

The following error is very common if the GitHub workflow is missing proper permission.

Error: User: arn:aws:sts::***:assumed-role/acme-core-use1-auto-actions-runner@actions-runner-system/token-file-web-identity is not authorized to perform: sts:TagSession on resource: arn:aws:iam::999999999999:role/acme-plat-use1-dev-gha

In order to use a web identity, GitHub Action pipelines must have the following permission. See GitHub Action documentation for more.

id-token: write # This is required for requesting the JWT
contents: read # This is required for actions/checkout


terraform>= 1.0.0
aws>= 4.9.0
cloudinit>= 2.2


aws>= 4.9.0
cloudinit>= 2.2




aws_ami.runnerdata source
aws_iam_policy_document.github_action_runnerdata source
aws_iam_policy_document.instance_assume_role_policydata source
aws_partition.currentdata source
aws_ssm_parameter.github_tokendata source
cloudinit_config.configdata source


account_map_environment_nameThe name of the environment where account_map is provisionedstring"gbl"no
account_map_stage_nameThe name of the stage where account_map is provisionedstring"root"no
account_map_tenant_nameThe name of the tenant where account_map is provisioned.

If the tenant label is not used, leave this as null.
additional_tag_mapAdditional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.
ami_filterMap of lists used to look up the AMI which will be used for the GitHub Actions
"name": [
ami_ownersThe list of owners used to select the AMI of action runner instances.list(string)
attributesID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.
block_device_mappingsSpecify volumes to attach to the instance besides the volumes specified by the AMI
device_name = string
no_device = bool
virtual_name = string
ebs = object({
delete_on_termination = bool
encrypted = bool
iops = number
kms_key_id = string
snapshot_id = string
volume_size = number
volume_type = string
contextSingle object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.
"additional_tag_map": {},
"attributes": [],
"delimiter": null,
"descriptor_formats": {},
"enabled": true,
"environment": null,
"id_length_limit": null,
"label_key_case": null,
"label_order": [],
"label_value_case": null,
"labels_as_tags": [
"name": null,
"namespace": null,
"regex_replace_chars": null,
"stage": null,
"tags": {},
"tenant": null
cpu_utilization_high_evaluation_periodsThe number of periods over which data is compared to the specified thresholdnumber2no
cpu_utilization_high_period_secondsThe period in seconds over which the specified statistic is appliednumber300no
cpu_utilization_high_threshold_percentThe value against which the specified statistic is comparednumber90no
cpu_utilization_low_evaluation_periodsThe number of periods over which data is compared to the specified thresholdnumber2no
cpu_utilization_low_period_secondsThe period in seconds over which the specified statistic is appliednumber300no
cpu_utilization_low_threshold_percentThe value against which the specified statistic is comparednumber10no
default_cooldownThe amount of time, in seconds, after a scaling activity completes before another scaling activity can startnumber300no
delimiterDelimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.
descriptor_formatsDescribe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
{<br/> format = string<br/> labels = list(string)<br/>}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).
docker_compose_versionThe version of docker-compose to installstring"1.29.2"no
enabledSet to false to prevent the module from creating any resourcesboolnullno
environmentID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'stringnullno
github_scopeScope of the runner (e.g. cloudposse/example for repo or cloudposse for org)stringn/ayes
id_length_limitLimit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.
instance_typeDefault instance type for the action runner.string"m5.large"no
label_key_caseControls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.
label_orderThe order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.
label_value_caseControls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.
labels_as_tagsSet of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.
max_instance_lifetimeThe maximum amount of time, in seconds, that an instance can be in service, values must be either equal to 0 or between 604800 and 31536000 secondsnumbernullno
max_sizeThe maximum size of the autoscale groupnumbern/ayes
min_sizeThe minimum size of the autoscale groupnumbern/ayes
mixed_instances_policyPolicy to use a mixed group of on-demand/spot of differing types. Launch template is automatically generated.
instances_distribution = object({
on_demand_allocation_strategy = string
on_demand_base_capacity = number
on_demand_percentage_above_base_capacity = number
spot_allocation_strategy = string
spot_instance_pools = number
spot_max_price = string
override = list(object({
instance_type = string
weighted_capacity = number
nameID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.
namespaceID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally uniquestringnullno
regex_replace_charsTerraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.
regionAWS Regionstringn/ayes
runner_groupGitHub runner groupstring"default"no
runner_labelsList of labels to add to the GitHub Runner (e.g. 'Amazon Linux 2').list(string)[]no
runner_role_additional_policy_arnsList of policy ARNs that will be attached to the runners' default role on creation in addition to the defaultslist(string)[]no
runner_versionGitHub runner release versionstring"2.288.1"no
scale_down_cooldown_secondsThe amount of time, in seconds, after a scaling activity completes and before the next scaling activity can startnumber300no
ssm_parameter_name_formatSSM parameter name formatstring"/%s/%s"no
ssm_pathGitHub token SSM pathstring"github"no
ssm_path_keyGitHub token SSM path keystring"registration-token"no
stageID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'stringnullno
tagsAdditional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.
tenantID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is forstringnullno
userdata_post_installShell script to run post installation of github action runnerstring""no
userdata_pre_installShell script to run before installation of github action runnerstring""no
wait_for_capacity_timeoutA maximum duration that Terraform should wait for ASG instances to be healthy before timing out. (See also Waiting for Capacity below.) Setting this to '0' causes Terraform to skip all Capacity Waiting behaviorstring"10m"no


autoscaling_group_arnThe Amazon Resource Name (ARN) of the Auto Scaling Group.
autoscaling_group_nameThe name of the Auto Scaling Group.
autoscaling_lifecycle_hook_nameThe name of the Lifecycle Hook for the Auto Scaling Group.
eventbridge_rule_arnThe ARN of the Eventbridge rule for the EC2 lifecycle transition.
eventbridge_target_arnThe ARN of the Eventbridge target corresponding to the Eventbridge rule for the EC2 lifecycle transition.
iam_role_arnThe ARN of the IAM role associated with the Autoscaling Group
ssm_document_arnThe ARN of the SSM document.


Can we scope it to a github org with both private and public repos ?

Yes but this requires Github Enterprise Cloud and the usage of runner groups to scope permissions of runners to specific repos. If you set the scope to the entire org without runner groups and if the org has both public and private repos, then the risk of using a self-hosted runner incorrectly is a vulnerability within public repos.

If you do not have github enterprise cloud and runner groups cannot be utilized, then it’s best to create new github runners per repo or use the summerwind action-runners-controller via a Github App to set the scope to specific repos.

How can we see the current spot pricing?

Go to

If we don’t use mixed at all does that mean we can’t do spot?

It’s possible to do spot without using mixed instances but you leave yourself open to zero instance availability with a single instance type.

For example, if you wanted to use spot and use t3.xlarge in us-east-2 and for some reason, AWS ran out of t3.xlarge, you wouldn't have the option to choose another instance type and so all the GitHub Action runs would stall until availability returned. If you use on-demand pricing, it’s more expensive, but you’re more likely to get scheduling priority. For guaranteed availability, reserved instances are required.

Do the overrides apply to both the on-demand and the spot instances, or only the spot instances?

Since the overrides affect the launch template, I believe they will affect both spot instances and override since weighted capacity can be set for either or. The override terraform option is on the ASG’s launch_template

List of nested arguments provides the ability to specify multiple instance types. This will override the same parameter in the launch template. For on-demand instances, Auto Scaling considers the order of preference of instance types to launch based on the order specified in the overrides list. Defined below. And in the terraform resource for instances_distribution

spot_max_price - (Optional) Maximum price per unit hour that the user is willing to pay for the Spot instances. Default: an empty string which means the on-demand price. For a mixed_instances_policy, this will do purely on-demand

on_demand_allocation_strategy: "prioritized"
on_demand_base_capacity: 1
on_demand_percentage_above_base_capacity: 0
spot_allocation_strategy: "capacity-optimized"
spot_instance_pools: null
spot_max_price: []

This will always do spot unless instances are unavailable, then switch to on-demand.

# ...
spot_max_price: 0.05

If you want a single instance type, you could still use the mixed instances policy to define that like above, or you can use these other inputs and comment out the mixed_instances_policy

        instance_type: "t3.xlarge"
# the below is optional in order to set the spot max price
market_type = "spot"
block_duration_minutes: 6000
instance_interruption_behavior: terminate
max_price: 0.05
spot_instance_type = persistent
valid_until: null

The overrides will override the instance_type above.