Introduction

A powerful feature of GitHub Actions is the ability to create custom actions, which can be shared and reused across multiple projects, fostering collaboration and enhancing productivity.

In this article, I will discuss the types of custom actions you can build, and walk you through the process of creating your own custom actions.

Types of Custom Actions

In this chapter, I will explore the three main types of custom actions that can be built for GitHub Actions: Docker Container Actions, JavaScript Actions, and Composite Run Steps Actions. Each type has its advantages and use cases, which we will discuss in detail.

https://docs.github.com/en/actions/creating-actions/about-custom-actions

Docker Container Actions

Docker Container Actions are based on Docker images, making them an excellent choice for incorporating languages, tools, or environments not natively supported by the GitHub Actions runner. These actions run in a separate container, providing isolation from the host environment.

Advantages

• Supports any language or tool with a compatible Docker image
• Offers environment isolation, reducing the risk of conflicts between dependencies

Disadvantages

• Slower execution due to the overhead of starting a new container
• Requires Docker knowledge to create and maintain the Dockerfile

Use cases

• Running actions with specific language versions or tools not supported by GitHub Actions
• Ensuring dependencies don't conflict with the host environment

JavaScript Actions

JavaScript Actions are written in JavaScript or TypeScript and execute directly on the GitHub Actions runner. They offer better performance compared to Docker Container Actions, as they don't require starting a separate container.

Advantages

• Faster execution, since they run directly on the GitHub Actions runner
• Easier maintenance, as there is no need for a Dockerfile

Disadvantages

• Limited to JavaScript or TypeScript languages
• No environment isolation, which can lead to dependency conflicts

Use cases

• Building simple actions with minimal dependencies
• Creating actions that need to be executed quickly

Composite Run Steps Actions

Composite Run Steps Actions enable you to combine multiple steps into a single reusable action. They can include a mix of shell commands and other actions, making them suitable for creating reusable workflows with complex logic.

Advantages

• Can combine multiple steps and actions into a single unit
• Supports various shell commands and other GitHub Actions

Disadvantages

• Limited to shell commands and existing GitHub Actions
• Can become complex if not well-organized

Use cases

• Bundling several related steps to simplify workflow files
• Creating reusable pieces of workflows for use in multiple projects

Creating Your Custom Action

In this chapter, I will walk you through the process of creating your first custom action. We'll provide a step-by-step guide to developing the action, and testing it locally.

Developing the Action

1. Choose one of the custom action types (Docker Container, JavaScript, or Composite Run Steps) and create the necessary files for your action:

• For Docker Container Actions
  1. Create a Dockerfile in the root of your repository.
  2. Write the necessary Docker commands to set up the environment, install dependencies, and define the entry point for your action.

https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action

• For JavaScript Actions
  1. Initialize a new Node.js project with npm init or yarn init in the repository root.
  2. Install any required dependencies using npm install or yarn add.
  3. Create a src directory and write your action's JavaScript or TypeScript code.

https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action

• For Composite Run Steps Actions
  1. Create a steps.yml file in the root of your repository.
  2. Define the sequence of shell commands and other actions in the steps section of the YAML file.

https://docs.github.com/en/actions/creating-actions/creating-a-composite-action

2. Implement the functionality of your action according to its purpose and requirements. Make sure to handle input parameters and provide meaningful error messages when necessary.

Testing the Action Locally

1. Create a sample workflow in your repository to test your action. In the .github/workflows directory, create a new YAML file (e.g., test-action.yml).

2. Configure the sample workflow to use your custom action. For example:

name: Test My Custom Action

on:
  push:

jobs:
  test-action:
    runs-on: ubuntu-latest
    steps:
    - name: Check out repository
      uses: actions/checkout@v2

    - name: Run My Custom Action
      uses: ./  # Replace with your action's path
      with:
        input-param: "Example value"  # Replace with your action's input parameters

3. Commit your changes and push them to the remote repository. The sample workflow will automatically run on the push event, allowing you to observe the execution of your custom action.

References

https://docs.github.com/en/actions/creating-actions/about-custom-actions
https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action
https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action
https://docs.github.com/en/actions/creating-actions/creating-a-composite-action