Building Custom GitHub Actions with JavaScript

While most developers rely on pre-built actions from the GitHub Marketplace, truly advanced teams create their own internal toolkits. JavaScript Actions allow you to write custom automation logic using Node.js. They execute faster than Docker actions and have direct access to the GitHub API, making them the perfect choice for complex repo management, custom reporting, and specialized deployment logic.

Why Build a Custom Action?
The Three Components of an Action
Step 1: Defining 'action.yml'
Step 2: Writing the Node.js Logic
Step 3: Compiling with NCC
Testing Your Action Locally
Frequently Asked Questions
Key Takeaway

Why Build a Custom Action?

If your workflow requires:

Complex string manipulation or data processing.
Multi-step interactions with the GitHub API (like auto-tagging certain users).
Logic that needs to be reused across 50 different repositories.

...then a simple shell script inside your YAML is no longer sufficient. JavaScript actions provide a professional, version-controlled, and testable way to package that logic.

The Three Components of an Action

A custom JavaScript action consists of three mandatory files:

action.yml: The metadata file that defines the inputs, outputs, and entrypoint.
package.json: Standard Node.js dependency management.
index.js: The actual JavaScript code that performs the automation.

Step 1: Defining 'action.yml'

This file tells GitHub what your action expects from the user.

yaml

Step 2: Writing the Node.js Logic

To interact with GitHub Actions, you should use the official Actions Toolbelt (@actions/core and @actions/github).

javascript

Step 3: Compiling with NCC

GitHub Actions runners don't run npm install for your custom action. They expect a single, self-contained JavaScript file that includes all its dependencies.

The industry standard for this is @vercel/ncc. It compiles your entire project into a single dist/index.js file.

Install ncc: npm i -g @vercel/ncc
Compile: ncc build index.js -o dist --minify
Commit the dist/ folder to your repository.

Testing Your Action Locally

You can test your custom action using a standard workflow file in the same repository:

yaml

Frequently Asked Questions

Can I use TypeScript? Yes! Most professional actions are written in TypeScript for better type safety. You simply use a build step (like tsc or ncc) to transpile it to JavaScript before pushing.

Where should I host my custom actions? If it's a generic utility, you can create a dedicated repository and publish it to the GitHub Marketplace. If it's a private company tool, you can keep it in a private repo and call it via uses: my-org/my-private-action@main.

Key Takeaway

Custom JavaScript actions are the ultimate power tool for DevOps engineers. By modularizing your recurring automation logic into reusable Node.js packages, you ensure that your CI/CD pipelines are clean, highly maintainable, and deeply integrated with the GitHub ecosystem.

Building Custom GitHub Actions with JavaScript