Custom Action Development

Custom Action Development

In the world of GitHub Actions, while there are countless pre-built actions available in the GitHub Marketplace, there are scenarios where you may need a solution tailored to your specific requirements. This is where custom GitHub Actions come into play. In this lesson, we'll explore how to create, test, and publish your own custom actions, providing you with the flexibility to streamline your CI/CD workflows.

What is a Custom GitHub Action?

A custom GitHub Action is a reusable piece of code that you can integrate into your GitHub workflows. Unlike pre-built actions, custom actions allow you to define your logic, making it possible to perform tasks that are unique to your project or organization.

Why Develop Custom Actions?

There are several reasons you might want to create a custom action: - Specific Functionality: You may need to implement a functionality that is not available in existing actions. - Reusability: Custom actions can be reused across multiple workflows or repositories, promoting DRY (Don't Repeat Yourself) principles. - Encapsulation: They allow you to encapsulate complex logic, making your workflows cleaner and easier to maintain.

Structure of a Custom Action

A custom GitHub Action can be defined using JavaScript, Docker, or as a composite action. Here’s a breakdown of each type:

1. JavaScript Actions: These are Node.js applications that run directly in the GitHub Actions environment.
2. Docker Actions: These run in a Docker container and can be used for more complex tasks that require specific environments or dependencies.
3. Composite Actions: These are a combination of existing actions and shell commands, allowing you to create a workflow from multiple actions.

Creating a Simple JavaScript Action

Let’s create a simple JavaScript action that prints a greeting message. The following steps outline the process:

Step 1: Set Up Your Action Directory

Create a new directory for your action:

mkdir greeting-action
cd greeting-action

Step 2: Initialize Node.js Project

Initialize a new Node.js project:

npm init -y

This command creates a package.json file, which will manage your dependencies.

Step 3: Create the Action File

Create an index.js file in your action directory:

// index.js
const core = require('@actions/core');

try {
  const name = core.getInput('name');
  core.info(`Hello, ${name}!`);
} catch (error) {
  core.setFailed(error.message);
}

Explanation: This code imports the @actions/core package, retrieves an input parameter named name, and prints a greeting message. If an error occurs, it sets the action as failed.

Step 4: Define Action Metadata

Create an action.yml file that contains metadata about your action:

name: 'Greeting Action'
description: 'A simple action that greets the user'
inputs:
  name:
    description: 'The name to greet'
    required: true
runs:
  using: 'node'
  main: 'index.js'

Explanation: The action.yml file defines the action's name, description, inputs, and how to execute it.

Step 5: Running Your Action Locally

To test your action locally, you can use the act tool, which simulates the GitHub Actions environment on your machine. Install it and run:

act -e event.json

Create an event.json file to simulate an event that triggers the action:

{
  "inputs": {
    "name": "World"
  }
}

This command will execute your action and print Hello, World!.

Creating a Docker Action

Now, let's create a Docker-based action that performs a similar greeting task. This method is particularly useful when your action has dependencies that need to be installed in a specific environment.

Step 1: Create a Dockerfile

Create a Dockerfile in your action directory:

FROM node:14

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install

COPY . .

ENTRYPOINT [ "node", "index.js" ]

Explanation: This Dockerfile sets up a Node.js environment, installs dependencies, and specifies the command to run your action.

Step 2: Update Action Metadata

Update your action.yml to reflect that it’s a Docker action:

name: 'Greeting Docker Action'
description: 'A Docker action that greets the user'
inputs:
  name:
    description: 'The name to greet'
    required: true
runs:
  using: 'docker'
  image: 'Dockerfile'

Testing Your Docker Action

You can test your Docker action similarly to the JavaScript action using the act tool. Ensure your Docker environment is set up correctly, and run:

act -e event.json

Publishing Your Action

Once your action is ready and tested, you can publish it to the GitHub Marketplace: 1. Push your action to a GitHub repository. 2. Navigate to the repository's settings and select "Actions". 3. Fill out the necessary details and publish your action.

Best Practices for Custom Actions

• Documentation: Clearly document your action, including its inputs, outputs, and examples of usage.
• Versioning: Use semantic versioning to manage changes and ensure users can rely on specific versions of your action.
• Testing: Write tests for your action to ensure it behaves as expected. Consider using testing frameworks like Jest for JavaScript actions.
• Error Handling: Implement robust error handling to ensure that your action fails gracefully and provides useful feedback.

Performance Considerations

When developing custom actions, consider the following performance aspects: - Cold Starts: Actions that run in Docker containers may experience cold starts. Optimize your Docker image size to reduce start-up time. - Caching Dependencies: Use caching strategies to speed up dependency installation, especially for Docker actions. - Minimize API Calls: If your action interacts with external APIs, minimize calls to reduce latency and potential rate-limiting issues.

Common Interview Questions

1. What are the different types of GitHub Actions?
   - GitHub Actions can be JavaScript actions, Docker actions, or composite actions.
2. How do you handle secrets in custom actions?
   - Secrets can be accessed through the process.env object in JavaScript actions or as environment variables in Docker actions.
3. What is the purpose of the action.yml file?
   - The action.yml file defines the metadata for the action, including its inputs, outputs, and execution method.

Mini Project: Create a Custom Action to Send Notifications

For this mini-project, create a custom action that sends notifications (e.g., via email or Slack) when a workflow fails. You can use a service like SendGrid or Slack API to implement this.

1. Define inputs for the action, such as recipient email or Slack channel.
2. Implement the logic to send a notification when the action is triggered.
3. Test your action locally and publish it to GitHub.

Key Takeaways

• Custom GitHub Actions allow you to create tailored functionality for your workflows.
• You can implement actions using JavaScript, Docker, or as composite actions.
• Proper documentation, versioning, and error handling are essential for maintainable actions.
• Testing your actions ensures reliability and performance.

In the next lesson, we will explore Managing Workflow Permissions, where we will discuss how to control access to your workflows and actions, ensuring security and compliance in your CI/CD processes.

Exercises

1. Create a JavaScript Action: Develop a JavaScript action that takes a number as input and returns its square.
2. Docker Action: Modify the previous exercise to create a Docker action that squares a number.
3. Publish Your Action: Push your JavaScript action to a GitHub repository and publish it to the GitHub Marketplace.
4. Error Handling: Enhance your action to handle invalid input gracefully and provide meaningful error messages.
5. Mini Project: Implement a custom action that sends a message to a Slack channel when a GitHub workflow fails.

Practical Assignment

Create a custom GitHub Action that retrieves the latest commit message from a repository and posts it to a specified Slack channel. Include error handling for cases where the repository does not exist or the Slack API call fails.

• Custom GitHub Actions provide tailored solutions for specific needs in CI/CD workflows.
• Actions can be created using JavaScript, Docker, or as composite actions.
• Proper documentation and versioning are crucial for maintainability.
• Testing and error handling ensure reliability in custom actions.
• Performance considerations include optimizing cold starts and minimizing API calls.