Skip to content

Commit 7d48b51

Browse files
machulavmachulav
committedDec 21, 2020
Update the action's code and docs
·
v2.3.9v1.0.0
1 parent 2fdcdf7 commit 7d48b51

15 files changed

+18323
-37775
lines changed
 

‎.env.example

+9-9
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,17 @@
55
#
66
# - Use environment variables with prefix "AWS_" to give access to your test AWS account.
77
# - Use environment variables with prefix "INPUT_" to simulate GitHub Actions input.
8-
# - Use environment variables with prefix "STATE_" to simulate GitHub Actions state.
98
# - Use GITHUB_REPOSITORY environment variable to provide the GitHub repository and it's owher as a context in the script. Use formst "owner/repo".
109

1110
AWS_ACCESS_KEY_ID=
1211
AWS_SECRET_ACCESS_KEY=
1312
AWS_REGION=
14-
INPUT_GITHUB_TOKEN=
15-
INPUT_EC2_IMAGE_ID=
16-
INPUT_EC2_INSTANCE_TYPE=
17-
INPUT_SUBNET_ID=
18-
INPUT_SECURITY_GROUP_ID=
19-
STATE_EC2_INSTANCE_ID=
20-
STATE_LABEL=
21-
GITHUB_REPOSITORY=
13+
INPUT_MODE=
14+
INPUT_GITHUB-TOKEN=
15+
INPUT_EC2-IMAGE-ID=
16+
INPUT_EC2-INSTANCE-TYPE=
17+
INPUT_SUBNET-ID=
18+
INPUT_SECURITY-GROUP-ID=
19+
INPUT_LABEL=
20+
INPUT_EC2-INSTANCE-ID=
21+
GITHUB_REPOSITORY=

‎.eslintrc.yml

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
env:
2-
commonjs: true
32
es6: true
43
node: true
54
jest: true
@@ -8,3 +7,6 @@ extends:
87
parserOptions:
98
ecmaVersion: 2018
109
sourceType: module
10+
rules:
11+
no-use-before-define: error
12+
prefer-const: error

‎.vscode/launch.json

-8
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,6 @@
88
"cwd": "${workspaceFolder}",
99
"runtimeExecutable": "npm",
1010
"runtimeArgs": ["run-script", "index"]
11-
},
12-
{
13-
"name": "debug cleanup",
14-
"type": "node",
15-
"request": "launch",
16-
"cwd": "${workspaceFolder}",
17-
"runtimeExecutable": "npm",
18-
"runtimeArgs": ["run-script", "cleanup"]
1911
}
2012
]
2113
}

‎README.md

+108-6
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,113 @@
1-
# (In Progress) "aws-github-runner" action for GitHub Actions
1+
# On-demand self-hosted EC2 runner for GitHub Actions
22

3-
Create an on-demand AWS EC2 instance and register it as a self-hosted GitHub Actions runner for your GitHub repository.
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.
44

5-
The runner is automatically started when the GitHub Actions workflow starts, runs all your jobs and is removed after the work is done.
5+
**Table of Contents**
66

7-
# Notes
7+
- [Usage](#usage)
8+
- [Inputs](#inputs)
9+
- [Environment variables](#environment-variables)
10+
- [Outputs](#outputs)
11+
- [Example](#example)
12+
- [License Summary](#license-summary)
813

9-
## GitHub Secret Token
14+
## Usage
1015

11-
Your GitHub Secret Token should have `repo` scope assigned.
16+
### Inputs
17+
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. |
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. |
28+
29+
### Environment variables
30+
31+
In addition to the inputs described above, the action also requires the following environment variables to access your AWS account:
32+
33+
- `AWS_DEFAULT_REGION`
34+
- `AWS_REGION`
35+
- `AWS_ACCESS_KEY_ID`
36+
- `AWS_SECRET_ACCESS_KEY`
37+
38+
We recommend using [aws-actions/configure-aws-credentials](https://github.com/aws-actions/configure-aws-credentials) action right before running the step for creating a self-hosted runner. This action perfectly does the job of setting the required environment variables.
39+
40+
### Outputs
41+
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. |
46+
47+
### Example
48+
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:
54+
55+
```yml
56+
name: do-the-job
57+
on: pull_request
58+
jobs:
59+
start-runner:
60+
name: Start self-hosted EC2 runner
61+
runs-on: ubuntu-latest
62+
outputs:
63+
label: ${{ steps.start-ec2-runner.outputs.label }}
64+
ec2-instance-id: ${{ steps.start-ec2-runner.outputs.ec2-instance-id }}
65+
steps:
66+
- name: Configure AWS credentials
67+
uses: aws-actions/configure-aws-credentials@v1
68+
with:
69+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
70+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
71+
aws-region: ${{ secrets.AWS_REGION }}
72+
- name: Start EC2 runner
73+
id: start-ec2-runner
74+
uses: machulav/ec2-github-runner@main
75+
with:
76+
mode: start
77+
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
78+
ec2-image-id: ami-123
79+
ec2-instance-type: t3.nano
80+
subnet-id: subnet-123
81+
security-group-id: sg-123
82+
do-the-job:
83+
name: Do the job
84+
runs-on: ${{ needs.start-runner.outputs.label }} # run the job on the newly created runner
85+
needs: start-runner # required to start the main job when the runner is ready
86+
steps:
87+
- name: Hello World
88+
run: echo 'Hello World!'
89+
stop-runner:
90+
name: Stop self-hosted EC2 runner
91+
runs-on: ubuntu-latest
92+
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
95+
steps:
96+
- name: Configure AWS credentials
97+
uses: aws-actions/configure-aws-credentials@v1
98+
with:
99+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
100+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
101+
aws-region: ${{ secrets.AWS_REGION }}
102+
- name: Stop EC2 runner
103+
uses: machulav/aws-github-runner@main
104+
with:
105+
mode: stop
106+
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
107+
label: ${{ needs.start-runner.outputs.label }}
108+
ec2-instance-id: ${{ needs.start-runner.outputs.ec2-instance-id }}
109+
```
110+
111+
## License Summary
112+
113+
This code is made available under the MIT license.

‎action.yml

+53-17
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,62 @@
1-
name: aws-github-runner-action
2-
description: GitHub Action for automatic EC2 instance creation and registering it as a self-hosted GitHub Actions runner
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.
33
author: Volodymyr Machula
44
inputs:
5-
github_token:
6-
description: GitHub Secret Token with a 'repo' scope assigned
5+
mode:
6+
description: >-
7+
Specify here which mode you want to use:
8+
- 'start' - to start a new runner;
9+
- 'stop' - to stop the previously created runner.
710
required: true
8-
ec2_image_id:
9-
description: '' # TODO, possible values: start, stop
10-
required: true
11-
ec2_instance_type:
12-
description: '' # TODO, possible values: start, stop
13-
required: true
14-
subnet_id:
15-
description: '' # TODO, possible values: start, stop
16-
required: true
17-
security_group_id:
18-
description: '' # TODO, possible values: start, stop
11+
github-token:
12+
description: >-
13+
GitHub Personal Access Token with a 'repo' scope assigned.
1914
required: true
15+
ec2-image-id:
16+
description: >-
17+
EC2 AMI Id. The new runner will be launched from this image.
18+
This input is required if you use the 'start' mode.
19+
required: false
20+
ec2-instance-type:
21+
description: >-
22+
EC2 Instance Type.
23+
This input is required if you use the 'start' mode.
24+
required: false
25+
subnet-id:
26+
description: >-
27+
VPC Subnet Id. The subnet should belong to the same VPC as the specified security group.
28+
This input is required if you use the 'start' mode.
29+
required: false
30+
security-group-id:
31+
description: >-
32+
EC2 Security Group Id.
33+
The security group should belong to the same VPC as the specified subnet.
34+
The runner doesn't require any inbound traffic. However, outbound traffic should be allowed.
35+
This input is required if you use the 'start' mode.
36+
required: false
37+
label:
38+
description: >-
39+
Name of the unique label assigned to the runner.
40+
The label is used to remove the runner from GitHub when the runner is not needed anymore.
41+
This input is required if you use the 'stop' mode.
42+
required: false
43+
ec2-instance-id:
44+
description: >-
45+
EC2 Instance Id of the created runner.
46+
The id is used to terminate the EC2 instance when the runner is not needed anymore.
47+
This input is required if you use the 'stop' mode.
48+
required: false
2049
outputs:
2150
label:
22-
description: '' # TODO
51+
description: >-
52+
Name of the unique label assigned to the runner.
53+
The label is used in two cases:
54+
- to use as the input of 'runs-on' property for the following jobs;
55+
- to remove the runner from GitHub when it is not needed anymore.
56+
ec2-instance-id:
57+
description: >-
58+
EC2 Instance Id of the created runner.
59+
The id is used to terminate the EC2 instance when the runner is not needed anymore.
2360
runs:
2461
using: node12
2562
main: ./dist/index.js
26-
post: ./dist/cleanup/index.js

0 commit comments

Comments
 (0)