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.
    required: true
  github-token:
    description: >-
      GitHub Personal Access Token with the 'repo' scope assigned.
    required: true
  availability-zones-config:
    description: >-
      JSON string array of objects with configurations for multiple availability zones.
      Each object should contain 'imageId', 'subnetId', and 'securityGroupId'.
      Optionally, you can specify 'region' to launch the instance in a specific AWS region.
      If 'region' is not specified, the default AWS_REGION environment variable will be used.
      Example: '[{"imageId":"ami-123","subnetId":"subnet-123","securityGroupId":"sg-123"},{"imageId":"ami-456","subnetId":"subnet-456","securityGroupId":"sg-456","region":"us-west-2"}]'
      When provided, the action will try each configuration in sequence until a successful instance is launched.
      This takes precedence over individual ec2-image-id, subnet-id, and security-group-id parameters.
    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 and don't provide availability-zones-config.
    required: false
  ec2-instance-type:
    description: >-
      EC2 Instance Type.
      This input is required if you use the 'start' mode.
    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 and don't provide availability-zones-config.
    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 and don't provide availability-zones-config.
    required: false
  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-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
  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: '[]'
  runner-home-dir:
    description: >-
      Directory that contains actions-runner software and scripts. E.g. /home/runner/actions-runner.
    required: false
  pre-runner-script:
    description: >-
      Specifies bash commands to run before the runner starts. It's useful for installing dependencies with apt-get, yum, dnf, etc.
    required: false
  market-type:
    description: >-
      Specifies the market (purchasing) option for the instance:
          - 'spot' - Use a spot instance
    required: false
  block-device-mappings:
    description: >-
      JSON string specifying the block device mappings for the EC2 instance.
      Example: '[{"DeviceName": "/dev/sda1", "Ebs": {"VolumeSize": 100, "VolumeType": "gp3"}}]'
    required: false
  startup-quiet-period-seconds:
    description: >-
      Specifies the quiet period in seconds after the instance starts.
      The runner will not be registered during this period.
    required: false
  startup-retry-interval-seconds:
    description: >-
      Specifies the retry interval in seconds to register the runner after the quiet period.
    required: false
  startup-timeout-minutes:
    description: >-
      Specifies the timeout in minutes to register the runner after the quiet period.
    required: false
    default: '5'
  run-runner-as-service:
    description: >-
      Start the runner as a service rather than using ./run.sh as root.
    required: false
    default: 'false'
  run-runner-as-user:
    description: >-
      Specify user under whom the runner service should run
    required: false
  ec2-volume-size:
    description: >-
      EC2 volume size in GB.
    required: false
  ec2-device-name:
    description: >-
      EC2 block device name.
    default: /dev/sda1
    required: false
  ec2-volume-type:
    description: >-
      EC2 block device type.
    required: false
  metadata-options:
    description: >-
      JSON string specifying the metadata options for the EC2 instance.
      Example: '{"HttpTokens": "required", "HttpEndpoint": "enabled", "HttpPutResponseHopLimit": 2, "InstanceMetadataTags": "enabled"}'
  packages:
    description: >-
      JSON array of packages to install via cloud-init.
      Example: '["git", "docker.io", "nodejs"]'
    required: false
    default: '[]'
  use-jit:
    description: >-
      Enable JIT (Just-In-Time) runner configuration. Uses GitHub's
      generate-jitconfig API instead of the traditional registration-token approach.
      JIT runners are single-use and auto-deregister after completing one job.
      Incompatible with 'run-runner-as-service: true'.
    required: false
    default: 'false'
  runner-group-id:
    description: >-
      The ID of the runner group to register the JIT runner in.
      Defaults to 1, which is the "Default" runner group for repository-level runners.
      Only used when 'use-jit' is true.
    required: false
    default: '1'
  runner-debug:
    description: >-
      Enable verbose debug logging for the runner setup.
      When true, outputs detailed instance info, console output polling,
      and step-by-step script execution logs.
    required: false
    default: 'false'
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.
  region:
    description: >-
      AWS region where the EC2 instance was created.
      This is useful for subsequent AWS operations on the instance.
runs:
  using: node20
  main: ./dist/index.js