Skip to content

Commit 0eea8c8

Browse files
machulavmachulav
committed
Update README.md and the description in other places
1 parent c7bf8c1 commit 0eea8c8

File tree

4 files changed

+93
-32
lines changed

4 files changed

+93
-32
lines changed

‎README.md

+88-27
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,87 @@
1-
# On-demand self-hosted EC2 runner for GitHub Actions
1+
# On-demand self-hosted AWS EC2 runner for GitHub Actions
22

3-
Using this GitHub action, you can start a new EC2 instance and register it as a [self-hosted runner in GitHub](https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners) right before you need it. Then run all the required jobs on it and stop it when you don't need it anymore.
3+
Start your EC2 [self-hosted runner](https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners) right before you need it.
4+
Run the job on it.
5+
And finally, stop it when you finish.
6+
7+
![GitHub Actions self-hosted EC2 runner](docs/images/github-actions-summary.png)
48

59
**Table of Contents**
610

711
- [Usage](#usage)
12+
- [How to start](#how-to-start)
813
- [Inputs](#inputs)
914
- [Environment variables](#environment-variables)
1015
- [Outputs](#outputs)
1116
- [Example](#example)
17+
- [Self-hosted runner security with public repositories](self-hosted-runner-security-with-public-repositories)
1218
- [License Summary](#license-summary)
1319

1420
## Usage
1521

22+
### How to start
23+
24+
Use the following steps to prepare your workflow for running on your EC2 self-hosted runner:
25+
26+
**1. Prepare AWS access keys**
27+
28+
1. Create new AWS access keys with the following least-privilege permissions.
29+
The action will use the keys for EC2 instance management in the AWS account.
30+
31+
```
32+
{
33+
"Version": "2012-10-17",
34+
"Statement": [
35+
{
36+
"Effect": "Allow",
37+
"Action": [
38+
"ec2:RunInstances",
39+
"ec2:TerminateInstances",
40+
"ec2:DescribeInstances",
41+
"ec2:DescribeInstanceStatus"
42+
],
43+
"Resource": "*"
44+
}
45+
]
46+
}
47+
```
48+
49+
2. Add the keys to GitHub secrets.
50+
3. Use the [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) action to put the keys into environment variables.
51+
52+
**2. Prepare GitHub personal access token**
53+
54+
1. Create a new GitHub personal access token with the `repo` scope.
55+
The action will use the token for self-hosted runners management in the GitHub account on the repository level.
56+
2. Add the token to GitHub secrets.
57+
58+
**3. Prepare EC2 image**
59+
60+
1. Create a new EC2 image (AMI) from the Linux distribution you need.
61+
You don't need to install anything special beforehand into the AMI.
62+
The action will install all the necessary tools during the EC2 instance creation.
63+
64+
**4. Configure the GitHub workflow**
65+
66+
1. Create a new GitHub Actions workflow or edit the existing one.
67+
2. Use the documentation and example below to configure your workflow.
68+
3. Please don't forget to set up a job for removing the EC2 instance at the end of the workflow execution.
69+
Otherwise, the EC2 instance won't be removed and continue to run even after the workflow execution is finished.
70+
71+
Now you're ready to go!
72+
1673
### Inputs
1774

18-
| Name | Required | Description |
19-
| ------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
20-
| `mode` | Always. | Specify here which mode you want to use:<br>- `start` - to start a new runner;<br>- `stop` - to stop the previously created runner. |
21-
| `github-token` | Always. | GitHub Personal Access Token with a `repo` scope assigned. |
22-
| `ec2-image-id` | Required if you use the `start` mode. | EC2 AMI Id. <br><br> The new runner will be launched from this image. The action is compatible only with Linux images. |
23-
| `ec2-instance-type` | Required if you use the `start` mode. | EC2 Instance Type. |
24-
| `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. |
25-
| `security-group-id` | Required if you use the `start` mode. | EC2 Security Group Id. <br><br> The security group should belong to the same VPC as the specified subnet. <br><br> The runner doesn't require any inbound traffic. However, outbound traffic should be allowed. |
26-
| `label` | Required if you use the `stop` mode. | Name of the unique label assigned to the runner. <br><br> The label is used to remove the runner from GitHub when the runner is not needed anymore. |
27-
| `ec2-instance-id` | Required if you use the `stop` mode. | EC2 Instance Id of the created runner. <br><br> The id is used to terminate the EC2 instance when the runner is not needed anymore. |
75+
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Required | Description |
76+
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77+
| `mode` | Always required. | Specify here which mode you want to use:<br>- `start` - to start a new runner;<br>- `stop` - to stop the previously created runner. |
78+
| `github-token` | Always required. | GitHub Personal Access Token with the `repo` scope assigned. |
79+
| `ec2-image-id` | Required if you use the `start` mode. | EC2 Image Id (AMI). <br><br> The new runner will be launched from this image. The action is compatible only with Linux images. |
80+
| `ec2-instance-type` | Required if you use the `start` mode. | EC2 Instance Type. |
81+
| `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. |
82+
| `security-group-id` | Required if you use the `start` mode. | EC2 Security Group Id. <br><br> The security group should belong to the same VPC as the specified subnet. <br><br> The runner doesn't require any inbound traffic. However, outbound traffic should be allowed. |
83+
| `label` | Required if you use the `stop` mode. | Name of the unique label assigned to the runner. <br><br> The label is used to remove the runner from GitHub when the runner is not needed anymore. |
84+
| `ec2-instance-id` | Required if you use the `stop` mode. | EC2 Instance Id of the created runner. <br><br> The id is used to terminate the EC2 instance when the runner is not needed anymore. |
2885

2986
### Environment variables
3087

@@ -39,18 +96,14 @@ We recommend using [aws-actions/configure-aws-credentials](https://github.com/aw
3996

4097
### Outputs
4198

42-
| Name | Description |
43-
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44-
| `label` | Name of the unique label assigned to the runner. <br><br> The label is used in two cases: <br> - to use as the input of `runs-on` property for the following jobs; <br> - to remove the runner from GitHub when it is not needed anymore. |
45-
| `ec2-instance-id` | EC2 Instance Id of the created runner. <br><br> The id is used to terminate the EC2 instance when the runner is not needed anymore. |
99+
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Description |
100+
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
101+
| `label` | Name of the unique label assigned to the runner. <br><br> The label is used in two cases: <br> - to use as the input of `runs-on` property for the following jobs; <br> - to remove the runner from GitHub when it is not needed anymore. |
102+
| `ec2-instance-id` | EC2 Instance Id of the created runner. <br><br> The id is used to terminate the EC2 instance when the runner is not needed anymore. |
46103

47104
### Example
48105

49-
In the following example, you can see how to start your EC2 self-hosted runner right before the job should be done, run the job on it, and then stop it at the end when you finish:
50-
51-
![GitHub Actions self-hosted EC2 runner](docs/images/github-actions-summary.png)
52-
53-
The workflow, declared in `.github/workflows/do-the-job.yml`, looks like this:
106+
The workflow showed in the picture above and declared in `do-the-job.yml` looks like this:
54107

55108
```yml
56109
name: do-the-job
@@ -64,14 +117,14 @@ jobs:
64117
ec2-instance-id: ${{ steps.start-ec2-runner.outputs.ec2-instance-id }}
65118
steps:
66119
- name: Configure AWS credentials
67-
uses: aws-actions/configure-aws-credentials@v1.0.0
120+
uses: aws-actions/configure-aws-credentials@v1
68121
with:
69122
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
70123
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
71124
aws-region: ${{ secrets.AWS_REGION }}
72125
- name: Start EC2 runner
73126
id: start-ec2-runner
74-
uses: machulav/ec2-github-runner@v1
127+
uses: machulav/ec2-github-runner@v1.0.0
75128
with:
76129
mode: start
77130
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
@@ -80,7 +133,7 @@ jobs:
80133
subnet-id: subnet-123
81134
security-group-id: sg-123
82135
do-the-job:
83-
name: Do the job
136+
name: Do the job on the runner
84137
runs-on: ${{ needs.start-runner.outputs.label }} # run the job on the newly created runner
85138
needs: start-runner # required to start the main job when the runner is ready
86139
steps:
@@ -90,8 +143,8 @@ jobs:
90143
name: Stop self-hosted EC2 runner
91144
runs-on: ubuntu-latest
92145
needs:
93-
- start-runner # required to get output from the job in this job
94-
- do-the-job # required to remove the runner when the main job is done
146+
- start-runner # required to get output from the start-runner job
147+
- do-the-job # required to wait when the main job is done
95148
steps:
96149
- name: Configure AWS credentials
97150
uses: aws-actions/configure-aws-credentials@v1
@@ -108,6 +161,14 @@ jobs:
108161
ec2-instance-id: ${{ needs.start-runner.outputs.ec2-instance-id }}
109162
```
110163
164+
## Self-hosted runner security with public repositories
165+
166+
We recommend that you do not use self-hosted runners with public repositories.
167+
168+
Forks of your public repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow.
169+
170+
Please find more details about this security note on [GitHub documentation](https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories).
171+
111172
## License Summary
112173
113-
This code is made available under the MIT license.
174+
This code is made available under the [MIT license](LICENSE).

‎action.yml

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
name: On-demand self-hosted EC2 runner for GitHub Actions
2-
description: GitHub Action for automatic creation and registration EC2 instance as a GitHub Actions self-hosted runner.
1+
name: On-demand self-hosted AWS EC2 runner for GitHub Actions
2+
description: GitHub Action for automatic creation and registration AWS EC2 instance as a GitHub Actions self-hosted runner.
33
author: Volodymyr Machula
44
branding:
55
icon: 'box'
@@ -13,11 +13,11 @@ inputs:
1313
required: true
1414
github-token:
1515
description: >-
16-
GitHub Personal Access Token with a 'repo' scope assigned.
16+
GitHub Personal Access Token with the 'repo' scope assigned.
1717
required: true
1818
ec2-image-id:
1919
description: >-
20-
EC2 AMI Id. The new runner will be launched from this image.
20+
EC2 Image Id (AMI). The new runner will be launched from this image.
2121
This input is required if you use the 'start' mode.
2222
required: false
2323
ec2-instance-type:

‎docs/images/github-actions-summary.png

-1.63 KB
Loading

‎package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "ec2-github-runner",
3-
"description": "GitHub Action for automatic creation and registration EC2 instance as a GitHub Actions self-hosted runner.",
3+
"description": "GitHub Action for automatic creation and registration AWS EC2 instance as a GitHub Actions self-hosted runner.",
44
"author": "Volodymyr Machula",
55
"license": "MIT",
66
"repository": {

0 commit comments

Comments
 (0)