Introduction

While GitHub Actions provides thousands of pre-built actions via the Marketplace, sometimes you need something specific to your project. That’s where custom actions come in. A custom GitHub Action is a script or container you define to run as a step in a GitHub Actions workflow.

You can write your own action in JavaScript (Node.js), as a Docker container, or even just use shell scripts. In this post, we'll focus on creating a simple custom JavaScript-based action.

Why Write a Custom Action?

• Reusable logic: Use the same action across multiple projects or teams.
• Cleaner workflows: Move complex shell scripts into their own files.
• More control: Define exactly how your step behaves and what inputs/outputs it uses.
• Share with the community: Publish your action to the GitHub Marketplace for others to use.

Step 1: Create a New GitHub Repository

Create a new public or private GitHub repo. You can name it something like my-first-action.

Step 2: Create the Action File Structure

                  my-first-action/
                  ├── action.yml
                  ├── index.js
                  ├── package.json
                  

• action.yml — defines your action's metadata.
• index.js — contains the actual code logic.
• package.json — declares dependencies if needed.

Step 3: Define action.yml

                  name: "My First Action"
                  description: "A simple GitHub Action that prints a greeting."
                  inputs:
                    name:
                      description: "Name to greet"
                      required: true
                      default: "World"
                  runs:
                    using: "node16"
                    main: "index.js"
                    

Step 4: Write the JavaScript Code (index.js)

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

                        try {
                        const name = core.getInput('name');
                        console.log(`👋 Hello, ${name}!`);
                        } catch (error) {
                        core.setFailed(`Action failed: ${error.message}`);
                        }
                    

This action grabs an input called name and logs a greeting to the console.

Step 5: Install Dependencies

In your repo root, run:

                    npm init -y
                    npm install @actions/core
  

Step 6: Commit and Push Your Code

                  git add .
                  git commit -m "Add my first custom action"
                  git push origin main
                    

Step 7: Use Your Action in a Workflow

Now you can call your custom action from another repo (or the same one) using the GitHub username and repo path:

                  name: Custom Action Test
                  
                  on: [push]
                  
                  jobs:
                    greet:
                      runs-on: ubuntu-latest
                      steps:
                        - uses: actions/checkout@v3
                        - uses: username/my-first-action@main
                          with:
                            name: Steven
                    

Optional: Publish to the Marketplace

If your action might be useful to others, consider publishing it to the GitHub Marketplace. Just include a README.md explaining how to use it, and tag a release version (e.g., v1) in your repo.

Conclusion

Writing a custom GitHub Action is a powerful way to make your workflows cleaner, more modular, and more reusable. Once you've created your first action, you’ll be able to automate even more parts of your development process with precision and clarity. Start small, and soon you'll be writing actions that deploy apps, lint code, generate reports, or even send Slack messages.