action.yml

name: On-demand self-hosted AWS EC2 runner for GitHub Actions
description: GitHub Action for automatic creation and registration AWS EC2 instance as a GitHub Actions self-hosted runner.
author: Volodymyr Machula
branding:
  icon: 'box'
  color: 'orange'
inputs:
  mode:
    description: >-
      Specify here which mode you want to use:
        - 'start' - to start a new runner;
        - 'stop' - to stop the previously created runner;
        - 'cleanup' - to reap leaked/orphaned runner instances this
          action started in the current repository (run on a schedule).
    required: true
  github-token:
    description: >-
      GitHub Personal Access Token with the 'repo' scope assigned.
    required: true
  ec2-image-filters:
    description: >-
      Filters to lookup for the AMI image.
      Example: '[{"Name": "name", "Values": ["amzn2-ami-hvm-2.0.????????-x86_64-gp2"]}]'
    required: false
    default: '[]'
  ec2-image-owner:
    description: >-
      Scopes the results to images with the specified owners. You can specify a combination of AWS account IDs, 'self', 'amazon', and 'aws-marketplace'.
      If you omit this parameter, the results include all images for which you have launch permissions, regardless of ownership.
      Works in conjunction with 'ec2-image-filters'
    required: false
  eip-allocation-id:
    description: >-
      Allows to associate the specified Elastic IP address with the runner instance
    required: false
  ec2-image-id:
    description: >-
      EC2 Image Id (AMI). The new runner will be launched from this image.
      This input is required if you use the 'start' mode.
    required: false
  ec2-instance-type:
    description: >-
      EC2 Instance Type. This input is required if you use the 'start' mode.
      Accepts a comma-separated ordered fallback list (e.g.
      'c7i.4xlarge,c6i.4xlarge,m7i.4xlarge'): on an insufficient-capacity
      error the action tries the next type. A single value behaves as before.
    required: false
  subnet-id:
    description: >-
      VPC Subnet Id. The subnet should belong to the same VPC as the specified security group.
      This input is required if you use the 'start' mode.
      Accepts a comma-separated ordered fallback list of subnets (typically
      in different AZs, e.g. 'subnet-aaa,subnet-bbb'): the action exhausts
      all subnets for an instance type before moving to the next type.
    required: false
  security-group-id:
    description: >-
      EC2 Security Group Id. 
      The security group should belong to the same VPC as the specified subnet.
      The runner doesn't require any inbound traffic. However, outbound traffic should be allowed.
      This input is required if you use the 'start' mode.
    required: false
  count:
    description: >-
      Used only with the 'start' mode. Number of runner instances to launch
      behind the single shared label (default 1). GitHub distributes matrix
      jobs across runners sharing a label. One RunInstances call launches all
      N; by default it is all-or-nothing (see allow-partial).
    required: false
    default: '1'
  allow-partial:
    description: >-
      Used only with the 'start' mode with count > 1. When 'false' (default)
      the batch is all-or-nothing (MinCount = count). When 'true', as few as
      1 instance may launch; the realized set is reported in the
      'ec2-instance-ids' output and a warning is logged.
    required: false
    default: 'false'
  reuse:
    description: >-
      Instance lifecycle. 'terminate' (default) launches a fresh instance on
      start and terminates it on stop. 'stop' enables warm pools: start
      reuses a stopped pool instance (or cold-launches into the pool), and
      stop stops the instance for reuse instead of terminating it. Set the
      same value on both the start and stop steps.
      WARNING: reused instances retain the previous job's disk state — safe
      for a single trusted repo's CI, UNSAFE for public/untrusted-PR
      workloads. See the security section in the README.
    required: false
    default: 'terminate'
  reuse-pool-tag:
    description: >-
      Used with reuse:stop. Pool identity — instances are interchangeable
      within a pool tag (default 'default'). Use distinct tags for distinct
      instance shapes (e.g. 'ci-medium', 'ci-large').
    required: false
    default: 'default'
  reuse-max-cycles:
    description: >-
      Used with reuse:stop. Recycle (terminate instead of stop) a pool
      instance after it has served this many jobs, so state doesn't
      accumulate forever (default 20).
    required: false
    default: '20'
  reaper-stopped-max-age:
    description: >-
      Used with the 'cleanup' mode. Terminate stopped pool instances older
      than this many minutes (default 1440 = 24h) so idle pools drain
      instead of accruing EBS cost.
    required: false
    default: '1440'
  label:
    description: >-
      Name of the unique label assigned to the runner.
      The label is used to remove the runner from GitHub when the runner is not needed anymore.
      This input is required if you use the 'stop' mode.
    required: false
  ec2-instance-ids:
    description: >-
      JSON array of EC2 instance ids to terminate, as emitted by a batched
      'start' (the 'ec2-instance-ids' output). Used with the 'stop' mode;
      either this or 'ec2-instance-id' is required to stop.
    required: false
  ec2-instance-id:
    description: >-
      EC2 Instance Id of the created runner.
      The id is used to terminate the EC2 instance when the runner is not needed anymore.
      This input is required if you use the 'stop' mode.
    required: false
  iam-role-name:
    description: >-
      IAM Role Name to attach to the created EC2 instance.
      This requires additional permissions on the AWS role used to launch instances.
    required: false
  runner-version:
    description: >-
      Version of the actions/runner binary to download and register.
      Must be one of the versions for which an entry exists in
      src/runner-checksums.js (the action verifies the downloaded
      tarball's SHA-256 against that table before extraction). To
      override, add the corresponding hash to the table in a PR.
    required: false
    default: '2.337.0'
  architecture:
    description: >-
      Used only with the 'start' mode. CPU architecture of the runner:
      'x64' (default) or 'arm64' (Graviton). Must match the AMI's
      architecture — a mismatch fails fast at start with a clear error. All
      instance types in an 'ec2-instance-type' fallback list must share this
      architecture. Checksums for both architectures are pinned, so no other
      change is needed to run on Graviton.
    required: false
    default: 'x64'
  pre-runner-script:
    description: >-
      Used only with the 'start' mode. A shell snippet run as root by the
      built-in bootstrap BEFORE runner configuration (e.g. install docker,
      mount caches, add corporate certs). Runs under set -euo pipefail; a
      failure is tagged 'failed:pre-runner-script'. Mutually exclusive with
      user-data-template.
    required: false
  user-data-template:
    description: >-
      Used only with the 'start' mode. Full user-data bootstrap override —
      a repo-relative file path or an inline template string. The action
      substitutes the documented placeholders ({{RUNNER_VERSION}},
      {{RUNNER_CHECKSUM_X64}}, {{RUNNER_CHECKSUM_ARM64}},
      {{REGISTRATION_TOKEN}}, {{REPO_URL}}, {{LABEL}}, {{TTL_MINUTES}}) and
      submits the result as-is. The template MUST register the runner.
      Custom templates are unsupported (the built-in bootstrap is the
      supported path); see examples/user-data/. Mutually exclusive with
      pre-runner-script.
    required: false
  encrypt-ebs:
    description: >-
      When 'true', the root EBS volume is created with SSE-EBS
      encryption enabled (AWS-managed KMS key, 'alias/aws/ebs', in
      the launch account). Requires that the account either has
      default EBS encryption enabled or can use the default AWS-
      managed KMS key. The AMI's BlockDeviceMapping is cloned and
      patched with 'Encrypted: true'; volume size / type / IOPS
      are preserved from the AMI. Default 'false' to avoid
      regressing consumers whose IAM / KMS policy doesn't allow
      this — opt in explicitly when you've verified the permissions.
    required: false
    default: 'false'
  market-type:
    description: >-
      Used only with the 'start' mode. 'on-demand' (default) or 'spot'.
      Spot instances are typically 60-90% cheaper and fit the ephemeral
      runner model, but can be reclaimed mid-job (2-minute warning).
    required: false
    default: 'on-demand'
  spot-fallback:
    description: >-
      Used only with the 'start' mode when market-type is 'spot'. What to
      do when spot capacity is unavailable: 'on-demand' (default) retries
      the launch as on-demand; 'fail' surfaces the error for cost-strict
      pipelines.
    required: false
    default: 'on-demand'
  spot-max-price:
    description: >-
      Used only with the 'start' mode when market-type is 'spot'. Optional
      maximum spot price in USD/hour (e.g. '0.05'). Empty (default) uses the
      on-demand price as the cap (AWS default).
    required: false
  volume-size:
    description: >-
      Used only with the 'start' mode. Root EBS volume size in GiB. When
      omitted, the AMI's default size is used (Amazon Linux 2023: 8 GiB,
      which Docker-based CI exhausts quickly). Must be >= the AMI snapshot
      size. Composes with encrypt-ebs.
    required: false
  volume-type:
    description: >-
      Used only with the 'start' mode. Root EBS volume type: one of gp3
      (recommended), gp2, io1, io2. When omitted, the AMI default is used.
    required: false
  volume-iops:
    description: >-
      Used only with the 'start' mode. Provisioned IOPS for the root
      volume. Only valid with volume-type io1, io2, or gp3.
    required: false
  volume-throughput:
    description: >-
      Used only with the 'start' mode. Root volume throughput in MiB/s.
      Only valid with volume-type gp3.
    required: false
  http-tokens:
    description: >-
      Instance Metadata Service (IMDS) token mode. Accepted values:
        - 'required' (default): IMDSv2-only. Any request to the IMDS
          endpoint (169.254.169.254) must present a session token.
          Mitigates SSRF-style credential theft.
        - 'optional': IMDSv1 and IMDSv2 both work. Only set this if
          a consumer workflow explicitly needs IMDSv1 compatibility.
      Passed through to RunInstances MetadataOptions.HttpTokens.
    required: false
    default: 'required'
  cleanup-on-start-failure:
    description: >-
      Used only with the 'start' mode. When 'true' (default), if the
      runner fails to bootstrap or register, the action captures the
      instance's console output and then terminates the instance so a
      failed start does not leak a billing instance. Set 'false' to
      leave the instance running for interactive debugging — the action
      prints its instance id and a ready-to-paste 'get-console-output'
      command instead of terminating it.
      NOTE: 'true' is a behavior change from older versions, which left
      the instance running after a registration timeout.
    required: false
    default: 'true'
  max-lifetime-minutes:
    description: >-
      Used only with the 'start' mode. Hard upper bound, in minutes, on
      the runner instance's lifetime. The instance arms a self-shutdown
      timer and launches with InstanceInitiatedShutdownBehavior=terminate,
      so it terminates itself when the timer fires even if GitHub, the
      workflow, and the AWS control plane are all unreachable. Size it
      above your longest legitimate job. Set '0' to disable the timer.
    required: false
    default: '360'
  max-age-minutes:
    description: >-
      Used only with the 'cleanup' mode. A registered-but-idle runner
      instance older than this many minutes is considered orphaned and
      reaped. Instances whose runner is no longer registered are reaped
      regardless of age (subject to a 15-minute grace floor that protects
      in-flight starts). Busy runners are never reaped.
    required: false
    default: '120'
  dry-run:
    description: >-
      Used only with the 'cleanup' mode. When 'true', the reaper lists the
      instances it would terminate (and why) in the job summary without
      terminating anything or deregistering any runners.
    required: false
    default: 'false'
  debug:
    description: >-
      When 'true', the action emits extra diagnostic output to the
      Actions run log: input parameters (secrets redacted), AWS SDK
      response metadata, runner-registration poll details. Leave at
      'false' for normal operation. Set 'true' when troubleshooting
      bootstrap failures.
    required: false
    default: 'false'
  aws-resource-tags:
    description: >-
      Tags to attach to the launched EC2 instance and volume.
      This must be a stringified array of AWS Tag objects, with both Key and Value fields,
      for example: '[{"Key": "TagKey1", "Value": "TagValue1"}, {"Key": "TagKey2", "Value": "TagValue2"}]'
    required: false
    default: '[]'
outputs:
  label:
    description: >-
      Name of the unique label assigned to the runner.
      The label is used in two cases:
      - to use as the input of 'runs-on' property for the following jobs;
      - to remove the runner from GitHub when it is not needed anymore.
  ec2-instance-id:
    description: >-
      EC2 Instance Id of the created runner.
      The id is used to terminate the EC2 instance when the runner is not needed anymore.
  ec2-instance-ids:
    description: >-
      JSON array of all EC2 instance ids launched by a batched 'start'
      (e.g. '["i-aaa","i-bbb"]'). For count=1 this is a single-element array;
      'ec2-instance-id' remains the first id for compatibility. Pass this to
      the 'stop' mode to terminate the whole batch.
  instance-type-used:
    description: >-
      The EC2 instance type that was actually launched (start mode). With a
      capacity-fallback list this may differ from the first choice.
  subnet-id-used:
    description: >-
      The subnet the runner was actually launched into (start mode). With a
      capacity-fallback list this may differ from the first choice.
  market-type-used:
    description: >-
      The market the runner was actually launched in (start mode): 'spot' or
      'on-demand'. Differs from market-type when spot fell back to on-demand.
runs:
  using: node24
  main: ./dist/index.js