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
  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.
    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.
    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
  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
  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.333.1'
  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'
  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'
  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.
runs:
  using: node24
  main: ./dist/index.js