TypeScript GitHub Action template

Intro

Hello! My name is Yevhen. At the moment when I am writing this post I already have 18 GitHub actions that I've implemented and published to the marketplace. A few of them are Docker container actions, some of them are JavaScript actions but personally I like TypeScript more than JavaScript for various reasons, so that's why most of the implemented GitHub actions are TypeScript 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 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 for logging, husky for git hooks, 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

Is it useful?

Yes. And I am saying that not because I wrote this template 😅 but because I've already used it for one of my action - ICQ Notify 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:

$ 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.

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. - 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).
  • 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 library. Code example:

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

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

Output:

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 shows tests coverage and maintainability for your project.
• Snyk for security testing.
• LGTM for tracking code quality.

CI

• Security tests using Snyk and CodeQL.
• 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. If you need different license please choose the one that you need 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.

More information here.

Finalizing

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

Thank you for reading and happy coding!