|
1 |
| -# Create a JavaScript Action Using TypeScript |
2 | 1 |
|
3 |
| -[](https://github.com/super-linter/super-linter) |
4 |
| - |
| 2 | +## GitHub Action: Setup Elide |
5 | 3 |
|
6 |
| -Use this template to bootstrap the creation of a TypeScript action. :rocket: |
| 4 | +This repository provides a [GitHub Action][0] to setup the [Elide][1] runtime within your workflows. |
7 | 5 |
|
8 |
| -This template includes compilation support, tests, a validation workflow, |
9 |
| -publishing, and versioning guidance. |
10 |
| - |
11 |
| -If you are new, there's also a simpler introduction in the |
12 |
| -[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action). |
13 |
| - |
14 |
| -## Create Your Own Action |
15 |
| - |
16 |
| -To create your own action, you can use this repository as a template! Just |
17 |
| -follow the below instructions: |
18 |
| - |
19 |
| -1. Click the **Use this template** button at the top of the repository |
20 |
| -1. Select **Create a new repository** |
21 |
| -1. Select an owner and name for your new repository |
22 |
| -1. Click **Create repository** |
23 |
| -1. Clone your new repository |
24 |
| - |
25 |
| -## Initial Setup |
26 |
| - |
27 |
| -After you've cloned the repository to your local machine or codespace, you'll |
28 |
| -need to perform some initial setup steps before you can develop your action. |
29 |
| - |
30 |
| -> [!NOTE] |
31 |
| -> |
32 |
| -> You'll need to have a reasonably modern version of |
33 |
| -> [Node.js](https://nodejs.org) handy. If you are using a version manager like |
34 |
| -> [`nodenv`](https://github.com/nodenv/nodenv) or |
35 |
| -> [`nvm`](https://github.com/nvm-sh/nvm), you can run `nodenv install` in the |
36 |
| -> root of your repository to install the version specified in |
37 |
| -> [`package.json`](./package.json). Otherwise, 20.x or later should work! |
38 |
| -
|
39 |
| -1. :hammer_and_wrench: Install the dependencies |
40 |
| - |
41 |
| - ```bash |
42 |
| - npm install |
43 |
| - ``` |
44 |
| - |
45 |
| -1. :building_construction: Package the TypeScript for distribution |
46 |
| - |
47 |
| - ```bash |
48 |
| - npm run bundle |
49 |
| - ``` |
50 |
| - |
51 |
| -1. :white_check_mark: Run the tests |
52 |
| - |
53 |
| - ```bash |
54 |
| - $ npm test |
55 |
| - |
56 |
| - PASS ./index.test.js |
57 |
| - ✓ throws invalid number (3ms) |
58 |
| - ✓ wait 500 ms (504ms) |
59 |
| - ✓ test runs (95ms) |
60 |
| - |
61 |
| - ... |
62 |
| - ``` |
63 |
| - |
64 |
| -## Update the Action Metadata |
65 |
| - |
66 |
| -The [`action.yml`](action.yml) file defines metadata about your action, such as |
67 |
| -input(s) and output(s). For details about this file, see |
68 |
| -[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions). |
69 |
| - |
70 |
| -When you copy this repository, update `action.yml` with the name, description, |
71 |
| -inputs, and outputs for your action. |
72 |
| - |
73 |
| -## Update the Action Code |
74 |
| - |
75 |
| -The [`src/`](./src/) directory is the heart of your action! This contains the |
76 |
| -source code that will be run when your action is invoked. You can replace the |
77 |
| -contents of this directory with your own code. |
78 |
| - |
79 |
| -There are a few things to keep in mind when writing your action code: |
80 |
| - |
81 |
| -- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously. |
82 |
| - In `main.ts`, you will see that the action is run in an `async` function. |
83 |
| - |
84 |
| - ```javascript |
85 |
| - import * as core from '@actions/core' |
86 |
| - //... |
87 |
| - |
88 |
| - async function run() { |
89 |
| - try { |
90 |
| - //... |
91 |
| - } catch (error) { |
92 |
| - core.setFailed(error.message) |
93 |
| - } |
94 |
| - } |
95 |
| - ``` |
96 |
| - |
97 |
| - For more information about the GitHub Actions toolkit, see the |
98 |
| - [documentation](https://github.com/actions/toolkit/blob/master/README.md). |
99 |
| - |
100 |
| -So, what are you waiting for? Go ahead and start customizing your action! |
101 |
| - |
102 |
| -1. Create a new branch |
103 |
| - |
104 |
| - ```bash |
105 |
| - git checkout -b releases/v1 |
106 |
| - ``` |
107 |
| - |
108 |
| -1. Replace the contents of `src/` with your action code |
109 |
| -1. Add tests to `__tests__/` for your source code |
110 |
| -1. Format, test, and build the action |
111 |
| - |
112 |
| - ```bash |
113 |
| - npm run all |
114 |
| - ``` |
115 |
| - |
116 |
| - > [!WARNING] |
117 |
| - > |
118 |
| - > This step is important! It will run [`ncc`](https://github.com/vercel/ncc) |
119 |
| - > to build the final JavaScript action code with all dependencies included. |
120 |
| - > If you do not run this step, your action will not work correctly when it is |
121 |
| - > used in a workflow. This step also includes the `--license` option for |
122 |
| - > `ncc`, which will create a license file for all of the production node |
123 |
| - > modules used in your project. |
124 |
| -
|
125 |
| -1. Commit your changes |
126 |
| - |
127 |
| - ```bash |
128 |
| - git add . |
129 |
| - git commit -m "My first action is ready!" |
130 |
| - ``` |
131 |
| - |
132 |
| -1. Push them to your repository |
133 |
| - |
134 |
| - ```bash |
135 |
| - git push -u origin releases/v1 |
136 |
| - ``` |
137 |
| - |
138 |
| -1. Create a pull request and get feedback on your action |
139 |
| -1. Merge the pull request into the `main` branch |
140 |
| - |
141 |
| -Your action is now published! :rocket: |
142 |
| - |
143 |
| -For information about versioning your action, see |
144 |
| -[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
145 |
| -in the GitHub Actions toolkit. |
146 |
| - |
147 |
| -## Validate the Action |
148 |
| - |
149 |
| -You can now validate the action by referencing it in a workflow file. For |
150 |
| -example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an |
151 |
| -action in the same repository. |
152 |
| - |
153 |
| -```yaml |
154 |
| -steps: |
155 |
| - - name: Checkout |
156 |
| - id: checkout |
157 |
| - uses: actions/checkout@v3 |
158 |
| - |
159 |
| - - name: Test Local Action |
160 |
| - id: test-action |
161 |
| - uses: ./ |
162 |
| - with: |
163 |
| - milliseconds: 1000 |
164 |
| - |
165 |
| - - name: Print Output |
166 |
| - id: output |
167 |
| - run: echo "${{ steps.test-action.outputs.time }}" |
168 |
| -``` |
169 |
| -
|
170 |
| -For example workflow runs, check out the |
171 |
| -[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket: |
172 |
| -
|
173 |
| -## Usage |
174 |
| -
|
175 |
| -After testing, you can create version tag(s) that developers can use to |
176 |
| -reference different stable versions of your action. For more information, see |
177 |
| -[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
178 |
| -in the GitHub Actions toolkit. |
179 |
| -
|
180 |
| -To include the action in a workflow in another repository, you can use the |
181 |
| -`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit |
182 |
| -hash. |
183 |
| - |
184 |
| -```yaml |
185 |
| -steps: |
186 |
| - - name: Checkout |
187 |
| - id: checkout |
188 |
| - uses: actions/checkout@v3 |
189 |
| -
|
190 |
| - - name: Test Local Action |
191 |
| - id: test-action |
192 |
| - uses: actions/typescript-action@v1 # Commit with the `v1` tag |
193 |
| - with: |
194 |
| - milliseconds: 1000 |
195 |
| - |
196 |
| - - name: Print Output |
197 |
| - id: output |
198 |
| - run: echo "${{ steps.test-action.outputs.time }}" |
199 |
| -``` |
| 6 | +[0]: https://github.com/features/actions |
| 7 | +[1]: https://elide.dev |
0 commit comments