TypeScript GitHub Action template
Tags: typescript, github, githubaction, ci
Published: 2021-02-07 23:47:34

## Intro

Hello! My name is Yevhen. At the moment when I am writing this post I already have [18 GitHub actions](https://github.com/marketplace?type=actions&query=fabasoad) that I've implemented and published to the marketplace. A few of them are [Docker container actions](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action), some of them are [JavaScript actions](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action) but personally I like TypeScript more than JavaScript for various reasons, so that's why most of the implemented GitHub actions are [TypeScript](https://www.typescriptlang.org/) actions.

So, after 1, 2, `n` implemeted TypeScript GitHub actions I found out that I do a boilerplate work again and again - I configure CI with the same pipelines and jobs, I configure tests with coverage and TypeScript, I configure npm with the commands that I usually use, etc. All this boilerplate work became a big part of the building GitHub Action itself. So, I've decided to find the way to somehow avoid doing boilerplate work and focus more on a business logic. After some investigation I found nice [actions/typescript-action](https://github.com/actions/typescript-action) template that basically can help developers like me to build TypeScript GitHub Action with some preconfigured settings. This is already better than nothing but personally for my needs that wasn't enough. For example, there are some set of pipelines that I use in almost all my GitHub actions repositories (like, "Create release", "Check updates", "Security tests, "Unit tests", etc.). I always use my personal settings for linters and tests. I always use some libraries that I used to work with, like [winston](https://www.npmjs.com/package/winston) for logging, [husky](https://www.npmjs.com/package/husky) for [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks), [snyk](https://www.npmjs.com/package/snyk) for security testing, etc. So even though I will use `actions/typescript-action` template - it is not enough for me because I have to do some boilerplate work anyway.

So, I've decided to prepare my personal TypeScript GitHub Action template with the 3 main goals:

- It is easy to configure.
- `0` boilerplate work.
- It is useful for me _and_ for other developers.

## fabasoad/typescript-action

As a result I've built such template that hopefully meets all the requirements (tickets and PRs are welcome, so don't hesitate to open a ticket or PR in case you found any bug or have an idea of enhancements).

Link: [fabasoad/typescript-action](https://github.com/fabasoad/typescript-action)

## Is it useful?

Yes. And I am saying that not because I wrote this template :sweat_smile: but because I've already used it for one of my action - [ICQ Notify](https://github.com/fabasoad/icq-notify-action) action. I configured the project in 5 minutes and then was focusing on a business logic without thinking about CI, npm, git hooks and other stuff that I usually configured manually. I already found this template super useful for myself and will be definitely using it (and improving it) in a future.

## How to use

I've decided to prepare a `Makefile` that will do all the job for you, like preparing namings, folder structures, etc. This `Makefile` has the single `default` command and this is what you need to run:

```bash
$ make
```

And that's it. Just answer the question in interactive mode, enter the name of your GitHub Action, author name, etc. and in the end you will see fully configured and ready to implement GitHub action repository.

> More information [here](https://github.com/fabasoad/typescript-action/wiki/How-to-use).

## What you will have out of the box

### GitHub action file

- Configured action file without any inputs or outputs. Feel free to add those if needed. More information [here](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions). _- I didn't add those because it really depends on a business logic of GitHub Action, some of them might have inputs/outputs but some of them might not have, so I've decided to leave it without these fields and developer will add them if needed_
- The following default values:
  - Branding icon is `terminal`.
  - Branding color is `gray-dark` (you can check these values [here](https://haya14busa.github.io/github-action-brandings/)).
  - Runs on `node12`.
  - `name`, `author` and `description` are based on your input during `make` run.

### Source code

- `index.ts` file with basic code. All what you need to do is to start adding your code under the `// Your main code here` comment.
- Logging mechanism that you can use in your code. It is using [winston](https://www.npmjs.com/package/winston) library. Code example:

```typescript
import { Logger } from 'winston'
import LoggerFactory from './LoggerFactory'

const log: Logger = LoggerFactory.create('index.ts')
log.info('Hello world!')
```

Output:

```bash
2021-02-07 02:48:03 [index.ts] info: Hello world!
```

### npm

The following npm targets that you can use:

| `npm` target    | Description                                                      |
|-----------------|------------------------------------------------------------------|
| `build`         | Build your source code into bundle that is used by GitHub Action |
| `lint:md`       | Run markdown lint checking                                       |
| `lint:es`       | Run `eslint` checking                                            |
| `lint`          | Run both `lint:md` and `lint:es` targets                         |
| `postinstall`   | Install `git` hooks using `husky`                                |
| `prepare`       | Run `snyk-protect` target                                        |
| `security:auth` | Run authentication to `snyk` (token should be provided)          |
| `security:test` | Run security tests using `snyk`                                  |
| `snyk-protect`  | Reads `.snyk` policy file to determine what patches to apply     |
| `test`          | Run unit tests using `jest`                                      |

### Tests

- Configured `jest` library with coverage threshold (`80%` by default).
- Coverage tests folder structure with basic test as a start.

### Integrations

- [CodeClimate](https://codeclimate.com/) shows tests coverage and maintainability for your project.
- [Snyk](https://snyk.io/) for security testing.
- [LGTM](https://lgtm.com/) for tracking code quality.

### CI

- `Security tests` using [Snyk](https://snyk.io) and [CodeQL](https://github.com/github/codeql-action).
- `Check updates` pipeline twice a month checks `npm` updates and creates PR automatically in case of any new versions are exist.
- `Create release` pipeline that will create a new release when you merge your MR into `main` branch.
- `Unit tests` pipeline that will run `lint` and `test` commands on each push to `main`, `feature/*` or `bugfix/*` branches.
- `Lint` pipeline that has 2 jobs - `YAML Lint` and `Markdown Lint`. Both are running on each `push` to any branch.

### GitHub files

- `PR`, `Bug report` and `Feature request` GitHub templates.
- `README`, `LICENSE` and `Contributing` documentation files. _- Default LICENSE is [MIT](https://opensource.org/licenses/MIT). If you need different license please [choose the one that you need](https://choosealicense.com/) and replace the `LICENSE` file_

### git

- `git` hooks:
  - checking that you're **not** committing into `main` branch.
  - checking that you're **not** committing any sensitive information.
  - running `lint` and `test` commands on each `git push`.
  - building bundle (`dist/index.js`) file (that is used as a main file for GitHub Action) on each `git commit`. So don't worry if you forget to build a bundle on top of your latest changes - this hook will do that for you.
- `.gitignore` file with basic patterns.

### IDE settings

- VS Code settings file that have some basic settings for easier development.

### Badges in README

- 10 badges that shows the latest release, result of passing pipelines and results from [integrations](#integrations).

> More information [here](https://github.com/fabasoad/typescript-action/wiki/What-you-will-have-out-of-the-box).

## Finalizing

This project has [wiki](https://github.com/fabasoad/typescript-action/wiki) with the detailed explanations of benefits and how to use it. Also, it has [discussions](https://github.com/fabasoad/typescript-action/discussions) section, so feel free to open discussions. Contributions are also welcome! So, either it's [bug report](https://github.com/fabasoad/typescript-action/issues/new/choose), [feature request](https://github.com/fabasoad/typescript-action/issues/new/choose) or [PR](https://github.com/fabasoad/typescript-action/pulls), I would be happy to see your activities there. I hope someone will find [fabasoad/typescript-action](https://github.com/fabasoad/typescript-action) template useful as well.

Thank you for reading and happy coding!