diff --git a/README.md b/README.md
index 353dd5e2..61cedc78 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ And all this automatically as a part of your GitHub Actions workflow.
>
> **Debian, Ubuntu, Alpine, and any other non-yum distributions are not supported.** If you launch this action against such an AMI, the EC2 instance will boot but the runner bootstrap will fail silently inside cloud-init, and the action will eventually time out with a registration error. Cross-distro support is not on the roadmap — if you need it, fork and replace the `userData` array in `src/aws.js`.
-
+
See [below](#example) the YAML code of the depicted workflow.
@@ -276,7 +276,9 @@ Now you're ready to go!
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | Always required. | Specify here which mode you want to use:
- `start` - to start a new runner;
- `stop` - to stop the previously created runner. |
| `github-token` | Always required. | GitHub Personal Access Token with the `repo` scope assigned. |
-| `ec2-image-id` | Required if you use the `start` mode. | EC2 Image Id (AMI).
The new runner will be launched from this image.
Only **yum-based** AMIs are supported (Amazon Linux 2023 tested; AL2 / RHEL-family in principle). See the [Supported operating systems](#on-demand-self-hosted-aws-ec2-runner-for-github-actions) notice at the top of this README. |
+| `ec2-image-id` | Required for `start` mode, unless `ec2-image-filters` is set. | EC2 Image Id (AMI).
The new runner will be launched from this image.
Only **yum-based** AMIs are supported (Amazon Linux 2023 tested; AL2 / RHEL-family in principle). See the [Supported operating systems](#on-demand-self-hosted-aws-ec2-runner-for-github-actions) notice at the top of this README. |
+| `ec2-image-filters` | Optional. Used only with the `start` mode. | Stringified JSON array of EC2 `DescribeImages` filters used to look up the AMI when `ec2-image-id` is not provided.
Example: `[{"Name": "name", "Values": ["al2023-ami-*-x86_64"]}]`. The most recently created matching image is used. |
+| `ec2-image-owner` | Optional. Used only with the `start` mode. | Scopes the `ec2-image-filters` AMI lookup to specific owners (AWS account IDs, `self`, `amazon`, or `aws-marketplace`). |
| `ec2-instance-type` | Required if you use the `start` mode. | EC2 Instance Type. |
| `subnet-id` | Required if you use the `start` mode. | VPC Subnet Id.
The subnet should belong to the same VPC as the specified security group. |
| `security-group-id` | Required if you use the `start` mode. | EC2 Security Group Id.
The security group should belong to the same VPC as the specified subnet.
Only the outbound traffic for port 443 should be allowed. No inbound traffic is required. |
@@ -284,6 +286,11 @@ Now you're ready to go!
| `ec2-instance-id` | Required if you use the `stop` mode. | EC2 Instance Id of the created runner.
The id is provided by the output of the action in the `start` mode.
The id is used to terminate the EC2 instance when the runner is not needed anymore. |
| `iam-role-name` | Optional. Used only with the `start` mode. | IAM role name to attach to the created EC2 runner.
This allows the runner to have permissions to run additional actions within the AWS account, without having to manage additional GitHub secrets and AWS users.
Setting this requires additional AWS permissions for the role launching the instance (see above). |
| `aws-resource-tags` | Optional. Used only with the `start` mode. | Specifies tags to add to the EC2 instance and any attached storage.
This field is a stringified JSON array of tag objects, each containing a `Key` and `Value` field (see example below).
Setting this requires additional AWS permissions for the role launching the instance (see above). |
+| `eip-allocation-id` | Optional. Used only with the `start` mode. | Allocation Id of an Elastic IP to associate with the runner instance once it is running. |
+| `runner-version` | Optional. Used only with the `start` mode. | Version of the `actions/runner` binary to download and register (default `2.333.1`).
Must have a matching entry in `src/runner-checksums.js`; the action verifies the downloaded tarball's SHA-256 against that table before extraction. |
+| `http-tokens` | Optional. Used only with the `start` mode. | Instance Metadata Service (IMDS) token mode (default `required`).
- `required` — IMDSv2 only; mitigates SSRF-style credential theft.
- `optional` — also allows IMDSv1; set only if a workload on the runner needs it. |
+| `encrypt-ebs` | Optional. Used only with the `start` mode. | When `true`, the root EBS volume is created with SSE-EBS encryption using the account's default AWS-managed key (default `false`). Volume size / type / IOPS are preserved from the AMI. |
+| `debug` | Optional. | When `true`, the action emits extra diagnostic output to the Actions log — inputs (secrets redacted), AWS SDK response metadata, and runner-registration poll details. Default `false`. |
### Environment variables
@@ -305,7 +312,7 @@ We recommend using [aws-actions/configure-aws-credentials](https://github.com/aw
### Example
-The workflow showed in the picture above and declared in `do-the-job.yml` looks like this:
+The workflow shown in the graph above and declared in `do-the-job.yml` looks like this:
```yml
name: do-the-job
@@ -319,14 +326,14 @@ jobs:
ec2-instance-id: ${{ steps.start-ec2-runner.outputs.ec2-instance-id }}
steps:
- name: Configure AWS credentials
- uses: aws-actions/configure-aws-credentials@v1
+ uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.AWS_REGION }}
- name: Start EC2 runner
id: start-ec2-runner
- uses: machulav/ec2-github-runner@v2
+ uses: namecheap/ec2-github-runner@v3
with:
mode: start
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
@@ -356,13 +363,13 @@ jobs:
if: ${{ always() }} # required to stop the runner even if the error happened in the previous jobs
steps:
- name: Configure AWS credentials
- uses: aws-actions/configure-aws-credentials@v1
+ uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.AWS_REGION }}
- name: Stop EC2 runner
- uses: machulav/ec2-github-runner@v2
+ uses: namecheap/ec2-github-runner@v3
with:
mode: stop
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
diff --git a/docs/images/github-actions-runner.gif b/docs/images/github-actions-runner.gif
new file mode 100644
index 00000000..e1e21cb7
Binary files /dev/null and b/docs/images/github-actions-runner.gif differ
diff --git a/docs/images/github-actions-summary.png b/docs/images/github-actions-summary.png
deleted file mode 100644
index 8b374a2a..00000000
Binary files a/docs/images/github-actions-summary.png and /dev/null differ