Cost allocation and resource tags

RunsOn tags all resources with default tags, and supports tagging resources with custom tags. This is useful to identify resources in your AWS account, help with cost allocation, and break down spend in AWS Cost Explorer.

How it works

RunsOn will tag all infrastructure resources with the CostAllocationTag key (default key: stack, value: the CloudFormation stack name).

For ephemeral resources (ec2 instances, disks, etc), RunsOn will tag them with the cost allocation tag, and any custom tags that you have defined.

EC2 instances will also be tagged with workflow-related tags (see Default tags below).

Default tags

RunsOn automatically applies the following default tags to EC2 instances:

Tag Key	Description
`runs-on-workflow-job-started`	Whether the workflow job has started
`runs-on-workflow-job-name`	Name of the GitHub Actions workflow job
`runs-on-workflow-job-interrupted`	Whether the job was interrupted
`runs-on-workflow-job-id`	Unique identifier for the workflow job
`runs-on-workflow-job-conclusion`	Final status of the workflow job
`runs-on-workflow-run-id`	Unique identifier for the workflow run
`runs-on-workflow-name`	Name of the GitHub Actions workflow
`runs-on-repo-full-name`	Full repository name (owner/repo)
`runs-on-image-id`	Unique identifier for the image spec used
`runs-on-runner-id`	Unique identifier for the runner spec used
`runs-on-networking-stack`	Networking stack configuration
`runs-on-labels`	Runner labels assigned to the job
`runs-on-org`	GitHub organization name
`runs-on-version`	RunsOn version used
`runs-on-env`	Environment configuration
`runs-on-role-id`	IAM role identifier
`runs-on-integrations-active`	Active integrations status
`runs-on-extras`	Additional configuration extras
`runs-on-is-private`	Whether the runner was launched in a private subnet
`runs-on-is-ghes`	Whether running on GitHub Enterprise Server
`runs-on-stack-name`	CloudFormation stack name
`runs-on-ami-name`	Name of the AMI used

The runs-on-is-private tag is useful if you want to break down usage between public and private runners, for example to understand which jobs are driving NAT gateway traffic.

Using RunsOn tags in AWS Cost Explorer

The default runs-on-* tags are standard AWS resource tags on the EC2 instances launched for your jobs. If you activate them as cost allocation tags in AWS Billing, you can use Cost Explorer to drill into where your RunsOn spend comes from.

The most useful tags to activate are usually:

runs-on-repo-full-name
runs-on-workflow-name
runs-on-workflow-job-name
runs-on-stack-name
runs-on-is-private

To enable them:

Open the AWS Billing and Cost Management console and make sure Cost Explorer is enabled.
Go to Cost allocation tags.
Search for the runs-on-* tags that you want to report on, then choose Activate.
If the AWS account where RunsOn is installed is a member account in AWS Organizations, do this from the organization’s management account (the top-level billing or payer account), not from the member account itself.
Wait up to 24 hours for the tags to become active in billing data and show up in Cost Explorer.
In Cost Explorer, group or filter by those tags to see costs per repository, workflow, or job.

Any custom tags you add through RunsOn can be activated the same way. For the AWS side of this flow, see the official guide on user-defined cost allocation tags ↗.

Custom tags

Custom tags can be set in different places:

custom tags defined in the RunnerCustomTags stack parameters.
custom tags defined in a specific custom property of your GitHub repository settings. The custom property must be named runs-on-custom-tags, and the value is a comma-separated list of tag keys and values, e.g. key1=value1,key2=value2.

custom tags defined for a runner specification in the runs-on.yml file.

If the same tag name is defined in multiple places, the precedence is as follows:

Stack-level tags
Custom property
runs-on.yml file