How to Build a Custom GitHub Action: A Step-by-Step Developer Tutorial for 2026

You’ve written the same CI workflow for the fifth time this month. Copy-paste, tweak a few lines, pray it doesn’t break. Sound familiar?

Every team needs that one automation that doesn’t exist in the marketplace. Maybe it’s validating PR titles against your company’s convention. Maybe it’s cross-referencing Jira tickets with branch names. Or sending Slack notifications with deployment context.

Why You Should Hire Vietnamese Developers in 2025: A CTO’s Perspective

TL;DR Vietnam is emerging as a top destination for offshore development. Strong technical skills, competitive rates, and a… ...

Read more

Whatever it is, you don’t need another bloated third-party action. You need your own.

Here’s the thing: building a custom GitHub Action is easier than most developers think. And once you understand the mechanics, you’ll automate everything that slows your team down. Let’s walk through it.

Why Your Next Big Project Needs a Multi-Agent AI System Architecture (And How to Build One)

TL;DR: A multi-agent AI system architecture isn’t just a buzzword — it’s how you scale AI for complex,… ...

Read more

Why Build a Custom Action Instead of Using a Script?

I get asked this all the time. Why not just run a shell script in your workflow?

Context matters. A GitHub Action is a self-contained unit that can access the entire event payload, interact with the GitHub API, and produce rich outputs that other steps can consume. A script? It’s just a script. You’d have to parse environment variables, handle authentication manually, and pray the exit codes are correct.

Actions are reusable, versioned, and shareable across repos. That’s the whole point.

But let’s be real — most tutorials overcomplicate this. They throw in Docker containers, complex abstractions, and six different dependencies. We don’t need that. For 80% of use cases, a JavaScript/TypeScript action is all you need.

One of our senior engineers in Can Tho recently built an action for a US client that automatically adds a “size” label to PRs based on line changes. Took him two hours. The team now uses it across 12 repos. That’s the kind of leverage we’re talking about.

Prerequisites

• Node.js 20+ (or 22, if you’re living on the edge)
• A GitHub account (obviously)
• Basic familiarity with JavaScript/TypeScript
• A repo where you can test the action (can be private or public)

That’s it. No Docker. No bash wizardry.

Step 1: Scaffold Your Action Project

Let’s create the project structure:

bash
mkdir my-custom-action
cd my-custom-action
npm init -y

Install the official toolkit:

bash
npm install @actions/core @actions/github

`@actions/core` gives you logging, inputs/outputs, and error handling. `@actions/github` provides access to the GitHub context and Octokit client.

Now create the essential files:

my-custom-action/
├── action.yml
├── index.js
├── package.json
└── node_modules/

`action.yml` is the manifest. It defines your action’s metadata, inputs, and outputs. Here’s a minimal example for a PR title validator:

yaml
name: 'PR Title Validator'
description: 'Validate pull request title follows conventional commit format'
author: 'Your Name'
inputs:
  pattern:
    description: 'Regex pattern to validate against'
    required: true
    default: '^(feat|fix|chore|docs|refactor|test): .+$'
  fail-on-error:
    description: 'Fail the workflow if validation fails'
    required: false
    default: 'true'
outputs:
  is_valid:
    description: 'Whether the PR title is valid (true/false)'
runs:
  using: 'node20'
  main: 'index.js'
branding:
  icon: 'check-circle'
  color: 'green'

Notice the `runs` section uses `node20`. That’s the current recommended version. Don’t use `node12` or `node16` — they’re deprecated.

Step 2: Write the Action Logic

We’ll use `@actions/core` to read inputs, print logs, and set outputs. Here’s the `index.js`:

javascript
const core = require('@actions/core');
const github = require('@actions/github');

try {
  const pattern = core.getInput('pattern');
  const failOnError = core.getInput('fail-on-error') === 'true';
  const prTitle = github.context.payload.pull_request?.title;

  if (!prTitle) {
    core.setFailed('This action only works on pull_request events.');
    return;
  }

  const regex = new RegExp(pattern);
  const isValid = regex.test(prTitle);

  core.setOutput('is_valid', isValid ? 'true' : 'false');

  if (isValid) {
    core.info(`✅ PR title "${prTitle}" matches the pattern.`);
  } else {
    const message = `❌ PR title "${prTitle}" does not match pattern: ${pattern}`;
    if (failOnError) {
      core.setFailed(message);
    } else {
      core.warning(message);
    }
  }
} catch (error) {
  core.setFailed(error.message);
}

That’s it. 30 lines. This action reads the PR title from the event payload, checks it against your regex, and either passes or fails.

You can extend it easily. Want to add a comment on the PR? Use `@actions/github` to create an Octokit client and call the Issues API. Want to post a Slack message? Add the `axios` package and call a webhook.

Step 3: Test Locally (Yes, You Can)

Testing actions locally used to be a pain. Not anymore. Install `act` — a tool that runs GitHub Actions locally:

bash
# macOS
brew install act

# Linux / WSL
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

Create a test workflow `.github/workflows/test-action.yml` in your repository:

yaml
name: Test Custom Action
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./  # This references the root of the repo where action.yml is
        with:
          pattern: '^(feat|fix|chore): .+$'

Now run `act pull_request` in your repo. It will spin up a Docker container and execute your action against a simulated PR event.

**Pro tip:** Use `act -l` to list all available events and `act -j ` to run a specific job.

Step 4: Publish to GitHub Marketplace

Once you’re satisfied with the action, commit and push to a public repo on GitHub.

Then publish to the Marketplace:

1. Go to your repo on GitHub.
2. Click Releases → Create a new release.
3. Tag it with a semantic version (e.g., `v1.0.0`).
4. Check the box Publish this Action to the GitHub Marketplace.
5. Fill in the description and write a changelog.

After publishing, other repos can use your action with:

yaml
- uses: your-username/my-custom-action@v1

Pro tip: Consider using a major version tag like `v1` that points to the latest patch of `v1.x.x`. That way users get bug fixes without changing their workflow. You can do this by creating or moving the `v1` tag each release.

Real-World Example: Conventional Commit Validator

Let’s add one more feature to the PR title validator: automatically label the PR with the type of change detected (feat, fix, chore…). You need write permissions on the repo, so configure the action accordingly.

Update your `index.js` to add this section after validation:

javascript
const octokit = github.getOctokit(process.env.GITHUB_TOKEN);
const { owner, repo } = github.context.repo;
const prNumber = github.context.payload.pull_request.number;

const match = prTitle.match(/^(feat|fix|chore|docs|refactor|test)/);
if (match) {
  const label = match[1];
  await octokit.rest.issues.addLabels({
    owner,
    repo,
    issue_number: prNumber,
    labels: [`type: ${label}`]
  });
}

Don’t forget to add `GITHUB_TOKEN` to your action’s `env` in the workflow step. GitHub automatically injects it.

Measuring the Impact

We deployed this exact action across all client projects at ECOAAI. The numbers:

Our team in Ho Chi Minh City ships this kind of automation routinely. It’s not magic — it’s just knowing the right tool for the job.

Frequently Asked Questions

Can I build a Docker-based action instead of JavaScript?

Yes, but you only need Docker if your action requires a specific runtime environment (e.g., Python with `pandas`). JavaScript actions run natively on GitHub’s runners — faster startup, no image pull.

Should I use TypeScript for my action?

If your action is more than 50 lines, yes. TypeScript catches null reference errors at compile time, which is critical for actions that touch the GitHub API. Setup is quick: add `typescript`, `@types/node`, and `ts-jest` as dev dependencies, then compile to `index.js` before publishing.

How do I pass secrets to my action?

You don’t. Well, not directly. In the workflow file, map secrets to environment variables:

yaml
- name: Run custom action
  uses: ./
  env:
    SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }}

Your action reads `process.env.SLACK_WEBHOOK`. Keep secrets out of inputs — they’d be exposed in logs.

Can I reuse my action across private repos without publishing?

Absolutely. Reference it with `uses: owner/repo@v1` if the repo is private. You just need to grant access to the target repos via GitHub settings. No marketplace required.

Related: Vietnamese software developers — Learn more about how ECOA AI can help your team.

Related: Hire Elite Vietnamese Developers — Learn more about how ECOA AI can help your team.

Related: developers in Vietnam — Learn more about how ECOA AI can help your team.

Related: Vietnam development team — Learn more about how ECOA AI can help your team.

Related reading: Outsourcing software Done Right: The CTO’s Playbook for 2025