|
| 1 | +# Create a GitHub Action Using TypeScript |
| 2 | + |
| 3 | +[](https://github.com/super-linter/super-linter) |
| 4 | + |
| 5 | +[](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml) |
| 6 | +[](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml) |
| 7 | +[](./badges/coverage.svg) |
| 8 | + |
| 9 | +Use this template to bootstrap the creation of a TypeScript action. :rocket: |
| 10 | + |
| 11 | +This template includes compilation support, tests, a validation workflow, |
| 12 | +publishing, and versioning guidance. |
| 13 | + |
| 14 | +If you are new, there's also a simpler introduction in the |
| 15 | +[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action). |
| 16 | + |
| 17 | +## Create Your Own Action |
| 18 | + |
| 19 | +To create your own action, you can use this repository as a template! Just |
| 20 | +follow the below instructions: |
| 21 | + |
| 22 | +1. Click the **Use this template** button at the top of the repository |
| 23 | +1. Select **Create a new repository** |
| 24 | +1. Select an owner and name for your new repository |
| 25 | +1. Click **Create repository** |
| 26 | +1. Clone your new repository |
| 27 | + |
| 28 | +> [!IMPORTANT] |
| 29 | +> |
| 30 | +> Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For |
| 31 | +> details on how to use this file, see |
| 32 | +> [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). |
| 33 | +
|
| 34 | +## Initial Setup |
| 35 | + |
| 36 | +After you've cloned the repository to your local machine or codespace, you'll |
| 37 | +need to perform some initial setup steps before you can develop your action. |
| 38 | + |
| 39 | +> [!NOTE] |
| 40 | +> |
| 41 | +> You'll need to have a reasonably modern version of |
| 42 | +> [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are |
| 43 | +> using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or |
| 44 | +> [`fnm`](https://github.com/Schniz/fnm), this template has a `.node-version` |
| 45 | +> file at the root of the repository that can be used to automatically switch to |
| 46 | +> the correct version when you `cd` into the repository. Additionally, this |
| 47 | +> `.node-version` file is used by GitHub Actions in any `actions/setup-node` |
| 48 | +> actions. |
| 49 | +
|
| 50 | +1. :hammer_and_wrench: Install the dependencies |
| 51 | + |
| 52 | + ```bash |
| 53 | + npm install |
| 54 | + ``` |
| 55 | + |
| 56 | +1. :building_construction: Package the TypeScript for distribution |
| 57 | + |
| 58 | + ```bash |
| 59 | + npm run bundle |
| 60 | + ``` |
| 61 | + |
| 62 | +1. :white_check_mark: Run the tests |
| 63 | + |
| 64 | + ```bash |
| 65 | + $ npm test |
| 66 | + |
| 67 | + PASS ./index.test.js |
| 68 | + ✓ throws invalid number (3ms) |
| 69 | + ✓ wait 500 ms (504ms) |
| 70 | + ✓ test runs (95ms) |
| 71 | + |
| 72 | + ... |
| 73 | + ``` |
| 74 | + |
| 75 | +## Update the Action Metadata |
| 76 | + |
| 77 | +The [`action.yml`](action.yml) file defines metadata about your action, such as |
| 78 | +input(s) and output(s). For details about this file, see |
| 79 | +[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions). |
| 80 | + |
| 81 | +When you copy this repository, update `action.yml` with the name, description, |
| 82 | +inputs, and outputs for your action. |
| 83 | + |
| 84 | +## Update the Action Code |
| 85 | + |
| 86 | +The [`src/`](./src/) directory is the heart of your action! This contains the |
| 87 | +source code that will be run when your action is invoked. You can replace the |
| 88 | +contents of this directory with your own code. |
| 89 | + |
| 90 | +There are a few things to keep in mind when writing your action code: |
| 91 | + |
| 92 | +- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously. |
| 93 | + In `main.ts`, you will see that the action is run in an `async` function. |
| 94 | + |
| 95 | + ```javascript |
| 96 | + import * as core from '@actions/core' |
| 97 | + //... |
| 98 | + |
| 99 | + async function run() { |
| 100 | + try { |
| 101 | + //... |
| 102 | + } catch (error) { |
| 103 | + core.setFailed(error.message) |
| 104 | + } |
| 105 | + } |
| 106 | + ``` |
| 107 | + |
| 108 | + For more information about the GitHub Actions toolkit, see the |
| 109 | + [documentation](https://github.com/actions/toolkit/blob/master/README.md). |
| 110 | + |
| 111 | +So, what are you waiting for? Go ahead and start customizing your action! |
| 112 | + |
| 113 | +1. Create a new branch |
| 114 | + |
| 115 | + ```bash |
| 116 | + git checkout -b releases/v1 |
| 117 | + ``` |
| 118 | + |
| 119 | +1. Replace the contents of `src/` with your action code |
| 120 | +1. Add tests to `__tests__/` for your source code |
| 121 | +1. Format, test, and build the action |
| 122 | + |
| 123 | + ```bash |
| 124 | + npm run all |
| 125 | + ``` |
| 126 | + |
| 127 | + > This step is important! It will run [`rollup`](https://rollupjs.org/) to |
| 128 | + > build the final JavaScript action code with all dependencies included. If |
| 129 | + > you do not run this step, your action will not work correctly when it is |
| 130 | + > used in a workflow. |
| 131 | +
|
| 132 | +1. (Optional) Test your action locally |
| 133 | + |
| 134 | + The [`@github/local-action`](https://github.com/github/local-action) utility |
| 135 | + can be used to test your action locally. It is a simple command-line tool |
| 136 | + that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run |
| 137 | + your TypeScript action locally without having to commit and push your changes |
| 138 | + to a repository. |
| 139 | + |
| 140 | + The `local-action` utility can be run in the following ways: |
| 141 | + |
| 142 | + - Visual Studio Code Debugger |
| 143 | + |
| 144 | + Make sure to review and, if needed, update |
| 145 | + [`.vscode/launch.json`](./.vscode/launch.json) |
| 146 | + |
| 147 | + - Terminal/Command Prompt |
| 148 | + |
| 149 | + ```bash |
| 150 | + # npx local action <action-yaml-path> <entrypoint> <dotenv-file> |
| 151 | + npx local-action . src/main.ts .env |
| 152 | + ``` |
| 153 | + |
| 154 | + You can provide a `.env` file to the `local-action` CLI to set environment |
| 155 | + variables used by the GitHub Actions Toolkit. For example, setting inputs and |
| 156 | + event payload data used by your action. For more information, see the example |
| 157 | + file, [`.env.example`](./.env.example), and the |
| 158 | + [GitHub Actions Documentation](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables). |
| 159 | + |
| 160 | +1. Commit your changes |
| 161 | + |
| 162 | + ```bash |
| 163 | + git add . |
| 164 | + git commit -m "My first action is ready!" |
| 165 | + ``` |
| 166 | + |
| 167 | +1. Push them to your repository |
| 168 | + |
| 169 | + ```bash |
| 170 | + git push -u origin releases/v1 |
| 171 | + ``` |
| 172 | + |
| 173 | +1. Create a pull request and get feedback on your action |
| 174 | +1. Merge the pull request into the `main` branch |
| 175 | + |
| 176 | +Your action is now published! :rocket: |
| 177 | + |
| 178 | +For information about versioning your action, see |
| 179 | +[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
| 180 | +in the GitHub Actions toolkit. |
| 181 | + |
| 182 | +## Validate the Action |
| 183 | + |
| 184 | +You can now validate the action by referencing it in a workflow file. For |
| 185 | +example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an |
| 186 | +action in the same repository. |
| 187 | + |
| 188 | +```yaml |
| 189 | +steps: |
| 190 | + - name: Checkout |
| 191 | + id: checkout |
| 192 | + uses: actions/checkout@v4 |
| 193 | +
|
| 194 | + - name: Test Local Action |
| 195 | + id: test-action |
| 196 | + uses: ./ |
| 197 | + with: |
| 198 | + milliseconds: 1000 |
| 199 | +
|
| 200 | + - name: Print Output |
| 201 | + id: output |
| 202 | + run: echo "${{ steps.test-action.outputs.time }}" |
| 203 | +``` |
| 204 | + |
| 205 | +For example workflow runs, check out the |
| 206 | +[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket: |
| 207 | + |
| 208 | +## Usage |
| 209 | + |
| 210 | +After testing, you can create version tag(s) that developers can use to |
| 211 | +reference different stable versions of your action. For more information, see |
| 212 | +[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) |
| 213 | +in the GitHub Actions toolkit. |
| 214 | + |
| 215 | +To include the action in a workflow in another repository, you can use the |
| 216 | +`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit |
| 217 | +hash. |
| 218 | + |
| 219 | +```yaml |
| 220 | +steps: |
| 221 | + - name: Checkout |
| 222 | + id: checkout |
| 223 | + uses: actions/checkout@v4 |
| 224 | +
|
| 225 | + - name: Test Local Action |
| 226 | + id: test-action |
| 227 | + uses: actions/typescript-action@v1 # Commit with the `v1` tag |
| 228 | + with: |
| 229 | + milliseconds: 1000 |
| 230 | +
|
| 231 | + - name: Print Output |
| 232 | + id: output |
| 233 | + run: echo "${{ steps.test-action.outputs.time }}" |
| 234 | +``` |
| 235 | + |
| 236 | +## Publishing a New Release |
| 237 | + |
| 238 | +This project includes a helper script, [`script/release`](./script/release) |
| 239 | +designed to streamline the process of tagging and pushing new releases for |
| 240 | +GitHub Actions. |
| 241 | + |
| 242 | +GitHub Actions allows users to select a specific version of the action to use, |
| 243 | +based on release tags. This script simplifies this process by performing the |
| 244 | +following steps: |
| 245 | + |
| 246 | +1. **Retrieving the latest release tag:** The script starts by fetching the most |
| 247 | + recent SemVer release tag of the current branch, by looking at the local data |
| 248 | + available in your repository. |
| 249 | +1. **Prompting for a new release tag:** The user is then prompted to enter a new |
| 250 | + release tag. To assist with this, the script displays the tag retrieved in |
| 251 | + the previous step, and validates the format of the inputted tag (vX.X.X). The |
| 252 | + user is also reminded to update the version field in package.json. |
| 253 | +1. **Tagging the new release:** The script then tags a new release and syncs the |
| 254 | + separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0, |
| 255 | + v2.1.2). When the user is creating a new major release, the script |
| 256 | + auto-detects this and creates a `releases/v#` branch for the previous major |
| 257 | + version. |
| 258 | +1. **Pushing changes to remote:** Finally, the script pushes the necessary |
| 259 | + commits, tags and branches to the remote repository. From here, you will need |
| 260 | + to create a new release in GitHub so users can easily reference the new tags |
| 261 | + in their workflows. |
0 commit comments