Jinal Desai

GitHub Actions, with its robust automation capabilities, empowers developers to streamline their software development workflows. While GitHub provides a plethora of pre-built actions, there are times when you need to create your own custom GitHub Actions to address specific requirements or automate repetitive tasks. In this fourth article of our GitHub Actions series, we will delve into the intricate process of creating your very own reusable GitHub Actions. Additionally, we will explore comprehensive best practices for writing custom actions that are not only efficient but also maintainable and reliable. 

Introduction to Custom GitHub Actions

Custom GitHub Actions are modular units of automation that can be utilized across various repositories and workflows. They are defined using YAML and comprise one or more steps that perform distinct tasks. The creation of custom actions can significantly enhance workflow efficiency, elevate code quality, and save valuable development time. Let’s embark on this journey!

Prerequisites

Before we embark on the creation of custom actions, ensure you have the following prerequisites in place:

1. A GitHub repository where you plan to utilize custom action.
2. A foundational understanding of YAML and GitHub Actions.
3. A code editor of your preference.

Creating a Custom GitHub Action

Step 1: Establish a New Repository

Commence setting up a new GitHub repository to host your custom action. You can either utilize an existing repository or create a dedicated one specifically for actions. Initialize a new Git repository and construct a directory for your action, which we shall christen as `my-custom-action`.

mkdir my-custom-action
cd my-custom-action
git init

Step 2: Define Your Action

Within the `my-custom-action` directory, fabricate a YAML file named `action.yml`. This file will be the blueprint for your custom action. Here’s an illustrative example:

name: 'My Custom Action'
description: 'A custom GitHub Action'

runs:
  using: 'node12'
  main: 'main.js'

In this example, we specify the action’s name and description, set the runtime environment to Node.js 12, and designate `main.js` as the entry point.

Step 3: Create the Action Code

Next, generate the `main.js` file within the same directory. This file houses the logic for your custom action. As an example, let’s design a straightforward action that calculates the square of a number:

const inputNumber = parseInt(process.env.INPUT_NUMBER, 10);
const result = inputNumber * inputNumber;

console.log(`The square of ${inputNumber} is ${result}.`);

Step 4: Version and Release

To make your custom action accessible to others, version and release it. Commit your changes and create a new GitHub release within your repository. Tag this release with a version number (e.g., `v1.0.0`) to facilitate its use in workflows across various repositories.

Step 5: Utilize Your Custom Action

To integrate your custom action into a GitHub Actions workflow, append the following YAML code to your workflow configuration file (e.g., `.github/workflows/main.yml`):

name: Calculate Square

on:
  push:
    branches:
      - main

jobs:
  calculate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Run Custom Action
        id: square
        uses: /@v1.0.0
        with:
          number: 5

Substitute “ and “ with your GitHub username and repository name. The `uses` field points to your custom action, tagged with the version number you previously released. Additionally, we pass an input parameter `number` to the action with the value `5`.

Best Practices for Writing Custom Actions

As you craft your custom GitHub Actions, adhere to the following best practices:

1. Modularity: Keep your actions granular and focused on specific tasks to enhance reusability and maintainability.

2. Parameterization: Allow users to customize your action’s behavior through inputs and outputs. Leverage the `inputs` and `outputs` sections in your `action.yml` file.

3. Documentation: Furnish detailed and comprehensive documentation for your action. Include usage examples and thorough input/output descriptions.

4. Testing: Employ testing to validate that your action functions as intended. Utilize GitHub’s testing features to automate this validation process.

5. Versioning: Adhere to semantic versioning (SemVer) to signify changes and compatibility with previous action versions.

6. Error Handling: Implement robust error handling and logging to simplify troubleshooting.

7. Third-Party Tools: When incorporating third-party tools or libraries, consider version pinning to prevent unforeseen changes.

8. Security: Ensure that your action doesn’t expose sensitive information and is free from vulnerabilities.

9. Performance: Optimize your action for performance to prevent workflow bottlenecks.

Conclusion

The creation of custom GitHub Actions empowers you to build efficient and reusable automation tailored to your specific needs. By following best practices and offering well-documented, modular actions, you can contribute to the GitHub Actions ecosystem while streamlining development processes for yourself and the broader community. Begin with small, focused actions, iterate, and soon, you’ll possess a valuable collection of custom actions designed to enhance your development workflows. Happy automating!